Merge branch 'master' into feature/role-generation

.github/actions/camel_install/action.yml

@@ -0,0 +1,29 @@
+name: 'camel_install'
+description: 'Setup python environment and install dependencies for CAMEL by poetry.'
+inputs:
+  python-version:
+    description: 'Python version.'
+    required: true
+    default: '3.8'
+runs:
+  using: "composite"
+  steps:
+    - name: Set up Python
+      uses: actions/setup-python@v3
+      with:
+        python-version: '${{ inputs.python-version }}'
+    - name: Install poetry
+      uses: abatilo/actions-poetry@v2
+    - name: Setup poetry virtual environment
+      run: |
+        poetry config virtualenvs.create true --local
+        poetry config virtualenvs.in-project true --local
+      shell: bash
+    - uses: actions/cache@v3
+      name: Cache for the virtual environment based on poetry.lock
+      with:
+        path: ./.venv
+        key: venv-${{ hashFiles('poetry.lock') }}
+    - name: Install the project dependencies
+      run: poetry install --with dev,docs -E all
+      shell: bash

.github/workflows/documentation.yaml → .github/workflows/documentation.yml

@@ -14,23 +14,10 @@ jobs:
 
     steps:
     - uses: actions/checkout@v3
-    - name: Set up Python 3.8
-      uses: actions/setup-python@v3
+    - name: Set up Python environment and install dependencies
+      uses: ./.github/actions/camel_install
       with:
         python-version: "3.8"
-    - name: Install poetry
-      uses: abatilo/actions-poetry@v2
-    - name: Setup poetry virtual environment
-      run: |
-        poetry config virtualenvs.create true --local
-        poetry config virtualenvs.in-project true --local
-    - uses: actions/cache@v3
-      name: Cache for the virtual environment based on pyproject.toml
-      with:
-        path: ./.venv
-        key: ${{ runner.os }}-venv-docs-${{ hashFiles('pyproject.toml') }}
-    - name: Install the project dependencies
-      run: poetry install --with docs -E all
     - name: Sphinx build
       run: |
         cd docs

.github/workflows/linting.yml

@@ -0,0 +1,27 @@
+name: Linting
+
+on:
+  push:
+    branches:
+      - master
+  pull_request:
+  merge_group:
+
+concurrency:
+  cancel-in-progress: ${{ startsWith(github.ref, 'refs/pull/') }}
+  group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}-${{ startsWith(github.ref, 'refs/pull/') || github.run_number }}
+
+jobs:
+  linting:
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v3
+    - name: Set up Python environment and install dependencies
+      uses: ./.github/actions/camel_install
+      with:
+        python-version: "3.8"
+    - name: Run mypy checks
+      run: |
+        poetry run mypy --install-types --non-interactive --namespace-packages -p camel
+        poetry run mypy --install-types --non-interactive --namespace-packages -p test
+        poetry run mypy --install-types --non-interactive --namespace-packages -p apps

.github/workflows/pytest_apps.yml

@@ -19,23 +19,10 @@ jobs:
 
     steps:
     - uses: actions/checkout@v3
-    - name: Set up Python 3.8
-      uses: actions/setup-python@v3
+    - name: Set up Python environment and install dependencies
+      uses: ./.github/actions/camel_install
       with:
         python-version: "3.8"
-    - name: Install poetry
-      uses: abatilo/actions-poetry@v2
-    - name: Setup poetry virtual environment
-      run: |
-        poetry config virtualenvs.create true --local
-        poetry config virtualenvs.in-project true --local
-    - uses: actions/cache@v3
-      name: Cache for the virtual environment based on pyproject.toml
-      with:
-        path: ./.venv
-        key: ${{ runner.os }}-venv-${{ hashFiles('pyproject.toml') }}
-    - name: Install the project dependencies
-      run: poetry install --with dev -E all
     - name: Run pytest
       env:
         OPENAI_API_KEY: "${{ secrets.OPENAI_API_KEY }}"
@@ -47,23 +34,10 @@ jobs:
 
     steps:
     - uses: actions/checkout@v3
-    - name: Set up Python 3.8
-      uses: actions/setup-python@v3
+    - name: Set up Python environment and install dependencies
+      uses: ./.github/actions/camel_install
       with:
         python-version: "3.8"
-    - name: Install poetry
-      uses: abatilo/actions-poetry@v2
-    - name: Setup poetry virtual environment
-      run: |
-        poetry config virtualenvs.create true --local
-        poetry config virtualenvs.in-project true --local
-    - uses: actions/cache@v3
-      name: Cache for the virtual environment based on pyproject.toml
-      with:
-        path: ./.venv
-        key: ${{ runner.os }}-venv-${{ hashFiles('pyproject.toml') }}
-    - name: Install the project dependencies
-      run: poetry install --with dev -E all
     - name: Run pytest
       env:
         OPENAI_API_KEY: "${{ secrets.OPENAI_API_KEY }}"

.github/workflows/pytest_package.yml

@@ -13,88 +13,42 @@ permissions:
   contents: read
 
 jobs:
-  pytest_package_test:
 
+  pytest_package_fast_test:
     runs-on: ubuntu-latest
-
     steps:
     - uses: actions/checkout@v3
-    - name: Set up Python 3.8
-      uses: actions/setup-python@v3
+    - name: Set up Python environment and install dependencies
+      uses: ./.github/actions/camel_install
       with:
         python-version: "3.8"
-    - name: Install poetry
-      uses: abatilo/actions-poetry@v2
-    - name: Setup poetry virtual environment
-      run: |
-        poetry config virtualenvs.create true --local
-        poetry config virtualenvs.in-project true --local
-    - uses: actions/cache@v3
-      name: Cache for the virtual environment based on pyproject.toml
-      with:
-        path: ./.venv
-        key: ${{ runner.os }}-venv-${{ hashFiles('pyproject.toml') }}
-    - name: Install the project dependencies
-      run: poetry install --with dev -E all
     - name: Run pytest
       env:
         OPENAI_API_KEY: "${{ secrets.OPENAI_API_KEY }}"
-      run: poetry run pytest test/
-
-
-  pytest_package_full_test:
+      run: poetry run pytest --fast-test-mode test/
 
+  pytest_package_llm_test:
     runs-on: ubuntu-latest
-
     steps:
     - uses: actions/checkout@v3
-    - name: Set up Python 3.8
-      uses: actions/setup-python@v3
+    - name: Set up Python environment and install dependencies
+      uses: ./.github/actions/camel_install
       with:
         python-version: "3.8"
-    - name: Install poetry
-      uses: abatilo/actions-poetry@v2
-    - name: Setup poetry virtual environment
-      run: |
-        poetry config virtualenvs.create true --local
-        poetry config virtualenvs.in-project true --local
-    - uses: actions/cache@v3
-      name: Cache for the virtual environment based on pyproject.toml
-      with:
-        path: ./.venv
-        key: ${{ runner.os }}-venv-${{ hashFiles('pyproject.toml') }}
-    - name: Install the project dependencies
-      run: poetry install --with dev -E all
     - name: Run pytest
       env:
         OPENAI_API_KEY: "${{ secrets.OPENAI_API_KEY }}"
-      run: poetry run pytest --full-test-mode test/
-
-
-  pytest_package_fast_test:
+      run: poetry run pytest --llm-test-only test/
 
+  pytest_package_very_slow_test:
     runs-on: ubuntu-latest
-
     steps:
     - uses: actions/checkout@v3
-    - name: Set up Python 3.8
-      uses: actions/setup-python@v3
+    - name: Set up Python environment and install dependencies
+      uses: ./.github/actions/camel_install
       with:
         python-version: "3.8"
-    - name: Install poetry
-      uses: abatilo/actions-poetry@v2
-    - name: Setup poetry virtual environment
-      run: |
-        poetry config virtualenvs.create true --local
-        poetry config virtualenvs.in-project true --local
-    - uses: actions/cache@v3
-      name: Cache for the virtual environment based on pyproject.toml
-      with:
-        path: ./.venv
-        key: ${{ runner.os }}-venv-${{ hashFiles('pyproject.toml') }}
-    - name: Install the project dependencies
-      run: poetry install --with dev -E all
     - name: Run pytest
       env:
         OPENAI_API_KEY: "${{ secrets.OPENAI_API_KEY }}"
-      run: poetry run pytest --fast-test-mode test/
+      run: poetry run pytest --very-slow-test-only test/

.gitignore

@@ -104,7 +104,7 @@ ipython_config.py
 #   This is especially recommended for binary packages to ensure reproducibility, and is more
 #   commonly ignored for libraries.
 #   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
-poetry.lock
+# poetry.lock
 
 # pdm
 #   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.

CONTRIBUTING.md

@@ -84,6 +84,10 @@ To verify that everything is set up correctly, run `pytest .` This will ensure t
 
 ## Common Actions 🔄
 
+### Update dependencies
+
+Whenever you add, update, or delete any dependencies in `pyproject.toml`, please run `poetry lock` to synchronize the dependencies with the lock file.
+
 ### Linting & Formatting ✨
 
 ```bash
@@ -133,7 +137,7 @@ pytest .
 
 To quickly run only local isolated unit and integration tests:
 ```bash
-pytest -m "not model_backend and not slow" .
+pytest --fast-test-mode .
 ```
 
 If you're developing with VSCode, make sure to create a `.env` file in the repository root and include your OpenAI API key:

README.md

@@ -151,6 +151,56 @@ python examples/ai_society/role_playing.py
 
 Please note that the environment variable is session-specific. If you open a new terminal window or tab, you will need to set the API key again in that new session.
 
+
+## Use Open-Source Models as Backends
+
+The basic workflow of using an open-sourced model as the backend is based on an external server running LLM inference service, e.g. during the development we chose [FastChat](https://github.com/lm-sys/FastChat) to run the service. 
+
+We do not fix the choice of server to decouple the implementation of any specific LLM inference server with CAMEL (indicating the server needs to be deployed by the user himself). But the server to be deployed must satisfy that **it supports OpenAI-compatible APIs, especially the method `openai.ChatCompletion.create`**.
+
+Here are some instructions for enabling open-source backends, where we use the [FastChat](https://github.com/lm-sys/FastChat) and a LLaMA2-based model ([`meta-llama/Llama-2-7b-chat-hf`](https://huggingface.co/meta-llama/Llama-2-7b-chat-hf)) in the example. Please install FastChat in advance following their installation guidance.
+
+1. Before running CAMEL, we should firstly launch FastChat server following the guidance on https://github.com/lm-sys/FastChat/blob/main/docs/openai_api.md. The instructions summarized below should be kept running **in separate processes**:
+
+```sh
+# Launch the controller
+python -m fastchat.serve.controller
+
+# Launch the model worker(s)
+python3 -m fastchat.serve.model_worker --model-path meta-llama/Llama-2-7b-chat-hf
+
+# Launch the RESTful API server
+python3 -m fastchat.serve.openai_api_server --host localhost --port 8000
+```
+
+2. After observing the controller successfully receiving the heart beat signal from the worker, the server should be ready for use at http://localhost:8000/v1. 
+
+3. Then we can try on running `role_playing_with_open_source_model.py`, where each agent in this example is initialized with specifying the `model_path` and `server_url`, similar to the example code below:
+
+```python
+system_message = # ...
+
+agent_kwargs = dict(
+    model=model_type,
+    model_config=OpenSourceConfig(
+        model_path="meta-llama/Llama-2-7b-chat-hf",
+        server_url="http://localhost:8000/v1",
+    ),
+)
+
+agent = ChatAgent(
+    system_message,
+    **agent_kwargs,
+)
+```
+
+### Supported Models
+
+- LLaMA2-based models
+  - example: [meta-llama/Llama-2-7b-chat-hf](https://huggingface.co/meta-llama/Llama-2-7b-chat-hf)
+- Vicuna-based models
+  - example: [lmsys/vicuna-7b-v1.5](https://huggingface.co/lmsys/vicuna-7b-v1.5)
+
 ## Data (Hosted on Hugging Face)
 | Dataset | Chat format | Instruction format | Chat format (translated) |
 | -- | -- | -- | -- |