[docs] added touchups to readme.md

.dockerignore

@@ -0,0 +1,7 @@
+__pycache__
+venv
+env
+.github
+docs
+scripts
+tests

.env.example

@@ -0,0 +1,5 @@
+OPENAI_API_KEY=''
+GEMINI_API_KEY=''
+ANTHROPIC_API_KEY=''
+GROQ_API_KEY=''
+HF_AUTH_TOKENS=''

.github/workflows/python-app.yml

@@ -0,0 +1,59 @@
+# This workflow will install Python dependencies, run tests and lint with a single version of Python
+# For more information see: https://docs.github.com/en/actions/automating-builds-and-tests/building-and-testing-python
+
+name: AIOS application
+
+on:
+  push:
+    branches: [ "main" ]
+  pull_request:
+    branches: [ "main" ]
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+
+    runs-on: ubuntu-latest
+
+    steps:
+    - uses: actions/checkout@v4
+    - name: Set up Python 3.10
+      uses: actions/setup-python@v3
+      with:
+        python-version: "3.10"
+    - name: Install dependencies
+      run: |
+        python -m pip install --upgrade pip
+        if [ -f requirements.txt ]; then pip install -r requirements.txt; fi
+    - name: Git Clone Action
+  # You may pin to the exact commit or the version.
+  # uses: sudosubin/git-clone-action@8a93ce24d47782e30077508cccacf8a05a891bae
+      uses: sudosubin/[email protected]
+      with:
+        # Repository owner and name. Ex: sudosubin/git-clone-action
+        repository: agiresearch/Cerebrum # optional, default is ${{ github.repository }}
+        path: Cerebrum
+    - name: Install cerebrum special edition
+      run: |
+        python -m pip install -e Cerebrum/
+    - name: Run AIOS kernel in background
+      run: |
+            bash runtime/launch_kernel.sh  &>logs &
+
+    - name: run the run-agent code
+      run: |
+        curl localhost:8000
+        export GEMINI_API_KEY=AIzaSyDKcFCc0UjbS_bliq78luOwcSGYJedlNK8
+        run-agent --llm_name gemini-1.5-flash --llm_backend google --agent_name_or_path demo_author/demo_agent --task "Tell me what is core idea of AIOS" --aios_kernel_url http://localhost:8000 
+        # >>logs 2>&1
+    - name: Upload a Build Artifact
+      uses: actions/[email protected]
+      with:
+        # Artifact name
+        name: logs
+        # A file, directory or wildcard pattern that describes what to upload
+        path: logs
+
+

.github/workflows/test_ollama.yml

@@ -0,0 +1,135 @@
+# This workflow will install Python dependencies, run tests and lint with a single version of Python
+# For more information see: https://docs.github.com/en/actions/automating-builds-and-tests/building-and-testing-python
+
+name: AIOS Application
+
+on:
+  push:
+    branches: [ "main" ]
+  pull_request:
+    branches: [ "main" ]
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+
+    steps:
+    - uses: actions/checkout@v4
+      with:
+        ref: main  # Specify main branch
+
+    - name: Set up Python 3.10
+      uses: actions/setup-python@v3
+      with:
+        python-version: "3.10"
+
+    - name: Install dependencies
+      run: |
+        python -m pip install --upgrade pip
+        if [ -f requirements.txt ]; then pip install -r requirements.txt; fi
+
+    - name: Git Clone Action
+      # You may pin to the exact commit or the version.
+      # uses: sudosubin/git-clone-action@8a93ce24d47782e30077508cccacf8a05a891bae
+      uses: sudosubin/[email protected]
+      with:
+        # Repository owner and name. Ex: sudosubin/git-clone-action
+        repository: agiresearch/Cerebrum
+        path: Cerebrum
+
+    - name: Install cerebrum special edition
+      run: |
+        python -m pip install -e Cerebrum/
+
+    - name: Download and install Ollama
+      run: |
+        curl -fsSL https://ollama.com/install.sh | sh
+
+    - name: Pull Ollama models
+      run: |
+        ollama pull llama3:8b
+
+    - name: Run Ollama serve
+      run: |
+        ollama serve 2>&1 | tee ollama-llm.log
+
+    - name: Run AIOS kernel in background
+      run: |
+        bash runtime/launch_kernel.sh &>logs &
+        KERNEL_PID=$!
+
+        # Set maximum wait time (20 seconds)
+        max_wait=20
+        start_time=$SECONDS
+
+        # Dynamically check if the process is running until it succeeds or times out
+        while true; do
+          if ! ps -p $KERNEL_PID > /dev/null; then
+            echo "Kernel process died. Checking logs:"
+            cat logs
+            exit 1
+          fi
+
+          if nc -z localhost 8000; then
+            if curl -s http://localhost:8000/health > /dev/null; then
+              echo "Kernel successfully started and healthy"
+              break
+            fi
+          fi
+
+          # Check if timed out
+          elapsed=$((SECONDS - start_time))
+          if [ $elapsed -ge $max_wait ]; then
+            echo "Timeout after ${max_wait} seconds. Kernel failed to start properly."
+            cat logs
+            exit 1
+          fi
+
+          echo "Waiting for kernel to start... (${elapsed}s elapsed)"
+          sleep 1
+        done
+
+    - name: Run the run-agent code
+      run: |
+        # Run agent and capture exit code
+        run-agent \
+          --llm_name llama3:8b \
+          --llm_backend ollama \
+          --agent_name_or_path demo_author/demo_agent \
+          --task "Tell me what is core idea of AIOS" \
+          --aios_kernel_url http://localhost:8000 \
+          2>&1 | tee agent.log
+
+        # Check for specific error patterns in the log
+        if grep -q "Failed to initialize client: 500 Server Error" agent.log; then
+          echo "Error: LLM initialization failed. Please check your API key configuration."
+          exit 1
+        fi
+
+        # Check if the agent actually completed successfully
+        if ! grep -q "Final Result:" agent.log; then
+          echo "Error: Agent did not complete successfully"
+          exit 1
+        fi
+
+    - name: Upload a Build Artifact
+      if: always()  # Upload logs even if job fails
+      uses: actions/[email protected]
+      with:
+        name: logs
+        path: |
+          logs
+          agent.log
+
+    - name: Collect debug information
+      if: failure()
+      run: |
+        echo "=== Kernel Logs ==="
+        cat logs
+        echo "=== Environment Variables ==="
+        env | grep -i api_key || true
+        echo "=== Process Status ==="
+        ps aux | grep kernel

.gitignore

@@ -203,4 +203,7 @@ next-env.d.ts
 metagpt
 workspace
 
-cache
+cache
+
+# Ignore configuration files
+aios/config/config.yaml

Dockerfile

@@ -0,0 +1,14 @@
+FROM python:3.11.8-slim-bullseye
+
+ENV PYTHONUNBUFFERED True
+
+ENV APP_HOME /app
+WORKDIR $APP_HOME
+COPY . ./
+
+ENV PORT 8000
+
+RUN pip install --no-cache-dir -r requirements.txt
+
+# As an example here we're running the web service with one worker on uvicorn.
+CMD exec uvicorn server:app --host 0.0.0.0 --port ${PORT} --workers 1

README.md

@@ -17,13 +17,13 @@ AIOS is the AI Agent Operating System, which embeds large language model (LLM) i
 <img src="docs/assets/aios-figs/architecture.jpg">
 </p>
 
-The AIOS system is comprised of two key components: the AIOS kernel and the AIOS-Agent SDK.
+The AIOS system is comprised of two key components: the AIOS kernel and the AIOS SDK.
 The AIOS kernel acts as an abstraction layer over the operating system kernel, managing various resources that agents require, such as LLM, memory, storage and tool. 
-The AIOS-Agent SDK is designed for agent users and developers, enabling them to build and run agent applications by interacting with the AIOS kernel.
-AIOS kernel is the current repository and AIOS-Agent SDK can be found at [here](htgithub.com/agiresearch/Cerebrum)
+The AIOS SDK is designed for agent users and developers, enabling them to build and run agent applications by interacting with the AIOS kernel.
+AIOS kernel is the current repository and AIOS SDK can be found at [here](https://github.com/agiresearch/Cerebrum)
 
 ### Modules and Connections
-Below shows how agents utilize AIOS-Agent SDK to interact with AIOS kernel and how AIOS kernel receives agent queries and leverage the chain of syscalls that are scheduled and dispatched to run in different modules. 
+Below shows how agents utilize AIOS SDK to interact with AIOS kernel and how AIOS kernel receives agent queries and leverage the chain of syscalls that are scheduled and dispatched to run in different modules. 
 <p align="center">
 <img src="docs/assets/aios-figs/details.png">
 </p>
@@ -41,6 +41,74 @@ Below shows how agents utilize AIOS-Agent SDK to interact with AIOS kernel and h
 - **[2024-03-25]** ✈️ Our paper [AIOS: LLM Agent Operating System](https://arxiv.org/abs/2403.16971) is released!
 - **[2023-12-06]** 📋 After several months of working, our perspective paper [LLM as OS, Agents as Apps: Envisioning AIOS, Agents and the AIOS-Agent Ecosystem](https://arxiv.org/abs/2312.03815) is officially released.
 
+## Different deployment modes of AIOS
+Here are some key notations that are required to know before introducing the different modes of AIOS. 
+- **AHM (Agent Hub Machine)**: Central server that hosts the agent marketplace/repository where users can publish, download, and share agents. Acts as the distribution center for all agent-related resources.
+- **AUM (Agent UI Machine)**: Client machine that provides user interface for interacting with agents. Can be any device from mobile phones to desktops that supports agent visualization and control.
+- **ADM (Agent Development Machine)**: Development environment where agent developers write, debug and test their agents. Requires proper development tools and libraries.
+- **ARM (Agent Running Machine)**: Execution environment where agents actually run and perform tasks. Needs adequate computational resources for agent operations.
+
+The following parts introduce different modes of deploying AIOS. **Currently, AIOS already supports Mode 1 and Mode 2, other modes with new features are still ongoing.**
+
+### Mode 1 (Local Kernel Mode)
+
+<p align="center">
+<img src="docs/assets/aios-figs/stage1.png" width=300>
+</p>
+
+- Features:
+  - For agent users: They can download agents from agent hub from Machine B and run agents on Machine A. 
+  - For agent developers: They can develop and test agents in Machine A and can upload agents to agent hub on Machine B.
+
+### Mode 2 (Remote Kernel Mode)
+
+<p align="center">
+<img src="docs/assets/aios-figs/stage2.png" width=300>
+</p>
+
+- Features: 
+  - Remote use of agents: Agent users / developers can use agents on Machine B, which is different from the development and running machine (Machine A).  
+  - Benefit users who would like to use agents on resource-restricted machine (e.g., mobile device or edge device)
+
+### Mode 2.5 (Remote Kernel Dev Mode)
+
+<p align="center">
+<img src="docs/assets/aios-figs/stage2.5.png" width=300>
+</p>
+
+- Features:
+  - Remote development of agents: Agent developers can develop their agents on Machine B while running and testing their agents in Machine A. Benefit developers who would like to develop agents on resource-restricted machine (e.g., mobile device or edge device)
+- Critical technique:
+  - Packaging and agent transmission on different machines for distributed agent development and testing
+
+### Mode 3 (Personal Remote Kernel Mode)
+
+<p align="center">
+<img src="docs/assets/aios-figs/stage3.png" width=800>
+</p>
+
+- Ongoing Features:
+  - Each user/developer can have their personal AIOS with long-term persistent data as long as they have registered account in the AIOS ecosystem
+  - Their personal data can be synced to different machines with the same account
+
+- Critical techniques:
+  - User account registration and verification mechanism
+  - Persistent personal data storage for each user's AIOS
+  - Synchronization for different AIOS instances on different devices within the same account
+  - Data privacy mechanism
+
+### Mode 4 (Personal Remote Virtual Kernel Mode)
+
+<p align="center">
+<img src="docs/assets/aios-figs/stage4.png" width=800>
+</p>
+
+- Ongoing Features:
+  - Different user/developer’s personal AIOS kernels can co-exist in the same physical machine through virtualization
+- Critical techniques:
+  - Virtualization of different AIOS kernel instances in the same machine
+  - Scheduling and resource allocation mechanism for different virtual machines located in the same machine
+
 
 ## ✈️ Getting Started
 Please see our ongoing [documentation](https://docs.aios.foundation/) for more information.
@@ -76,11 +144,13 @@ To obtain these API keys:
 Git clone AIOS kernel
 ```bash
 git clone https://github.com/agiresearch/AIOS.git
-cd AIOS && git checkout v0.2.0.beta
+cd AIOS
+git checkout v.20 # don't do this unless you're testing
 ```
 Create venv environment (recommended)
 ```bash
-python3.x -m venv venv # Only support for Python 3.10 and 3.11
+python3.x --version # Check if it is 3.10 or 3.11
+python3.x -m venv venv
 source venv/bin/activate
 ```
 or create conda environment
@@ -109,15 +179,23 @@ pip install -r requirements.txt
 <!-- Note: Please use `launch.py` for the WebUI, or `agent_repl.py` for the TUI. -->
 #### Configurations
 ##### Use with OpenAI API
-You need to get your OpenAI API key from https://platform.openai.com/api-keys.
+You need to get your OpenAI API key from https://platform.openai.com/api-keys. Note that API keys **cost money**.
 Then set up your OpenAI API key as an environment variable
 
 ```bash
 export OPENAI_API_KEY=<YOUR_OPENAI_API_KEY>
 ```
 
+##### Use with Anthropic API
+You need to get your Anthropic API key from https://console.anthropic.com/settings/keys.
+Then set up your Anthropic API key as an environment variable
+
+```bash
+export ANTHROPIC_API_KEY=<YOUR_ANTHROPIC_API_KEY>
+```
+
 ##### Use with Gemini API
-You need to get your Gemini API key from https://ai.google.dev/gemini-api
+You need to get your Gemini API key from https://ai.google.dev/gemini-api. Gemini is a free cloud LLM provider.
 
 ```bash
 export GEMINI_API_KEY=<YOUR_GEMINI_API_KEY>
@@ -178,13 +256,18 @@ or you can pass the `CUDA_VISIBLE_DEVICES` as the prefix
 #### Launch AIOS
 After you setup your keys or environment parameters, then you can follow the instructions below to start.
 
-First, you need to start the AIOS kernel by running the following commands
-
-```
+Start AIOS by running:
+```bash
 bash runtime/launch_kernel.sh
 ```
 
-Then you can start the client provided by the AIOS-Agent SDK either in the terminal or in the WebUI. The instructions can be found at [here](https://github.com/agiresearch/Cerebrum)
+**Note:** If you need to specify `python3.10`, `python3.11`, `python3`, etc. then run the command in the script manually:
+
+```bash
+python3.x -m uvicorn runtime.kernel:app --host 0.0.0.0 
+```
+
+Then you can start the client provided by the AIOS SDK either in the terminal or in the WebUI. The instructions can be found at [here](https://github.com/agiresearch/Cerebrum)
 
 
 ### Supported Agent Frameworks