open-swarm 0.1.1743070217__tar.gz → 0.1.1743362777__tar.gz

open_swarm-0.1.1743362777/.gitignore

@@ -0,0 +1,197 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+db.sqlite3-*
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+#.python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# UV
+#   Similar to Pipfile.lock, it is generally recommended to include uv.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#uv.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   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
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#pdm.lock
+#   pdm stores project-wide configurations in .pdm.toml, but it is recommended to not include it
+#   in version control.
+#   https://pdm.fming.dev/latest/usage/project/#working-with-version-control
+.pdm.toml
+.pdm-python
+.pdm-build/
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#  JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#  be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#  and can be added to the global gitignore or merged into this file.  For a more nuclear
+#  option (not recommended) you can uncomment the following to ignore the entire idea folder.
+#.idea/
+
+# PyPI configuration file
+.pypirc
+
+
+uv.lock
+test.db
+*.bak
+uvx
+*.log
+.env.*
+staticfiles/*
+
+swarm-django.db
+swarm-django.db-*
+
+wp-sites.json
+
+traces.*
+
+openapi.yaml
+
+*.db
+*.db-shm
+logs/*
+
+openai-agents-python/*
+docker-compose.override.yml

open_swarm-0.1.1743362777/PKG-INFO

@@ -0,0 +1,217 @@
+Metadata-Version: 2.4
+Name: open-swarm
+Version: 0.1.1743362777
+Summary: Open Swarm: Orchestrating AI Agent Swarms with Django
+Project-URL: Homepage, https://github.com/yourusername/open-swarm
+Project-URL: Documentation, https://github.com/yourusername/open-swarm/blob/main/README.md
+Project-URL: Repository, https://github.com/yourusername/open-swarm.git
+Project-URL: Changelog, https://github.com/yourusername/open-swarm/blob/main/CHANGELOG.md
+Author-email: Matthew Hand <matthewhandau@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Framework :: Django :: 4.2
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Natural Language :: English
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
+Requires-Python: >=3.10
+Requires-Dist: beautifulsoup4>=4.12.0
+Requires-Dist: celery>=5.3.0
+Requires-Dist: channels-redis>=4.0
+Requires-Dist: channels>=4.0
+Requires-Dist: django-cors-headers>=4.0.0
+Requires-Dist: django-environ>=0.11.0
+Requires-Dist: django-extensions>=3.2.0
+Requires-Dist: django-filter>=23.0
+Requires-Dist: django-model-utils>=4.3.0
+Requires-Dist: django<5.0,>=4.2
+Requires-Dist: djangorestframework<4.0,>=3.14
+Requires-Dist: drf-spectacular>=0.28.0
+Requires-Dist: drf-yasg>=1.21.0
+Requires-Dist: google-api-python-client>=2.100.0
+Requires-Dist: google-auth-httplib2>=0.1.0
+Requires-Dist: google-auth-oauthlib>=1.2.1
+Requires-Dist: gunicorn>=21.0.0
+Requires-Dist: httpx<0.26.0,>=0.25.2
+Requires-Dist: jinja2>=3.1.6
+Requires-Dist: openai-agents>=0.0.1
+Requires-Dist: openai<2.0.0,>=1.3.0
+Requires-Dist: platformdirs>=4.0.0
+Requires-Dist: psycopg2-binary>=2.9.0
+Requires-Dist: pyinstaller>=5.13.0
+Requires-Dist: python-dotenv>=1.0.0
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: qdrant-client>=1.6.0
+Requires-Dist: redis>=5.0.0
+Requires-Dist: requests>=2.31.0
+Requires-Dist: tiktoken>=0.5.0
+Requires-Dist: typer>=0.9.0
+Requires-Dist: uvicorn>=0.23.0
+Provides-Extra: dev
+Requires-Dist: factory-boy>=3.3.0; extra == 'dev'
+Requires-Dist: ipdb; extra == 'dev'
+Requires-Dist: ipython; extra == 'dev'
+Requires-Dist: mypy>=1.5.0; extra == 'dev'
+Requires-Dist: pre-commit>=3.5.0; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.21.0; extra == 'dev'
+Requires-Dist: pytest-cov>=4.1.0; extra == 'dev'
+Requires-Dist: pytest-django>=4.7.0; extra == 'dev'
+Requires-Dist: pytest-mock>=3.11.0; extra == 'dev'
+Requires-Dist: pytest>=8.0.0; extra == 'dev'
+Requires-Dist: ruff>=0.1.0; extra == 'dev'
+Requires-Dist: uv>=0.1.11; extra == 'dev'
+Provides-Extra: docs
+Requires-Dist: myst-parser>=2.0.0; extra == 'docs'
+Requires-Dist: sphinx-rtd-theme>=1.3.0; extra == 'docs'
+Requires-Dist: sphinx>=7.0.0; extra == 'docs'
+Provides-Extra: test
+Requires-Dist: anyio>=4.0.0; extra == 'test'
+Requires-Dist: factory-boy>=3.3.0; extra == 'test'
+Requires-Dist: pytest-asyncio>=0.21.0; extra == 'test'
+Requires-Dist: pytest-cov>=4.1.0; extra == 'test'
+Requires-Dist: pytest-django>=4.7.0; extra == 'test'
+Requires-Dist: pytest-env>=1.0.0; extra == 'test'
+Requires-Dist: pytest-mock>=3.11.0; extra == 'test'
+Requires-Dist: pytest-xdist; extra == 'test'
+Requires-Dist: pytest>=8.0.0; extra == 'test'
+Requires-Dist: respx>=0.20.0; extra == 'test'
+Requires-Dist: sseclient-py>=1.7.2; extra == 'test'
+Description-Content-Type: text/markdown
+
+# Open Swarm
+
+<div align="center">
+<img src="assets/images/openswarm-project-image.jpg" alt="Project Logo" width="70%"/>
+</div>
+
+**Open Swarm** is a Python framework for creating, managing, and deploying autonomous agent swarms. It leverages the `openai-agents` library for core agent functionality and provides a structured way to build complex, multi-agent workflows using **Blueprints**.
+
+---
+
+## Core Concepts
+
+*   **Agents:** Individual AI units performing specific tasks, powered by LLMs (like GPT-4, Claude, etc.). Built using the `openai-agents` SDK.
+*   **Blueprints:** Python classes (`BlueprintBase` subclasses) defining a swarm's structure, agents, coordination logic, and external dependencies (like required environment variables or MCP servers). They act as reusable templates for specific tasks (e.g., code generation, research, data analysis).
+*   **MCP (Mission Control Platform) Servers:** Optional external processes providing specialized capabilities (tools) to agents, such as filesystem access, web browsing, database interaction, or interacting with specific APIs (Slack, Monday.com, etc.). Agents interact with MCP servers via a standardized communication protocol.
+*   **Configuration (`swarm_config.json`):** A central JSON file defining available LLM profiles (API keys, models) and configurations for MCP servers. Typically managed via `swarm-cli` in `~/.config/swarm/`.
+*   **`swarm-cli`:** A command-line tool for managing blueprints (adding, listing, running, installing) and the `swarm_config.json` file. Uses XDG directories for storing blueprints (`~/.local/share/swarm/blueprints/`) and configuration (`~/.config/swarm/`).
+*   **`swarm-api`:** A launcher for the Django/DRF backend that exposes installed blueprints via an OpenAI-compatible REST API (`/v1/models`, `/v1/chat/completions`).
+
+---
+
+## Quickstart (Docker - Recommended)
+
+This is the easiest and recommended way to get started, especially for deploying the API service.
+
+**Prerequisites:**
+*   Docker ([Install Docker](https://docs.docker.com/engine/install/))
+*   Docker Compose ([Install Docker Compose](https://docs.docker.com/compose/install/))
+
+**Steps:**
+
+1.  **Clone the Repository:**
+    ```bash
+    git clone https://github.com/matthewhand/open-swarm.git
+    cd open-swarm
+    ```
+
+2.  **Configure Environment:**
+    *   Copy the example environment file:
+        ```bash
+        cp .env.example .env
+        ```
+    *   Edit `.env` and add your necessary API keys (e.g., `OPENAI_API_KEY`).
+
+3.  **Configure Docker Compose Overrides (Optional but Recommended):**
+    *   Copy the override example:
+        ```bash
+        cp docker-compose.override.yaml.example docker-compose.override.yaml
+        ```
+    *   Edit `docker-compose.override.yaml` to:
+        *   Mount any local directories containing custom blueprints you want the API server to access (e.g., uncomment and adjust the `./my_custom_blueprints:/app/custom_blueprints:ro` line).
+        *   Make any other necessary adjustments (ports, environment variables, etc.).
+
+4.  **Start the Service:**
+    ```bash
+    docker compose up -d
+    ```
+    This will build the image (if not already pulled/built) and start the `open-swarm` service, exposing the API on port 8000 (or the port specified in your `.env`/override).
+
+5.  **Verify API:**
+    *   Check the available models (blueprints):
+        ```bash
+        curl http://localhost:8000/v1/models
+        ```
+    *   Send a chat completion request:
+        ```bash
+        curl http://localhost:8000/v1/chat/completions \
+          -H "Content-Type: application/json" \
+          -d '{
+                "model": "echocraft",
+                "messages": [{"role": "user", "content": "Hello Docker!"}]
+              }'
+        ```
+        *(Replace `echocraft` with a blueprint name available in your mounted volumes or the base image).*
+
+---
+
+## Usage Modes
+
+Open Swarm offers several ways to interact with your blueprints:
+
+1.  **Run via `swarm-api` (OpenAI-Compatible REST API):**
+    *   **How:** Start the Django server (`uv run python manage.py runserver` or via Docker as shown above).
+    *   **What:** Exposes blueprints listed in `settings.BLUEPRINT_DIRECTORY` (within the Docker container, this typically includes `/app/blueprints` and any volumes mounted in the override file) via `/v1/models` and `/v1/chat/completions`.
+    *   **Auth:** If `SWARM_API_KEY` is set in `.env`, requests require an `Authorization: Bearer <your_key>` header. Otherwise, access is anonymous.
+    *   **Security:** **Warning:** Running with anonymous access, especially when bound to `0.0.0.0`, can be insecure if blueprints have access to sensitive operations (filesystem, shell commands). **Setting `SWARM_API_KEY` is highly recommended for non-local deployments.**
+    *   **(TODO) Web UI:** A future mode will integrate a simple web chat interface with the API server.
+
+2.  **Run via `swarm-cli run`:**
+    *   **How:** `swarm-cli run <blueprint_name> --instruction "Your single instruction"`
+    *   **What:** Executes a blueprint managed by `swarm-cli` (located in `~/.local/share/swarm/blueprints/`) directly in the terminal. Uses configuration from `~/.config/swarm/swarm_config.json`.
+    *   **Interactive Mode:** If you omit the `--instruction` argument (`swarm-cli run <blueprint_name>`), it will enter an interactive chat mode in the terminal.
+    *   **Use Case:** Good for testing, debugging, interactive sessions, or running specific tasks locally without the API overhead.
+
+3.  **Run via `swarm-cli install`:**
+    *   **How:** `swarm-cli install <blueprint_name>`, then run `<blueprint_name> --instruction "..."`
+    *   **What:** Creates a standalone executable for a managed blueprint using PyInstaller and places it in the user's binary directory (e.g., `~/.local/bin/` or similar, ensure it's in your `PATH`).
+    *   **Use Case:** Convenient for frequently used blueprints that act like regular command-line tools.
+
+4.  **Direct Python Execution:**
+    *   **How:** `uv run python /path/to/your/blueprint_file.py --instruction "..."`
+    *   **What:** Runs a specific blueprint Python file directly. Requires manual handling of configuration loading and dependencies.
+    *   **Use Case:** Primarily for development and testing of a single blueprint file outside the managed environment.
+
+---
+
+## Further Documentation
+
+This README provides a high-level overview and quickstart. For more detailed information, please refer to:
+
+*   **User Guide (`USERGUIDE.md`):** Detailed instructions on using `swarm-cli` commands for managing blueprints and configuration.
+*   **Development Guide (`DEVELOPMENT.md`):** Information for contributors and developers, including architecture details, testing strategies, project layout, and advanced topics like XDG paths and blueprint creation.
+*   **Example Blueprints (`src/swarm/blueprints/README.md`):** A list and description of the example blueprints included with the framework, showcasing various features and integration patterns.
+
+---
+
+## Contributing
+
+Contributions are welcome! Please refer to the `CONTRIBUTING.md` file (if available) or open an issue/pull request on the repository.
+
+---
+
+## License
+
+Open Swarm is provided under the MIT License. Refer to the [LICENSE](LICENSE) file for full details.
+
+---
+
+## Acknowledgements
+
+This project builds upon concepts and code from the `openai-agents` library and potentially other open-source projects. Specific acknowledgements can be found in `DEVELOPMENT.md` or individual source files.

open_swarm-0.1.1743362777/README.md

@@ -0,0 +1,131 @@
+# Open Swarm
+
+<div align="center">
+<img src="assets/images/openswarm-project-image.jpg" alt="Project Logo" width="70%"/>
+</div>
+
+**Open Swarm** is a Python framework for creating, managing, and deploying autonomous agent swarms. It leverages the `openai-agents` library for core agent functionality and provides a structured way to build complex, multi-agent workflows using **Blueprints**.
+
+---
+
+## Core Concepts
+
+*   **Agents:** Individual AI units performing specific tasks, powered by LLMs (like GPT-4, Claude, etc.). Built using the `openai-agents` SDK.
+*   **Blueprints:** Python classes (`BlueprintBase` subclasses) defining a swarm's structure, agents, coordination logic, and external dependencies (like required environment variables or MCP servers). They act as reusable templates for specific tasks (e.g., code generation, research, data analysis).
+*   **MCP (Mission Control Platform) Servers:** Optional external processes providing specialized capabilities (tools) to agents, such as filesystem access, web browsing, database interaction, or interacting with specific APIs (Slack, Monday.com, etc.). Agents interact with MCP servers via a standardized communication protocol.
+*   **Configuration (`swarm_config.json`):** A central JSON file defining available LLM profiles (API keys, models) and configurations for MCP servers. Typically managed via `swarm-cli` in `~/.config/swarm/`.
+*   **`swarm-cli`:** A command-line tool for managing blueprints (adding, listing, running, installing) and the `swarm_config.json` file. Uses XDG directories for storing blueprints (`~/.local/share/swarm/blueprints/`) and configuration (`~/.config/swarm/`).
+*   **`swarm-api`:** A launcher for the Django/DRF backend that exposes installed blueprints via an OpenAI-compatible REST API (`/v1/models`, `/v1/chat/completions`).
+
+---
+
+## Quickstart (Docker - Recommended)
+
+This is the easiest and recommended way to get started, especially for deploying the API service.
+
+**Prerequisites:**
+*   Docker ([Install Docker](https://docs.docker.com/engine/install/))
+*   Docker Compose ([Install Docker Compose](https://docs.docker.com/compose/install/))
+
+**Steps:**
+
+1.  **Clone the Repository:**
+    ```bash
+    git clone https://github.com/matthewhand/open-swarm.git
+    cd open-swarm
+    ```
+
+2.  **Configure Environment:**
+    *   Copy the example environment file:
+        ```bash
+        cp .env.example .env
+        ```
+    *   Edit `.env` and add your necessary API keys (e.g., `OPENAI_API_KEY`).
+
+3.  **Configure Docker Compose Overrides (Optional but Recommended):**
+    *   Copy the override example:
+        ```bash
+        cp docker-compose.override.yaml.example docker-compose.override.yaml
+        ```
+    *   Edit `docker-compose.override.yaml` to:
+        *   Mount any local directories containing custom blueprints you want the API server to access (e.g., uncomment and adjust the `./my_custom_blueprints:/app/custom_blueprints:ro` line).
+        *   Make any other necessary adjustments (ports, environment variables, etc.).
+
+4.  **Start the Service:**
+    ```bash
+    docker compose up -d
+    ```
+    This will build the image (if not already pulled/built) and start the `open-swarm` service, exposing the API on port 8000 (or the port specified in your `.env`/override).
+
+5.  **Verify API:**
+    *   Check the available models (blueprints):
+        ```bash
+        curl http://localhost:8000/v1/models
+        ```
+    *   Send a chat completion request:
+        ```bash
+        curl http://localhost:8000/v1/chat/completions \
+          -H "Content-Type: application/json" \
+          -d '{
+                "model": "echocraft",
+                "messages": [{"role": "user", "content": "Hello Docker!"}]
+              }'
+        ```
+        *(Replace `echocraft` with a blueprint name available in your mounted volumes or the base image).*
+
+---
+
+## Usage Modes
+
+Open Swarm offers several ways to interact with your blueprints:
+
+1.  **Run via `swarm-api` (OpenAI-Compatible REST API):**
+    *   **How:** Start the Django server (`uv run python manage.py runserver` or via Docker as shown above).
+    *   **What:** Exposes blueprints listed in `settings.BLUEPRINT_DIRECTORY` (within the Docker container, this typically includes `/app/blueprints` and any volumes mounted in the override file) via `/v1/models` and `/v1/chat/completions`.
+    *   **Auth:** If `SWARM_API_KEY` is set in `.env`, requests require an `Authorization: Bearer <your_key>` header. Otherwise, access is anonymous.
+    *   **Security:** **Warning:** Running with anonymous access, especially when bound to `0.0.0.0`, can be insecure if blueprints have access to sensitive operations (filesystem, shell commands). **Setting `SWARM_API_KEY` is highly recommended for non-local deployments.**
+    *   **(TODO) Web UI:** A future mode will integrate a simple web chat interface with the API server.
+
+2.  **Run via `swarm-cli run`:**
+    *   **How:** `swarm-cli run <blueprint_name> --instruction "Your single instruction"`
+    *   **What:** Executes a blueprint managed by `swarm-cli` (located in `~/.local/share/swarm/blueprints/`) directly in the terminal. Uses configuration from `~/.config/swarm/swarm_config.json`.
+    *   **Interactive Mode:** If you omit the `--instruction` argument (`swarm-cli run <blueprint_name>`), it will enter an interactive chat mode in the terminal.
+    *   **Use Case:** Good for testing, debugging, interactive sessions, or running specific tasks locally without the API overhead.
+
+3.  **Run via `swarm-cli install`:**
+    *   **How:** `swarm-cli install <blueprint_name>`, then run `<blueprint_name> --instruction "..."`
+    *   **What:** Creates a standalone executable for a managed blueprint using PyInstaller and places it in the user's binary directory (e.g., `~/.local/bin/` or similar, ensure it's in your `PATH`).
+    *   **Use Case:** Convenient for frequently used blueprints that act like regular command-line tools.
+
+4.  **Direct Python Execution:**
+    *   **How:** `uv run python /path/to/your/blueprint_file.py --instruction "..."`
+    *   **What:** Runs a specific blueprint Python file directly. Requires manual handling of configuration loading and dependencies.
+    *   **Use Case:** Primarily for development and testing of a single blueprint file outside the managed environment.
+
+---
+
+## Further Documentation
+
+This README provides a high-level overview and quickstart. For more detailed information, please refer to:
+
+*   **User Guide (`USERGUIDE.md`):** Detailed instructions on using `swarm-cli` commands for managing blueprints and configuration.
+*   **Development Guide (`DEVELOPMENT.md`):** Information for contributors and developers, including architecture details, testing strategies, project layout, and advanced topics like XDG paths and blueprint creation.
+*   **Example Blueprints (`src/swarm/blueprints/README.md`):** A list and description of the example blueprints included with the framework, showcasing various features and integration patterns.
+
+---
+
+## Contributing
+
+Contributions are welcome! Please refer to the `CONTRIBUTING.md` file (if available) or open an issue/pull request on the repository.
+
+---
+
+## License
+
+Open Swarm is provided under the MIT License. Refer to the [LICENSE](LICENSE) file for full details.
+
+---
+
+## Acknowledgements
+
+This project builds upon concepts and code from the `openai-agents` library and potentially other open-source projects. Specific acknowledgements can be found in `DEVELOPMENT.md` or individual source files.