open-swarm 0.1.1743070217__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (126) hide show
  1. open_swarm-0.1.1743070217/LICENSE +21 -0
  2. open_swarm-0.1.1743070217/PKG-INFO +258 -0
  3. open_swarm-0.1.1743070217/README.md +215 -0
  4. open_swarm-0.1.1743070217/pyproject.toml +61 -0
  5. open_swarm-0.1.1743070217/setup.cfg +4 -0
  6. open_swarm-0.1.1743070217/src/open_swarm.egg-info/PKG-INFO +258 -0
  7. open_swarm-0.1.1743070217/src/open_swarm.egg-info/SOURCES.txt +124 -0
  8. open_swarm-0.1.1743070217/src/open_swarm.egg-info/dependency_links.txt +1 -0
  9. open_swarm-0.1.1743070217/src/open_swarm.egg-info/entry_points.txt +3 -0
  10. open_swarm-0.1.1743070217/src/open_swarm.egg-info/requires.txt +35 -0
  11. open_swarm-0.1.1743070217/src/open_swarm.egg-info/top_level.txt +1 -0
  12. open_swarm-0.1.1743070217/src/swarm/__init__.py +3 -0
  13. open_swarm-0.1.1743070217/src/swarm/agent/__init__.py +7 -0
  14. open_swarm-0.1.1743070217/src/swarm/agent/agent.py +49 -0
  15. open_swarm-0.1.1743070217/src/swarm/apps.py +53 -0
  16. open_swarm-0.1.1743070217/src/swarm/auth.py +56 -0
  17. open_swarm-0.1.1743070217/src/swarm/consumers.py +141 -0
  18. open_swarm-0.1.1743070217/src/swarm/core.py +326 -0
  19. open_swarm-0.1.1743070217/src/swarm/extensions/__init__.py +1 -0
  20. open_swarm-0.1.1743070217/src/swarm/extensions/blueprint/__init__.py +36 -0
  21. open_swarm-0.1.1743070217/src/swarm/extensions/blueprint/agent_utils.py +45 -0
  22. open_swarm-0.1.1743070217/src/swarm/extensions/blueprint/blueprint_base.py +562 -0
  23. open_swarm-0.1.1743070217/src/swarm/extensions/blueprint/blueprint_discovery.py +112 -0
  24. open_swarm-0.1.1743070217/src/swarm/extensions/blueprint/blueprint_utils.py +17 -0
  25. open_swarm-0.1.1743070217/src/swarm/extensions/blueprint/common_utils.py +12 -0
  26. open_swarm-0.1.1743070217/src/swarm/extensions/blueprint/django_utils.py +203 -0
  27. open_swarm-0.1.1743070217/src/swarm/extensions/blueprint/interactive_mode.py +102 -0
  28. open_swarm-0.1.1743070217/src/swarm/extensions/blueprint/modes/rest_mode.py +37 -0
  29. open_swarm-0.1.1743070217/src/swarm/extensions/blueprint/output_utils.py +95 -0
  30. open_swarm-0.1.1743070217/src/swarm/extensions/blueprint/spinner.py +91 -0
  31. open_swarm-0.1.1743070217/src/swarm/extensions/cli/__init__.py +0 -0
  32. open_swarm-0.1.1743070217/src/swarm/extensions/cli/blueprint_runner.py +251 -0
  33. open_swarm-0.1.1743070217/src/swarm/extensions/cli/cli_args.py +88 -0
  34. open_swarm-0.1.1743070217/src/swarm/extensions/cli/commands/__init__.py +0 -0
  35. open_swarm-0.1.1743070217/src/swarm/extensions/cli/commands/blueprint_management.py +31 -0
  36. open_swarm-0.1.1743070217/src/swarm/extensions/cli/commands/config_management.py +15 -0
  37. open_swarm-0.1.1743070217/src/swarm/extensions/cli/commands/edit_config.py +77 -0
  38. open_swarm-0.1.1743070217/src/swarm/extensions/cli/commands/list_blueprints.py +22 -0
  39. open_swarm-0.1.1743070217/src/swarm/extensions/cli/commands/validate_env.py +57 -0
  40. open_swarm-0.1.1743070217/src/swarm/extensions/cli/commands/validate_envvars.py +39 -0
  41. open_swarm-0.1.1743070217/src/swarm/extensions/cli/interactive_shell.py +41 -0
  42. open_swarm-0.1.1743070217/src/swarm/extensions/cli/main.py +36 -0
  43. open_swarm-0.1.1743070217/src/swarm/extensions/cli/selection.py +43 -0
  44. open_swarm-0.1.1743070217/src/swarm/extensions/cli/utils/discover_commands.py +32 -0
  45. open_swarm-0.1.1743070217/src/swarm/extensions/cli/utils/env_setup.py +15 -0
  46. open_swarm-0.1.1743070217/src/swarm/extensions/cli/utils.py +105 -0
  47. open_swarm-0.1.1743070217/src/swarm/extensions/config/__init__.py +6 -0
  48. open_swarm-0.1.1743070217/src/swarm/extensions/config/config_loader.py +208 -0
  49. open_swarm-0.1.1743070217/src/swarm/extensions/config/config_manager.py +258 -0
  50. open_swarm-0.1.1743070217/src/swarm/extensions/config/server_config.py +49 -0
  51. open_swarm-0.1.1743070217/src/swarm/extensions/config/setup_wizard.py +103 -0
  52. open_swarm-0.1.1743070217/src/swarm/extensions/config/utils/__init__.py +0 -0
  53. open_swarm-0.1.1743070217/src/swarm/extensions/config/utils/logger.py +36 -0
  54. open_swarm-0.1.1743070217/src/swarm/extensions/launchers/__init__.py +1 -0
  55. open_swarm-0.1.1743070217/src/swarm/extensions/launchers/build_launchers.py +14 -0
  56. open_swarm-0.1.1743070217/src/swarm/extensions/launchers/build_swarm_wrapper.py +12 -0
  57. open_swarm-0.1.1743070217/src/swarm/extensions/launchers/swarm_api.py +68 -0
  58. open_swarm-0.1.1743070217/src/swarm/extensions/launchers/swarm_cli.py +304 -0
  59. open_swarm-0.1.1743070217/src/swarm/extensions/launchers/swarm_wrapper.py +29 -0
  60. open_swarm-0.1.1743070217/src/swarm/extensions/mcp/__init__.py +1 -0
  61. open_swarm-0.1.1743070217/src/swarm/extensions/mcp/cache_utils.py +36 -0
  62. open_swarm-0.1.1743070217/src/swarm/extensions/mcp/mcp_client.py +341 -0
  63. open_swarm-0.1.1743070217/src/swarm/extensions/mcp/mcp_constants.py +7 -0
  64. open_swarm-0.1.1743070217/src/swarm/extensions/mcp/mcp_tool_provider.py +110 -0
  65. open_swarm-0.1.1743070217/src/swarm/llm/chat_completion.py +195 -0
  66. open_swarm-0.1.1743070217/src/swarm/messages.py +132 -0
  67. open_swarm-0.1.1743070217/src/swarm/migrations/0010_initial_chat_models.py +51 -0
  68. open_swarm-0.1.1743070217/src/swarm/migrations/__init__.py +0 -0
  69. open_swarm-0.1.1743070217/src/swarm/models.py +45 -0
  70. open_swarm-0.1.1743070217/src/swarm/repl/__init__.py +1 -0
  71. open_swarm-0.1.1743070217/src/swarm/repl/repl.py +87 -0
  72. open_swarm-0.1.1743070217/src/swarm/serializers.py +12 -0
  73. open_swarm-0.1.1743070217/src/swarm/settings.py +189 -0
  74. open_swarm-0.1.1743070217/src/swarm/tool_executor.py +239 -0
  75. open_swarm-0.1.1743070217/src/swarm/types.py +126 -0
  76. open_swarm-0.1.1743070217/src/swarm/urls.py +89 -0
  77. open_swarm-0.1.1743070217/src/swarm/util.py +124 -0
  78. open_swarm-0.1.1743070217/src/swarm/utils/color_utils.py +40 -0
  79. open_swarm-0.1.1743070217/src/swarm/utils/context_utils.py +272 -0
  80. open_swarm-0.1.1743070217/src/swarm/utils/general_utils.py +162 -0
  81. open_swarm-0.1.1743070217/src/swarm/utils/logger.py +61 -0
  82. open_swarm-0.1.1743070217/src/swarm/utils/logger_setup.py +25 -0
  83. open_swarm-0.1.1743070217/src/swarm/utils/message_sequence.py +173 -0
  84. open_swarm-0.1.1743070217/src/swarm/utils/message_utils.py +95 -0
  85. open_swarm-0.1.1743070217/src/swarm/utils/redact.py +68 -0
  86. open_swarm-0.1.1743070217/src/swarm/views/__init__.py +41 -0
  87. open_swarm-0.1.1743070217/src/swarm/views/api_views.py +46 -0
  88. open_swarm-0.1.1743070217/src/swarm/views/chat_views.py +76 -0
  89. open_swarm-0.1.1743070217/src/swarm/views/core_views.py +118 -0
  90. open_swarm-0.1.1743070217/src/swarm/views/message_views.py +40 -0
  91. open_swarm-0.1.1743070217/src/swarm/views/model_views.py +135 -0
  92. open_swarm-0.1.1743070217/src/swarm/views/utils.py +457 -0
  93. open_swarm-0.1.1743070217/src/swarm/views/web_views.py +149 -0
  94. open_swarm-0.1.1743070217/src/swarm/wsgi.py +16 -0
  95. open_swarm-0.1.1743070217/tests/test_apps.py +11 -0
  96. open_swarm-0.1.1743070217/tests/test_blueprint_base.py +155 -0
  97. open_swarm-0.1.1743070217/tests/test_blueprint_base_unit.py +85 -0
  98. open_swarm-0.1.1743070217/tests/test_blueprint_discovery.py +146 -0
  99. open_swarm-0.1.1743070217/tests/test_blueprint_filter.py +24 -0
  100. open_swarm-0.1.1743070217/tests/test_blueprint_loading.py +26 -0
  101. open_swarm-0.1.1743070217/tests/test_blueprint_runner.py +71 -0
  102. open_swarm-0.1.1743070217/tests/test_blueprints.py +118 -0
  103. open_swarm-0.1.1743070217/tests/test_chat.py +153 -0
  104. open_swarm-0.1.1743070217/tests/test_cli_mode_selection.py +28 -0
  105. open_swarm-0.1.1743070217/tests/test_config_loader.py +380 -0
  106. open_swarm-0.1.1743070217/tests/test_core_chatmessage.py +15 -0
  107. open_swarm-0.1.1743070217/tests/test_core_filter_duplicate_system_messages.py +78 -0
  108. open_swarm-0.1.1743070217/tests/test_core_filter_messages.py +70 -0
  109. open_swarm-0.1.1743070217/tests/test_core_truncate_message_history.py +193 -0
  110. open_swarm-0.1.1743070217/tests/test_core_update_null_content.py +70 -0
  111. open_swarm-0.1.1743070217/tests/test_dummy.py +1 -0
  112. open_swarm-0.1.1743070217/tests/test_list_models.py +104 -0
  113. open_swarm-0.1.1743070217/tests/test_message_sequence.py +102 -0
  114. open_swarm-0.1.1743070217/tests/test_models.py +58 -0
  115. open_swarm-0.1.1743070217/tests/test_openai_api_key_handling.py +34 -0
  116. open_swarm-0.1.1743070217/tests/test_redact.py +104 -0
  117. open_swarm-0.1.1743070217/tests/test_resource_timeout.py +59 -0
  118. open_swarm-0.1.1743070217/tests/test_settings.py +16 -0
  119. open_swarm-0.1.1743070217/tests/test_setup_wizard.py +113 -0
  120. open_swarm-0.1.1743070217/tests/test_swarm_init.py +66 -0
  121. open_swarm-0.1.1743070217/tests/test_swarm_types.py +36 -0
  122. open_swarm-0.1.1743070217/tests/test_truncate_message_history.py +204 -0
  123. open_swarm-0.1.1743070217/tests/test_util.py +16 -0
  124. open_swarm-0.1.1743070217/tests/test_utils_coverage.py +79 -0
  125. open_swarm-0.1.1743070217/tests/test_views.py +116 -0
  126. open_swarm-0.1.1743070217/tests/test_wsgi.py +10 -0
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2024 mhand
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -0,0 +1,258 @@
1
+ Metadata-Version: 2.4
2
+ Name: open-swarm
3
+ Version: 0.1.1743070217
4
+ Summary: A tool for orchestrating Swarm using both CLI and API.
5
+ Author-email: Matthew Hand <matthewhandau@gmail.com>
6
+ Requires-Python: >=3.10
7
+ Description-Content-Type: text/markdown
8
+ License-File: LICENSE
9
+ Requires-Dist: aiofiles>=24.1.0
10
+ Requires-Dist: aiohttp>=3.11.11
11
+ Requires-Dist: asyncio>=3.4.3
12
+ Requires-Dist: asynctest>=0.13.0
13
+ Requires-Dist: channels>=4.2.0
14
+ Requires-Dist: colorama>=0.4.6
15
+ Requires-Dist: django<5.0,>=4.2
16
+ Requires-Dist: django-allauth>=65.3.1
17
+ Requires-Dist: django-template-debug>=0.3.5
18
+ Requires-Dist: djangorestframework>=3.15.2
19
+ Requires-Dist: flask>=3.1.0
20
+ Requires-Dist: jmespath>=1.0.1
21
+ Requires-Dist: jsonschema-pydantic>=0.6
22
+ Requires-Dist: mcp>=1.2.0
23
+ Requires-Dist: openai>=1.58.1
24
+ Requires-Dist: python-dotenv>=1.0.1
25
+ Requires-Dist: redis>=5.2.1
26
+ Requires-Dist: requests>=2.32.3
27
+ Requires-Dist: whitenoise>=6.8.2
28
+ Requires-Dist: drf-spectacular>=0.23.0
29
+ Requires-Dist: pyinstaller>=6.12.0
30
+ Requires-Dist: tiktoken>=0.9.0
31
+ Requires-Dist: django-cors-headers>=4.7.0
32
+ Requires-Dist: cachetools>=5.5.2
33
+ Provides-Extra: dev
34
+ Requires-Dist: pytest>=8.3.4; extra == "dev"
35
+ Requires-Dist: pytest-asyncio>=0.25.1; extra == "dev"
36
+ Requires-Dist: pytest-cov>=6.0.0; extra == "dev"
37
+ Requires-Dist: pytest-django>=4.9.0; extra == "dev"
38
+ Requires-Dist: pytest-mock>=3.14.0; extra == "dev"
39
+ Requires-Dist: python-semantic-release>=9.20.0; extra == "dev"
40
+ Provides-Extra: experimental
41
+ Requires-Dist: nemoguardrails>=0.11.0; extra == "experimental"
42
+ Dynamic: license-file
43
+
44
+ # Open Swarm
45
+
46
+ <div align="center">
47
+ <img src="assets/images/openswarm-project-image.jpg" alt="Project Logo" width="70%"/>
48
+ </div>
49
+
50
+ **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.
51
+
52
+ ---
53
+
54
+ https://github.com/user-attachments/assets/1335f7fb-ff61-4e96-881c-7d3154eb9f14
55
+
56
+ (generated by www.gitpodcast.com)
57
+
58
+ ---
59
+
60
+ ## Table of Contents
61
+ - [Key Features](#key-features)
62
+ - [Quickstart](#quickstart)
63
+ - [Blueprints](#blueprints)
64
+ - [Further Documentation](#further-documentation)
65
+ - [License](#license)
66
+ - [Acknowledgements](#acknowledgements)
67
+
68
+ ---
69
+
70
+ ## Key Features
71
+
72
+ 1. **Multi-Agent Orchestration**
73
+ - Define multiple agents, each with unique instructions and roles.
74
+ - Agents coordinate tasks, share context, or hand off queries between one another.
75
+
76
+ 2. **Blueprint-Driven Architecture**
77
+ - Each **Blueprint** encapsulates logic, tool connections, and environment/config settings.
78
+ - Encourages reusable, modular patterns for different use cases.
79
+
80
+ 3. **Optional MCP Integration**
81
+ - Integrate with external tools (e.g., databases, web search, filesystems) through **MCP servers**.
82
+ - Note `npx` MCP servers work great but `uvx` MCP servers currently have issues.
83
+
84
+ 4. **CLI & REST Interface**
85
+ - Run from the command line or expose a Django-powered REST API for broader integration.
86
+ - Interactive web pages per blueprint at `/<blueprint_name>/`.
87
+
88
+ 5. **OpenAI API Compatibility**
89
+ - Exposes an endpoint at `/v1/chat/completions` that is functionally similar to the OpenAI Chat Completions API.
90
+ - Includes a **mandatory** `sender` field in agent responses.
91
+ - This field identifies which Swarm agent provided the response and must be preserved in the conversation history for proper handoffs between agents.
92
+ - 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.
93
+ - **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.
94
+
95
+ 6. **Configurable LLMs**
96
+ - Supports multiple OpenAI-compatible providers in a single environment (e.g., `openai`, `grok`, `ollama`).
97
+ - Allows specifying different models/providers for different agents—even within the same blueprint.
98
+ - Use environment variable `DEFAULT_LLM` to specify default LLM model used by blueprints, e.g., `DEFAULT_LLM=deepseek-r1-distill-llama-70b`
99
+
100
+ ---
101
+
102
+ ## Quickstart
103
+
104
+ Follow these simple steps to get Open Swarm up and running:
105
+
106
+ 1. **Install the Package**
107
+ Run:
108
+ ```bash
109
+ pip install open-swarm
110
+ ```
111
+
112
+ 2. **Configure an LLM Provider**
113
+ 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:
114
+ ```json
115
+ {
116
+ "llm": {
117
+ "default": {
118
+ "provider": "openai",
119
+ "model": "gpt-4o",
120
+ "base_url": "https://api.openai.com/v1",
121
+ "api_key": "${OPENAI_API_KEY}"
122
+ }
123
+ },
124
+ "mcpServers": {}
125
+ }
126
+ ```
127
+ Make sure to set the `OPENAI_API_KEY` environment variable with your valid OpenAI API key.
128
+
129
+ An example of using an alternative provider:
130
+
131
+ `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}"}' `
132
+
133
+
134
+ 3. **(Optional) Configure a Simple MCP Server**
135
+ To add an MCP server for additional utilities (e.g., file fetching), use the `swarm-cli config add --json '<multiline_json_block>'`. For example:
136
+
137
+ ```json
138
+ "filesystem": {
139
+ "command": "npx",
140
+ "args": [
141
+ "-y",
142
+ "@modelcontextprotocol/server-filesystem ${ALLOWED_PATH}"
143
+ ],
144
+ "env": {
145
+ "ALLOWED_PATH": "${ALLOWED_PATH}"
146
+ }
147
+ }
148
+ ```
149
+
150
+ 4. **Add an Example Blueprint**
151
+ Add an example blueprint by running:
152
+ ```bash
153
+ swarm-cli add /path/to/your/blueprint.py --name example
154
+ ```
155
+ This copies your blueprint into the managed blueprints directory.
156
+
157
+ Example blueprints are provided here: https://github.com/matthewhand/open-swarm/tree/main/blueprints
158
+
159
+ 5. **Run the Blueprint from CLI**
160
+ Execute the blueprint with:
161
+ ```bash
162
+ swarm-cli run example
163
+ ```
164
+
165
+ ---
166
+
167
+ ## Overview
168
+
169
+ Open Swarm provides the following core components:
170
+
171
+ - **Swarm CLI:**
172
+ 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.
173
+
174
+ - **Swarm API:**
175
+ 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.
176
+
177
+ - **Swarm SDK:**
178
+ 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.
179
+
180
+ For detailed usage instructions, please refer to the [USERGUIDE.md](./USERGUIDE.md). For developer-specific guidance, see [DEVELOPMENT.md](./DEVELOPMENT.md).
181
+
182
+ ---
183
+
184
+
185
+ ## Blueprints
186
+
187
+ A **Blueprint** is a Python module that wraps:
188
+
189
+ - **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.
190
+ - **Tools**: Specifies which agents have which tools (e.g., MCP-discovered tools, Python function calls).
191
+ - **Environment & Configuration**: Ensures required environment variables and JSON configs are validated prior to agent execution.
192
+
193
+ Once registered, a blueprint is discoverable at runtime, allowing the system to list and load agents on demand.
194
+
195
+ ### Personal Assistant Example
196
+
197
+ The **Personal Assistant Blueprint** demonstrates a hybrid approach, integrating **local Python function tools** with **MCP-discovered tools**. It consists of:
198
+
199
+ 1. **Personal Assistant Agent**
200
+ - Determines user intent and delegates queries accordingly.
201
+ - Routes weather-related queries to the `WeatherAgent`.
202
+ - Routes knowledge-based queries to the `DocumentationAgent`.
203
+
204
+ 2. **Weather Agent** (Uses Python Function Tools)
205
+ - Fetches current weather and forecasts via OpenWeatherMap.
206
+ - Uses a **locally defined Python function** rather than an MCP server.
207
+ - Requires `WEATHER_API_KEY` as an environment variable.
208
+
209
+ 3. **Documentation Agent** (Uses MCP-Discovered Tools)
210
+ - Retrieves relevant documentation via `rag-docs`.
211
+ - Uses the MCP function `search_documentation` to dynamically retrieve information.
212
+ - Requires the following environment variables:
213
+ - `OPENAI_API_KEY`
214
+ - `QDRANT_URL`
215
+ - `QDRANT_API_KEY`
216
+
217
+ This blueprint highlights **seamless multi-agent coordination** and the **flexibility of combining Python functions with MCP-discovered tools**.
218
+
219
+ ### Other Examples
220
+
221
+ Open Swarm includes a growing library of **Blueprint** examples:
222
+
223
+ | Blueprint Name | Description | Status |
224
+ |------------------------------|-----------------------------------------------------------------------------|-----------------------------------------|
225
+ | **Echo Blueprint** | A straightforward agent that simply echoes user inputs—ideal for testing or as a starter template. | Stable |
226
+ | **Suggestion Blueprint** | Blueprint providing suggestions and recommendations. | Stable |
227
+ | **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 |
228
+ | **University Blueprint** | Multi-agent system for university-related tasks. | Stable |
229
+ | **Divine Ops Blueprint** | Multi-agent system for handling system administration tasks using MCP tools (filesystem, SQLite, search, etc.). | Stable |
230
+ | **Nebucha Shellzzar Blueprint**| Example system administration blueprint. | Stable |
231
+ | **Personal Assistant Blueprint** | Combines real-time weather updates (Python function) with documentation search (`rag-docs`, MCP). Demonstrates mixed tooling. | Broken (uvx-based) |
232
+ | **Flowise Blueprint** | Integrates with Flowise for visual flow orchestration. | Broken (uvx-based, requires Flowise setup)|
233
+
234
+ ---
235
+ ---
236
+
237
+ ## Further Documentation
238
+
239
+ 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.
240
+
241
+ ---
242
+
243
+ ## License
244
+
245
+ Open Swarm is provided under the MIT License. Refer to the [LICENSE](LICENSE) file for full details.
246
+
247
+ ---
248
+
249
+ ## Acknowledgements
250
+
251
+ 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.
252
+ We also wish to credit [django_chatbot](https://github.com/MattiPaivike/django_chatbot) for the Django chatbot view.
253
+
254
+ ### Third-Party Libraries
255
+ - **[Marked.js](https://github.com/markedjs/marked)** (MIT License)
256
+ A fast, lightweight library for parsing Markdown into HTML.
257
+ - **[Tabler Icons](https://tablericons.com)** (MIT License)
258
+ A set of free, high-quality SVG icons for web projects, designed by Paweł Kuna.
@@ -0,0 +1,215 @@
1
+ # Open Swarm
2
+
3
+ <div align="center">
4
+ <img src="assets/images/openswarm-project-image.jpg" alt="Project Logo" width="70%"/>
5
+ </div>
6
+
7
+ **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.
8
+
9
+ ---
10
+
11
+ https://github.com/user-attachments/assets/1335f7fb-ff61-4e96-881c-7d3154eb9f14
12
+
13
+ (generated by www.gitpodcast.com)
14
+
15
+ ---
16
+
17
+ ## Table of Contents
18
+ - [Key Features](#key-features)
19
+ - [Quickstart](#quickstart)
20
+ - [Blueprints](#blueprints)
21
+ - [Further Documentation](#further-documentation)
22
+ - [License](#license)
23
+ - [Acknowledgements](#acknowledgements)
24
+
25
+ ---
26
+
27
+ ## Key Features
28
+
29
+ 1. **Multi-Agent Orchestration**
30
+ - Define multiple agents, each with unique instructions and roles.
31
+ - Agents coordinate tasks, share context, or hand off queries between one another.
32
+
33
+ 2. **Blueprint-Driven Architecture**
34
+ - Each **Blueprint** encapsulates logic, tool connections, and environment/config settings.
35
+ - Encourages reusable, modular patterns for different use cases.
36
+
37
+ 3. **Optional MCP Integration**
38
+ - Integrate with external tools (e.g., databases, web search, filesystems) through **MCP servers**.
39
+ - Note `npx` MCP servers work great but `uvx` MCP servers currently have issues.
40
+
41
+ 4. **CLI & REST Interface**
42
+ - Run from the command line or expose a Django-powered REST API for broader integration.
43
+ - Interactive web pages per blueprint at `/<blueprint_name>/`.
44
+
45
+ 5. **OpenAI API Compatibility**
46
+ - Exposes an endpoint at `/v1/chat/completions` that is functionally similar to the OpenAI Chat Completions API.
47
+ - Includes a **mandatory** `sender` field in agent responses.
48
+ - This field identifies which Swarm agent provided the response and must be preserved in the conversation history for proper handoffs between agents.
49
+ - 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.
50
+ - **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.
51
+
52
+ 6. **Configurable LLMs**
53
+ - Supports multiple OpenAI-compatible providers in a single environment (e.g., `openai`, `grok`, `ollama`).
54
+ - Allows specifying different models/providers for different agents—even within the same blueprint.
55
+ - Use environment variable `DEFAULT_LLM` to specify default LLM model used by blueprints, e.g., `DEFAULT_LLM=deepseek-r1-distill-llama-70b`
56
+
57
+ ---
58
+
59
+ ## Quickstart
60
+
61
+ Follow these simple steps to get Open Swarm up and running:
62
+
63
+ 1. **Install the Package**
64
+ Run:
65
+ ```bash
66
+ pip install open-swarm
67
+ ```
68
+
69
+ 2. **Configure an LLM Provider**
70
+ 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:
71
+ ```json
72
+ {
73
+ "llm": {
74
+ "default": {
75
+ "provider": "openai",
76
+ "model": "gpt-4o",
77
+ "base_url": "https://api.openai.com/v1",
78
+ "api_key": "${OPENAI_API_KEY}"
79
+ }
80
+ },
81
+ "mcpServers": {}
82
+ }
83
+ ```
84
+ Make sure to set the `OPENAI_API_KEY` environment variable with your valid OpenAI API key.
85
+
86
+ An example of using an alternative provider:
87
+
88
+ `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}"}' `
89
+
90
+
91
+ 3. **(Optional) Configure a Simple MCP Server**
92
+ To add an MCP server for additional utilities (e.g., file fetching), use the `swarm-cli config add --json '<multiline_json_block>'`. For example:
93
+
94
+ ```json
95
+ "filesystem": {
96
+ "command": "npx",
97
+ "args": [
98
+ "-y",
99
+ "@modelcontextprotocol/server-filesystem ${ALLOWED_PATH}"
100
+ ],
101
+ "env": {
102
+ "ALLOWED_PATH": "${ALLOWED_PATH}"
103
+ }
104
+ }
105
+ ```
106
+
107
+ 4. **Add an Example Blueprint**
108
+ Add an example blueprint by running:
109
+ ```bash
110
+ swarm-cli add /path/to/your/blueprint.py --name example
111
+ ```
112
+ This copies your blueprint into the managed blueprints directory.
113
+
114
+ Example blueprints are provided here: https://github.com/matthewhand/open-swarm/tree/main/blueprints
115
+
116
+ 5. **Run the Blueprint from CLI**
117
+ Execute the blueprint with:
118
+ ```bash
119
+ swarm-cli run example
120
+ ```
121
+
122
+ ---
123
+
124
+ ## Overview
125
+
126
+ Open Swarm provides the following core components:
127
+
128
+ - **Swarm CLI:**
129
+ 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.
130
+
131
+ - **Swarm API:**
132
+ 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.
133
+
134
+ - **Swarm SDK:**
135
+ 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.
136
+
137
+ For detailed usage instructions, please refer to the [USERGUIDE.md](./USERGUIDE.md). For developer-specific guidance, see [DEVELOPMENT.md](./DEVELOPMENT.md).
138
+
139
+ ---
140
+
141
+
142
+ ## Blueprints
143
+
144
+ A **Blueprint** is a Python module that wraps:
145
+
146
+ - **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.
147
+ - **Tools**: Specifies which agents have which tools (e.g., MCP-discovered tools, Python function calls).
148
+ - **Environment & Configuration**: Ensures required environment variables and JSON configs are validated prior to agent execution.
149
+
150
+ Once registered, a blueprint is discoverable at runtime, allowing the system to list and load agents on demand.
151
+
152
+ ### Personal Assistant Example
153
+
154
+ The **Personal Assistant Blueprint** demonstrates a hybrid approach, integrating **local Python function tools** with **MCP-discovered tools**. It consists of:
155
+
156
+ 1. **Personal Assistant Agent**
157
+ - Determines user intent and delegates queries accordingly.
158
+ - Routes weather-related queries to the `WeatherAgent`.
159
+ - Routes knowledge-based queries to the `DocumentationAgent`.
160
+
161
+ 2. **Weather Agent** (Uses Python Function Tools)
162
+ - Fetches current weather and forecasts via OpenWeatherMap.
163
+ - Uses a **locally defined Python function** rather than an MCP server.
164
+ - Requires `WEATHER_API_KEY` as an environment variable.
165
+
166
+ 3. **Documentation Agent** (Uses MCP-Discovered Tools)
167
+ - Retrieves relevant documentation via `rag-docs`.
168
+ - Uses the MCP function `search_documentation` to dynamically retrieve information.
169
+ - Requires the following environment variables:
170
+ - `OPENAI_API_KEY`
171
+ - `QDRANT_URL`
172
+ - `QDRANT_API_KEY`
173
+
174
+ This blueprint highlights **seamless multi-agent coordination** and the **flexibility of combining Python functions with MCP-discovered tools**.
175
+
176
+ ### Other Examples
177
+
178
+ Open Swarm includes a growing library of **Blueprint** examples:
179
+
180
+ | Blueprint Name | Description | Status |
181
+ |------------------------------|-----------------------------------------------------------------------------|-----------------------------------------|
182
+ | **Echo Blueprint** | A straightforward agent that simply echoes user inputs—ideal for testing or as a starter template. | Stable |
183
+ | **Suggestion Blueprint** | Blueprint providing suggestions and recommendations. | Stable |
184
+ | **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 |
185
+ | **University Blueprint** | Multi-agent system for university-related tasks. | Stable |
186
+ | **Divine Ops Blueprint** | Multi-agent system for handling system administration tasks using MCP tools (filesystem, SQLite, search, etc.). | Stable |
187
+ | **Nebucha Shellzzar Blueprint**| Example system administration blueprint. | Stable |
188
+ | **Personal Assistant Blueprint** | Combines real-time weather updates (Python function) with documentation search (`rag-docs`, MCP). Demonstrates mixed tooling. | Broken (uvx-based) |
189
+ | **Flowise Blueprint** | Integrates with Flowise for visual flow orchestration. | Broken (uvx-based, requires Flowise setup)|
190
+
191
+ ---
192
+ ---
193
+
194
+ ## Further Documentation
195
+
196
+ 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.
197
+
198
+ ---
199
+
200
+ ## License
201
+
202
+ Open Swarm is provided under the MIT License. Refer to the [LICENSE](LICENSE) file for full details.
203
+
204
+ ---
205
+
206
+ ## Acknowledgements
207
+
208
+ 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.
209
+ We also wish to credit [django_chatbot](https://github.com/MattiPaivike/django_chatbot) for the Django chatbot view.
210
+
211
+ ### Third-Party Libraries
212
+ - **[Marked.js](https://github.com/markedjs/marked)** (MIT License)
213
+ A fast, lightweight library for parsing Markdown into HTML.
214
+ - **[Tabler Icons](https://tablericons.com)** (MIT License)
215
+ A set of free, high-quality SVG icons for web projects, designed by Paweł Kuna.
@@ -0,0 +1,61 @@
1
+ [project]
2
+ name = "open-swarm"
3
+ version = "0.1.1743070217"
4
+ description = "A tool for orchestrating Swarm using both CLI and API."
5
+ readme = "README.md"
6
+ authors = [
7
+ { name = "Matthew Hand", email = "matthewhandau@gmail.com" }
8
+ ]
9
+ requires-python = ">=3.10"
10
+ dependencies = [
11
+ "aiofiles>=24.1.0",
12
+ "aiohttp>=3.11.11",
13
+ "asyncio>=3.4.3",
14
+ "asynctest>=0.13.0",
15
+ "channels>=4.2.0",
16
+ "colorama>=0.4.6",
17
+ "django>=4.2,<5.0",
18
+ "django-allauth>=65.3.1",
19
+ "django-template-debug>=0.3.5",
20
+ "djangorestframework>=3.15.2",
21
+ "flask>=3.1.0",
22
+ "jmespath>=1.0.1",
23
+ "jsonschema-pydantic>=0.6",
24
+ "mcp>=1.2.0",
25
+ "openai>=1.58.1",
26
+ "python-dotenv>=1.0.1",
27
+ "redis>=5.2.1",
28
+ "requests>=2.32.3",
29
+ "whitenoise>=6.8.2",
30
+ "drf-spectacular>=0.23.0",
31
+ "pyinstaller>=6.12.0",
32
+ "tiktoken>=0.9.0",
33
+ "django-cors-headers>=4.7.0",
34
+ "cachetools>=5.5.2",
35
+ ]
36
+
37
+ [project.scripts]
38
+ swarm-cli = "swarm.extensions.launchers.swarm_cli:main"
39
+ swarm-api = "swarm.extensions.launchers.swarm_api:main"
40
+
41
+ [project.optional-dependencies]
42
+ dev = [
43
+ "pytest>=8.3.4",
44
+ "pytest-asyncio>=0.25.1",
45
+ "pytest-cov>=6.0.0",
46
+ "pytest-django>=4.9.0",
47
+ "pytest-mock>=3.14.0",
48
+ "python-semantic-release>=9.20.0",
49
+ ]
50
+
51
+ experimental = [
52
+ "nemoguardrails>=0.11.0",
53
+ ]
54
+
55
+ [build-system]
56
+ requires = ["setuptools", "wheel"]
57
+ build-backend = "setuptools.build_meta"
58
+
59
+ [tool.pytest.ini_options]
60
+ DJANGO_SETTINGS_MODULE = "src.swarm.settings"
61
+ pythonpath = ["src"]
@@ -0,0 +1,4 @@
1
+ [egg_info]
2
+ tag_build =
3
+ tag_date = 0
4
+