open-swarm 0.1.1748636259__tar.gz → 0.1.1748636295__tar.gz

open_swarm-0.1.1748636295/PKG-INFO

@@ -0,0 +1,257 @@
+Metadata-Version: 2.4
+Name: open-swarm
+Version: 0.1.1748636295
+Summary: A tool for orchestrating Swarm using both CLI and API.
+Author-email: Matthew Hand <matthewhandau@gmail.com>
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: aiofiles>=24.1.0
+Requires-Dist: aiohttp>=3.11.11
+Requires-Dist: asyncio>=3.4.3
+Requires-Dist: asynctest>=0.13.0
+Requires-Dist: channels>=4.2.0
+Requires-Dist: colorama>=0.4.6
+Requires-Dist: django<5.0,>=4.2
+Requires-Dist: django-allauth>=65.3.1
+Requires-Dist: django-template-debug>=0.3.5
+Requires-Dist: djangorestframework>=3.15.2
+Requires-Dist: flask>=3.1.0
+Requires-Dist: jmespath>=1.0.1
+Requires-Dist: jsonschema-pydantic>=0.6
+Requires-Dist: mcp>=1.2.0
+Requires-Dist: openai>=1.58.1
+Requires-Dist: python-dotenv>=1.0.1
+Requires-Dist: redis>=5.2.1
+Requires-Dist: requests>=2.32.3
+Requires-Dist: whitenoise>=6.8.2
+Requires-Dist: drf-spectacular>=0.23.0
+Requires-Dist: pyinstaller>=6.12.0
+Requires-Dist: tiktoken>=0.9.0
+Requires-Dist: django-cors-headers>=4.7.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8.3.4; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.25.1; extra == "dev"
+Requires-Dist: pytest-cov>=6.0.0; extra == "dev"
+Requires-Dist: pytest-django>=4.9.0; extra == "dev"
+Requires-Dist: pytest-mock>=3.14.0; extra == "dev"
+Requires-Dist: python-semantic-release>=9.20.0; extra == "dev"
+Provides-Extra: experimental
+Requires-Dist: nemoguardrails>=0.11.0; extra == "experimental"
+Dynamic: license-file
+
+# Open Swarm
+
+<div align="center">
+<img src="assets/images/openswarm-project-image.jpg" alt="Project Logo" width="70%"/>
+</div>
+
+**Open Swarm** is a versatile, modular framework for building intelligent, multi-agent systems. It's a **fork and actively maintained extension** of the [OpenAI Swarm](https://github.com/openai/swarm) framework. It includes modifications to support stateless RESTful operations and a plugin system for custom extensions that enhance agentic workflows.
+
+---
+
+https://github.com/user-attachments/assets/1335f7fb-ff61-4e96-881c-7d3154eb9f14
+
+(generated by www.gitpodcast.com)
+
+---
+
+## Table of Contents
+- [Key Features](#key-features)
+- [Quickstart](#quickstart)
+- [Blueprints](#blueprints)
+- [Further Documentation](#further-documentation)
+- [License](#license)
+- [Acknowledgements](#acknowledgements)
+
+---
+
+## Key Features
+
+1. **Multi-Agent Orchestration**  
+   - Define multiple agents, each with unique instructions and roles.
+   - Agents coordinate tasks, share context, or hand off queries between one another.
+
+2. **Blueprint-Driven Architecture**  
+   - Each **Blueprint** encapsulates logic, tool connections, and environment/config settings.
+   - Encourages reusable, modular patterns for different use cases.
+
+3. **Optional MCP Integration**  
+   - Integrate with external tools (e.g., databases, web search, filesystems) through **MCP servers**.
+   - Note `npx` MCP servers work great but `uvx` MCP servers currently have issues.
+
+4. **CLI & REST Interface**  
+   - Run from the command line or expose a Django-powered REST API for broader integration.
+   - Interactive web pages per blueprint at `/<blueprint_name>/`.
+
+5. **OpenAI API Compatibility**  
+   - Exposes an endpoint at `/v1/chat/completions` that is functionally similar to the OpenAI Chat Completions API.
+   - Includes a **mandatory** `sender` field in agent responses.  
+     - This field identifies which Swarm agent provided the response and must be preserved in the conversation history for proper handoffs between agents.
+     - While the framework is compatible with OpenAI-like API clients, it assumes the client application maintains the `sender` field and, ideally, displays it in the user interface.
+     - **Note:** Most OpenAI API-compatible applications will ignore the `sender` field by default and not display the agent name. Custom UI or logic is required to utilise and present this information.
+
+6. **Configurable LLMs**  
+   - Supports multiple OpenAI-compatible providers in a single environment (e.g., `openai`, `grok`, `ollama`).
+   - Allows specifying different models/providers for different agents—even within the same blueprint.
+   - Use environment variable `DEFAULT_LLM` to specify default LLM model used by blueprints, e.g., `DEFAULT_LLM=deepseek-r1-distill-llama-70b`
+
+---
+
+## Quickstart
+
+Follow these simple steps to get Open Swarm up and running:
+
+1. **Install the Package**  
+   Run:
+   ```bash
+   pip install open-swarm
+   ```
+
+2. **Configure an LLM Provider**  
+   When you run a blueprint for the first time, Open Swarm checks for a configuration file at `~/.swarm/swarm_config.json`. If the file is missing, it will automatically create a default configuration as shown below:
+   ```json
+   {
+       "llm": {
+           "default": {
+               "provider": "openai",
+               "model": "gpt-4o",
+               "base_url": "https://api.openai.com/v1",
+               "api_key": "${OPENAI_API_KEY}"
+           }
+       },
+       "mcpServers": {}
+   }
+   ```
+   Make sure to set the `OPENAI_API_KEY` environment variable with your valid OpenAI API key.
+
+   An example of using an alternative provider:
+
+   `swarm-cli config add --section llm --name deepseek-r1-distill-llama-70b --json '{"provider": "openai", "model": "deepseek-r1-distill-llama-70b", "base_url": "https://api.groq.com/openai/v1", "api_key": "${GROQ_API_KEY}"}' `
+
+
+3. **(Optional) Configure a Simple MCP Server**  
+   To add an MCP server for additional utilities (e.g., file fetching), use the `swarm-cli config add --json '<multiline_json_block>'`. For example:
+
+   ```json
+      "filesystem": {
+         "command": "npx",
+         "args": [
+               "-y",
+               "@modelcontextprotocol/server-filesystem ${ALLOWED_PATH}"
+         ],
+         "env": {
+               "ALLOWED_PATH": "${ALLOWED_PATH}"
+         }
+      }
+   ```
+
+4. **Add an Example Blueprint**  
+   Add an example blueprint by running:
+   ```bash
+   swarm-cli add /path/to/your/blueprint.py --name example
+   ```
+   This copies your blueprint into the managed blueprints directory.
+
+   Example blueprints are provided here: https://github.com/matthewhand/open-swarm/tree/main/blueprints
+
+5. **Run the Blueprint from CLI**  
+   Execute the blueprint with:
+   ```bash
+   swarm-cli run example
+   ```
+
+---
+
+## Overview
+
+Open Swarm provides the following core components:
+
+- **Swarm CLI:**  
+  A command-line tool for managing blueprints and configuration settings. It allows you to add, list, delete, run, and install blueprints, as well as update configuration entries for LLM providers and MCP servers.
+
+- **Swarm API:**  
+  An HTTP REST service that exposes endpoints such as `/v1/models` and `/v1/chat/completion(s)`. These endpoints let external applications interact with Open Swarm in an OpenAI API-compatible manner, publishing blueprints as models and processing chat completions.  Additional endpoints can be exposed via blueprints.
+
+- **Swarm SDK:**  
+  Open Swarm can be used as a Python module.  It is backwards compatible with the original OpenAI Swarm educational framework.  It also adds many extensions including configuration loading, MCP server integration, Python Django DB and REST features, etc etc.
+
+For detailed usage instructions, please refer to the [USERGUIDE.md](./USERGUIDE.md). For developer-specific guidance, see [DEVELOPMENT.md](./DEVELOPMENT.md).
+
+---
+
+
+## Blueprints
+
+A **Blueprint** is a Python module that wraps:
+
+- **Agent Logic**: Defines how each agent in the Swarm processes user messages, whether it calls tools, and how it decides to hand off to other agents.
+- **Tools**: Specifies which agents have which tools (e.g., MCP-discovered tools, Python function calls).
+- **Environment & Configuration**: Ensures required environment variables and JSON configs are validated prior to agent execution.
+
+Once registered, a blueprint is discoverable at runtime, allowing the system to list and load agents on demand.
+
+### Personal Assistant Example
+
+The **Personal Assistant Blueprint** demonstrates a hybrid approach, integrating **local Python function tools** with **MCP-discovered tools**. It consists of:
+
+1. **Personal Assistant Agent**  
+   - Determines user intent and delegates queries accordingly.  
+   - Routes weather-related queries to the `WeatherAgent`.  
+   - Routes knowledge-based queries to the `DocumentationAgent`.
+
+2. **Weather Agent** (Uses Python Function Tools)  
+   - Fetches current weather and forecasts via OpenWeatherMap.  
+   - Uses a **locally defined Python function** rather than an MCP server.  
+   - Requires `WEATHER_API_KEY` as an environment variable.
+
+3. **Documentation Agent** (Uses MCP-Discovered Tools)  
+   - Retrieves relevant documentation via `rag-docs`.  
+   - Uses the MCP function `search_documentation` to dynamically retrieve information.  
+   - Requires the following environment variables:  
+     - `OPENAI_API_KEY`  
+     - `QDRANT_URL`  
+     - `QDRANT_API_KEY`
+
+This blueprint highlights **seamless multi-agent coordination** and the **flexibility of combining Python functions with MCP-discovered tools**.
+
+### Other Examples
+
+Open Swarm includes a growing library of **Blueprint** examples:
+
+| Blueprint Name               | Description                                                                 | Status                                  |
+|------------------------------|-----------------------------------------------------------------------------|-----------------------------------------|
+| **Echo Blueprint**           | A straightforward agent that simply echoes user inputs—ideal for testing or as a starter template. | Stable                                  |
+| **Suggestion Blueprint**     | Blueprint providing suggestions and recommendations.                        | Stable                                  |
+| **Database and Web Blueprint** | Demonstrates MCP-based integration with an SQLite database and Brave Search, illustrating how to combine data retrieval with real-time web queries. | Stable                                  |
+| **University Blueprint**       | Multi-agent system for university-related tasks.                            | Stable                                  |
+| **Divine Ops Blueprint**       | Multi-agent system for handling system administration tasks using MCP tools (filesystem, SQLite, search, etc.). | Stable                                  |
+| **Nebucha Shellzzar Blueprint**| Example system administration blueprint.                                  | Stable                                  |
+| **Personal Assistant Blueprint** | Combines real-time weather updates (Python function) with documentation search (`rag-docs`, MCP). Demonstrates mixed tooling. | Broken (uvx-based)                      |
+| **Flowise Blueprint**          | Integrates with Flowise for visual flow orchestration.                      | Broken (uvx-based, requires Flowise setup)|
+
+---
+---
+
+## Further Documentation
+
+For advanced usage, sequence diagrams, or in-depth tooling examples, see [DEVELOPMENT.md](./DEVELOPMENT.md). Additional expansions and best practices for agent orchestration, LLM provider swapping, and more can be found in that document.
+
+---
+
+## License
+
+Open Swarm is provided under the MIT License. Refer to the [LICENSE](LICENSE) file for full details.
+
+---
+
+## Acknowledgements
+
+This project is based on the [OpenAI Swarm](https://github.com/openai/swarm) framework. We would like to acknowledge the original authors and contributors of this project for their work.  
+We also wish to credit [django_chatbot](https://github.com/MattiPaivike/django_chatbot) for the Django chatbot view.
+
+### Third-Party Libraries
+- **[Marked.js](https://github.com/markedjs/marked)** (MIT License)  
+  A fast, lightweight library for parsing Markdown into HTML.
+- **[Tabler Icons](https://tablericons.com)** (MIT License)  
+  A set of free, high-quality SVG icons for web projects, designed by Paweł Kuna.

open_swarm-0.1.1748636295/README.md

@@ -0,0 +1,215 @@
+# Open Swarm
+
+<div align="center">
+<img src="assets/images/openswarm-project-image.jpg" alt="Project Logo" width="70%"/>
+</div>
+
+**Open Swarm** is a versatile, modular framework for building intelligent, multi-agent systems. It's a **fork and actively maintained extension** of the [OpenAI Swarm](https://github.com/openai/swarm) framework. It includes modifications to support stateless RESTful operations and a plugin system for custom extensions that enhance agentic workflows.
+
+---
+
+https://github.com/user-attachments/assets/1335f7fb-ff61-4e96-881c-7d3154eb9f14
+
+(generated by www.gitpodcast.com)
+
+---
+
+## Table of Contents
+- [Key Features](#key-features)
+- [Quickstart](#quickstart)
+- [Blueprints](#blueprints)
+- [Further Documentation](#further-documentation)
+- [License](#license)
+- [Acknowledgements](#acknowledgements)
+
+---
+
+## Key Features
+
+1. **Multi-Agent Orchestration**  
+   - Define multiple agents, each with unique instructions and roles.
+   - Agents coordinate tasks, share context, or hand off queries between one another.
+
+2. **Blueprint-Driven Architecture**  
+   - Each **Blueprint** encapsulates logic, tool connections, and environment/config settings.
+   - Encourages reusable, modular patterns for different use cases.
+
+3. **Optional MCP Integration**  
+   - Integrate with external tools (e.g., databases, web search, filesystems) through **MCP servers**.
+   - Note `npx` MCP servers work great but `uvx` MCP servers currently have issues.
+
+4. **CLI & REST Interface**  
+   - Run from the command line or expose a Django-powered REST API for broader integration.
+   - Interactive web pages per blueprint at `/<blueprint_name>/`.
+
+5. **OpenAI API Compatibility**  
+   - Exposes an endpoint at `/v1/chat/completions` that is functionally similar to the OpenAI Chat Completions API.
+   - Includes a **mandatory** `sender` field in agent responses.  
+     - This field identifies which Swarm agent provided the response and must be preserved in the conversation history for proper handoffs between agents.
+     - While the framework is compatible with OpenAI-like API clients, it assumes the client application maintains the `sender` field and, ideally, displays it in the user interface.
+     - **Note:** Most OpenAI API-compatible applications will ignore the `sender` field by default and not display the agent name. Custom UI or logic is required to utilise and present this information.
+
+6. **Configurable LLMs**  
+   - Supports multiple OpenAI-compatible providers in a single environment (e.g., `openai`, `grok`, `ollama`).
+   - Allows specifying different models/providers for different agents—even within the same blueprint.
+   - Use environment variable `DEFAULT_LLM` to specify default LLM model used by blueprints, e.g., `DEFAULT_LLM=deepseek-r1-distill-llama-70b`
+
+---
+
+## Quickstart
+
+Follow these simple steps to get Open Swarm up and running:
+
+1. **Install the Package**  
+   Run:
+   ```bash
+   pip install open-swarm
+   ```
+
+2. **Configure an LLM Provider**  
+   When you run a blueprint for the first time, Open Swarm checks for a configuration file at `~/.swarm/swarm_config.json`. If the file is missing, it will automatically create a default configuration as shown below:
+   ```json
+   {
+       "llm": {
+           "default": {
+               "provider": "openai",
+               "model": "gpt-4o",
+               "base_url": "https://api.openai.com/v1",
+               "api_key": "${OPENAI_API_KEY}"
+           }
+       },
+       "mcpServers": {}
+   }
+   ```
+   Make sure to set the `OPENAI_API_KEY` environment variable with your valid OpenAI API key.
+
+   An example of using an alternative provider:
+
+   `swarm-cli config add --section llm --name deepseek-r1-distill-llama-70b --json '{"provider": "openai", "model": "deepseek-r1-distill-llama-70b", "base_url": "https://api.groq.com/openai/v1", "api_key": "${GROQ_API_KEY}"}' `
+
+
+3. **(Optional) Configure a Simple MCP Server**  
+   To add an MCP server for additional utilities (e.g., file fetching), use the `swarm-cli config add --json '<multiline_json_block>'`. For example:
+
+   ```json
+      "filesystem": {
+         "command": "npx",
+         "args": [
+               "-y",
+               "@modelcontextprotocol/server-filesystem ${ALLOWED_PATH}"
+         ],
+         "env": {
+               "ALLOWED_PATH": "${ALLOWED_PATH}"
+         }
+      }
+   ```
+
+4. **Add an Example Blueprint**  
+   Add an example blueprint by running:
+   ```bash
+   swarm-cli add /path/to/your/blueprint.py --name example
+   ```
+   This copies your blueprint into the managed blueprints directory.
+
+   Example blueprints are provided here: https://github.com/matthewhand/open-swarm/tree/main/blueprints
+
+5. **Run the Blueprint from CLI**  
+   Execute the blueprint with:
+   ```bash
+   swarm-cli run example
+   ```
+
+---
+
+## Overview
+
+Open Swarm provides the following core components:
+
+- **Swarm CLI:**  
+  A command-line tool for managing blueprints and configuration settings. It allows you to add, list, delete, run, and install blueprints, as well as update configuration entries for LLM providers and MCP servers.
+
+- **Swarm API:**  
+  An HTTP REST service that exposes endpoints such as `/v1/models` and `/v1/chat/completion(s)`. These endpoints let external applications interact with Open Swarm in an OpenAI API-compatible manner, publishing blueprints as models and processing chat completions.  Additional endpoints can be exposed via blueprints.
+
+- **Swarm SDK:**  
+  Open Swarm can be used as a Python module.  It is backwards compatible with the original OpenAI Swarm educational framework.  It also adds many extensions including configuration loading, MCP server integration, Python Django DB and REST features, etc etc.
+
+For detailed usage instructions, please refer to the [USERGUIDE.md](./USERGUIDE.md). For developer-specific guidance, see [DEVELOPMENT.md](./DEVELOPMENT.md).
+
+---
+
+
+## Blueprints
+
+A **Blueprint** is a Python module that wraps:
+
+- **Agent Logic**: Defines how each agent in the Swarm processes user messages, whether it calls tools, and how it decides to hand off to other agents.
+- **Tools**: Specifies which agents have which tools (e.g., MCP-discovered tools, Python function calls).
+- **Environment & Configuration**: Ensures required environment variables and JSON configs are validated prior to agent execution.
+
+Once registered, a blueprint is discoverable at runtime, allowing the system to list and load agents on demand.
+
+### Personal Assistant Example
+
+The **Personal Assistant Blueprint** demonstrates a hybrid approach, integrating **local Python function tools** with **MCP-discovered tools**. It consists of:
+
+1. **Personal Assistant Agent**  
+   - Determines user intent and delegates queries accordingly.  
+   - Routes weather-related queries to the `WeatherAgent`.  
+   - Routes knowledge-based queries to the `DocumentationAgent`.
+
+2. **Weather Agent** (Uses Python Function Tools)  
+   - Fetches current weather and forecasts via OpenWeatherMap.  
+   - Uses a **locally defined Python function** rather than an MCP server.  
+   - Requires `WEATHER_API_KEY` as an environment variable.
+
+3. **Documentation Agent** (Uses MCP-Discovered Tools)  
+   - Retrieves relevant documentation via `rag-docs`.  
+   - Uses the MCP function `search_documentation` to dynamically retrieve information.  
+   - Requires the following environment variables:  
+     - `OPENAI_API_KEY`  
+     - `QDRANT_URL`  
+     - `QDRANT_API_KEY`
+
+This blueprint highlights **seamless multi-agent coordination** and the **flexibility of combining Python functions with MCP-discovered tools**.
+
+### Other Examples
+
+Open Swarm includes a growing library of **Blueprint** examples:
+
+| Blueprint Name               | Description                                                                 | Status                                  |
+|------------------------------|-----------------------------------------------------------------------------|-----------------------------------------|
+| **Echo Blueprint**           | A straightforward agent that simply echoes user inputs—ideal for testing or as a starter template. | Stable                                  |
+| **Suggestion Blueprint**     | Blueprint providing suggestions and recommendations.                        | Stable                                  |
+| **Database and Web Blueprint** | Demonstrates MCP-based integration with an SQLite database and Brave Search, illustrating how to combine data retrieval with real-time web queries. | Stable                                  |
+| **University Blueprint**       | Multi-agent system for university-related tasks.                            | Stable                                  |
+| **Divine Ops Blueprint**       | Multi-agent system for handling system administration tasks using MCP tools (filesystem, SQLite, search, etc.). | Stable                                  |
+| **Nebucha Shellzzar Blueprint**| Example system administration blueprint.                                  | Stable                                  |
+| **Personal Assistant Blueprint** | Combines real-time weather updates (Python function) with documentation search (`rag-docs`, MCP). Demonstrates mixed tooling. | Broken (uvx-based)                      |
+| **Flowise Blueprint**          | Integrates with Flowise for visual flow orchestration.                      | Broken (uvx-based, requires Flowise setup)|
+
+---
+---
+
+## Further Documentation
+
+For advanced usage, sequence diagrams, or in-depth tooling examples, see [DEVELOPMENT.md](./DEVELOPMENT.md). Additional expansions and best practices for agent orchestration, LLM provider swapping, and more can be found in that document.
+
+---
+
+## License
+
+Open Swarm is provided under the MIT License. Refer to the [LICENSE](LICENSE) file for full details.
+
+---
+
+## Acknowledgements
+
+This project is based on the [OpenAI Swarm](https://github.com/openai/swarm) framework. We would like to acknowledge the original authors and contributors of this project for their work.  
+We also wish to credit [django_chatbot](https://github.com/MattiPaivike/django_chatbot) for the Django chatbot view.
+
+### Third-Party Libraries
+- **[Marked.js](https://github.com/markedjs/marked)** (MIT License)  
+  A fast, lightweight library for parsing Markdown into HTML.
+- **[Tabler Icons](https://tablericons.com)** (MIT License)  
+  A set of free, high-quality SVG icons for web projects, designed by Paweł Kuna.

{open_swarm-0.1.1748636259 → open_swarm-0.1.1748636295}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "open-swarm"
-version = "0.1.1748636259"
+version = "0.1.1748636295"
 description = "A tool for orchestrating Swarm using both CLI and API."
 readme = "README.md"
 authors = [
@@ -31,8 +31,6 @@ dependencies = [
    "pyinstaller>=6.12.0",
    "tiktoken>=0.9.0",
    "django-cors-headers>=4.7.0",
-   "cachetools>=5.5.2",
-   "openai-agents",
 ]
 
 [project.scripts]