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

{open_swarm-0.1.1743362777 → open_swarm-0.1.1743364176}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: open-swarm
-Version: 0.1.1743362777
+Version: 0.1.1743364176
 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
@@ -40,6 +40,7 @@ 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: jmespath>=1.0.1
 Requires-Dist: openai-agents>=0.0.1
 Requires-Dist: openai<2.0.0,>=1.3.0
 Requires-Dist: platformdirs>=4.0.0
@@ -92,6 +93,11 @@ Description-Content-Type: text/markdown
 
 **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**.
 
+Open Swarm can be used in two primary ways:
+
+1.  **As a CLI Utility (`swarm-cli`):** Manage, run, and install blueprints directly on your local machine. Ideal for personal use, testing, and creating standalone agent tools. (Recommended installation: PyPI)
+2.  **As an API Service (`swarm-api`):** Deploy a web server that exposes your blueprints via an OpenAI-compatible REST API. Ideal for integrations, web UIs, and shared access. (Recommended deployment: Docker)
+
 ---
 
 ## Core Concepts
@@ -105,97 +111,160 @@ Description-Content-Type: text/markdown
 
 ---
 
-## Quickstart (Docker - Recommended)
+## Quickstart 1: Using `swarm-cli` Locally (via PyPI)
 
-This is the easiest and recommended way to get started, especially for deploying the API service.
+This is the recommended way to use `swarm-cli` for managing and running blueprints on your local machine.
 
 **Prerequisites:**
-*   Docker ([Install Docker](https://docs.docker.com/engine/install/))
-*   Docker Compose ([Install Docker Compose](https://docs.docker.com/compose/install/))
+*   Python 3.10+
+*   `pip` (Python package installer)
 
 **Steps:**
 
-1.  **Clone the Repository:**
+1.  **Install `open-swarm` from PyPI:**
     ```bash
-    git clone https://github.com/matthewhand/open-swarm.git
-    cd open-swarm
+    pip install open-swarm
     ```
+    *(Using a virtual environment is recommended: `python -m venv .venv && source .venv/bin/activate`)*
 
-2.  **Configure Environment:**
-    *   Copy the example environment file:
+2.  **Initial Configuration (First Run):**
+    *   The first time you run a `swarm-cli` command that requires configuration (like `run` or `config`), it will automatically create a default `swarm_config.json` at `~/.config/swarm/swarm_config.json` if one doesn't exist.
+    *   You **must** set the required environment variables (like `OPENAI_API_KEY`) in your shell for the configuration to work. Create a `.env` file in your working directory or export them:
         ```bash
-        cp .env.example .env
+        export OPENAI_API_KEY="sk-..."
+        # Add other keys as needed (GROQ_API_KEY, etc.)
         ```
-    *   Edit `.env` and add your necessary API keys (e.g., `OPENAI_API_KEY`).
+    *   You can customize the configuration further using `swarm-cli config` commands (see `USERGUIDE.md`).
 
-3.  **Configure Docker Compose Overrides (Optional but Recommended):**
-    *   Copy the override example:
+3.  **Add a Blueprint:**
+    *   Download or create a blueprint file (e.g., `my_blueprint.py`). Example blueprints are available in the [project repository](https://github.com/matthewhand/open-swarm/tree/main/src/swarm/blueprints).
+    *   Add it using `swarm-cli`:
         ```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.).
+        # Example: Adding a downloaded blueprint file
+        swarm-cli add ./path/to/downloaded/blueprint_echocraft.py
 
-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).
+        # Example: Adding a directory containing a blueprint
+        swarm-cli add ./my_custom_blueprints/agent_smith --name agent_smith
+        ```
 
-5.  **Verify API:**
-    *   Check the available models (blueprints):
+4.  **Run the Blueprint:**
+    *   **Single Instruction:**
         ```bash
-        curl http://localhost:8000/v1/models
+        swarm-cli run echocraft --instruction "Hello from CLI!"
         ```
-    *   Send a chat completion request:
+    *   **Interactive Mode:**
         ```bash
-        curl http://localhost:8000/v1/chat/completions \
-          -H "Content-Type: application/json" \
-          -d '{
-                "model": "echocraft",
-                "messages": [{"role": "user", "content": "Hello Docker!"}]
-              }'
+        swarm-cli run echocraft
+        # Now you can chat with the blueprint interactively
         ```
-        *(Replace `echocraft` with a blueprint name available in your mounted volumes or the base image).*
+
+5.  **(Optional) Install as Command:**
+    ```bash
+    swarm-cli install echocraft
+    # Now run (ensure ~/.local/share/swarm/bin is in your PATH):
+    echocraft --instruction "I am a command now!"
+    ```
 
 ---
 
-## Usage Modes
+## Quickstart 2: Deploying `swarm-api` Service (via Docker)
+
+This section covers deploying the API service using Docker.
+
+### Option A: Docker Compose (Recommended for Flexibility)
+
+This method uses `docker-compose.yaml` and is best if you need to customize volumes, environment variables easily, or manage related services (like Redis).
+
+**Prerequisites:**
+*   Docker ([Install Docker](https://docs.docker.com/engine/install/))
+*   Docker Compose ([Install Docker Compose](https://docs.docker.com/compose/install/))
+*   Git
+
+**Steps:**
+
+1.  **Clone the Repository:** (Needed for `docker-compose.yaml` and config files)
+    ```bash
+    git clone https://github.com/matthewhand/open-swarm.git
+    cd open-swarm
+    ```
+
+2.  **Configure Environment:**
+    *   Copy `cp .env.example .env` and edit `.env` with your API keys (e.g., `OPENAI_API_KEY`, `SWARM_API_KEY`).
+
+3.  **Prepare Blueprints & Config:**
+    *   Place blueprints in `./blueprints`.
+    *   Ensure `./swarm_config.json` exists and is configured.
+
+4.  **Configure Overrides (Optional):**
+    *   Copy `cp docker-compose.override.yaml.example docker-compose.override.yaml`.
+    *   Edit the override file to mount additional volumes, change ports, etc.
+
+5.  **Start the Service:**
+    ```bash
+    docker compose up -d
+    ```
+
+6.  **Verify API:** (Default port 8000)
+    *   Models: `curl http://localhost:8000/v1/models`
+    *   Chat: `curl http://localhost:8000/v1/chat/completions -H "Content-Type: application/json" -d '{"model": "echocraft", ...}'` (Add `-H "Authorization: Bearer <key>"` if needed).
+
+### Option B: Direct `docker run` (Simpler for Single Container)
+
+This method runs the pre-built image directly from Docker Hub. Good for quick tests or simple deployments without cloning the repo. Customization requires careful use of `-v` (volume) and `-e` (environment) flags.
+
+**Prerequisites:**
+*   Docker ([Install Docker](https://docs.docker.com/engine/install/))
+
+**Steps:**
 
-Open Swarm offers several ways to interact with your blueprints:
+1.  **Prepare Local Files (If Customizing):**
+    *   Create a directory for your blueprints (e.g., `~/my_swarm_blueprints`).
+    *   Create your `swarm_config.json` file locally (e.g., `~/my_swarm_config.json`).
+    *   Create a `.env` file locally (e.g., `~/swarm.env`) with your API keys (`OPENAI_API_KEY`, `SWARM_API_KEY`, etc.).
 
-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 the Container:**
+    ```bash
+    docker run -d \
+      --name open-swarm-api \
+      -p 8000:8000 \
+      --env-file ~/swarm.env \
+      -v ~/my_swarm_blueprints:/app/blueprints:ro \
+      -v ~/my_swarm_config.json:/app/swarm_config.json:ro \
+      -v open_swarm_db:/app/db.sqlite3 \
+      --restart unless-stopped \
+      mhand79/open-swarm:latest
+    ```
+    *   `-d`: Run detached (in background).
+    *   `--name`: Assign a name to the container.
+    *   `-p 8000:8000`: Map host port 8000 to container port 8000 (adjust if needed).
+    *   `--env-file`: Load environment variables from your local file.
+    *   `-v ...:/app/blueprints:ro`: Mount your local blueprints directory (read-only). **Required** if you want to use custom blueprints.
+    *   `-v ...:/app/swarm_config.json:ro`: Mount your local config file (read-only). **Required** for custom LLM/MCP settings.
+    *   `-v open_swarm_db:/app/db.sqlite3`: Use a named Docker volume for the database to persist data.
+    *   `--restart unless-stopped`: Automatically restart the container unless manually stopped.
+    *   `mhand79/open-swarm:latest`: The image name on Docker Hub.
+
+3.  **Verify API:** (Same as Docker Compose)
+    *   Models: `curl http://localhost:8000/v1/models`
+    *   Chat: `curl http://localhost:8000/v1/chat/completions ...` (Add `-H "Authorization: Bearer <key>"` if needed).
 
-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.
+## Usage Modes Summary
 
-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.
+*   **`swarm-api` (via Docker or `manage.py runserver`):** Exposes blueprints as an OpenAI-compatible REST API. Ideal for integrations. Requires `SWARM_API_KEY` for security in non-local deployments.
+*   **`swarm-cli run` (via PyPI install):** Executes managed blueprints locally, either with a single instruction or in interactive chat mode. Good for testing and local tasks.
+*   **`swarm-cli install` (via PyPI install):** Creates standalone command-line executables from managed blueprints.
+*   **Direct Python Execution (via Git clone):** Running `uv run python <blueprint_file.py>` is mainly for development and testing individual files.
 
 ---
 
 ## Further Documentation
 
-This README provides a high-level overview and quickstart. For more detailed information, please refer to:
+This README provides a high-level overview and quickstart guides. 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.
+*   **User Guide (`USERGUIDE.md`):** Detailed instructions on using `swarm-cli` commands for managing blueprints and configuration locally.
+*   **Development Guide (`DEVELOPMENT.md`):** Information for contributors and developers, including architecture details, testing strategies, project layout, API details, and advanced topics.
 *   **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.
 
 ---

open_swarm-0.1.1743364176/README.md

@@ -0,0 +1,199 @@
+# 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**.
+
+Open Swarm can be used in two primary ways:
+
+1.  **As a CLI Utility (`swarm-cli`):** Manage, run, and install blueprints directly on your local machine. Ideal for personal use, testing, and creating standalone agent tools. (Recommended installation: PyPI)
+2.  **As an API Service (`swarm-api`):** Deploy a web server that exposes your blueprints via an OpenAI-compatible REST API. Ideal for integrations, web UIs, and shared access. (Recommended deployment: Docker)
+
+---
+
+## 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 1: Using `swarm-cli` Locally (via PyPI)
+
+This is the recommended way to use `swarm-cli` for managing and running blueprints on your local machine.
+
+**Prerequisites:**
+*   Python 3.10+
+*   `pip` (Python package installer)
+
+**Steps:**
+
+1.  **Install `open-swarm` from PyPI:**
+    ```bash
+    pip install open-swarm
+    ```
+    *(Using a virtual environment is recommended: `python -m venv .venv && source .venv/bin/activate`)*
+
+2.  **Initial Configuration (First Run):**
+    *   The first time you run a `swarm-cli` command that requires configuration (like `run` or `config`), it will automatically create a default `swarm_config.json` at `~/.config/swarm/swarm_config.json` if one doesn't exist.
+    *   You **must** set the required environment variables (like `OPENAI_API_KEY`) in your shell for the configuration to work. Create a `.env` file in your working directory or export them:
+        ```bash
+        export OPENAI_API_KEY="sk-..."
+        # Add other keys as needed (GROQ_API_KEY, etc.)
+        ```
+    *   You can customize the configuration further using `swarm-cli config` commands (see `USERGUIDE.md`).
+
+3.  **Add a Blueprint:**
+    *   Download or create a blueprint file (e.g., `my_blueprint.py`). Example blueprints are available in the [project repository](https://github.com/matthewhand/open-swarm/tree/main/src/swarm/blueprints).
+    *   Add it using `swarm-cli`:
+        ```bash
+        # Example: Adding a downloaded blueprint file
+        swarm-cli add ./path/to/downloaded/blueprint_echocraft.py
+
+        # Example: Adding a directory containing a blueprint
+        swarm-cli add ./my_custom_blueprints/agent_smith --name agent_smith
+        ```
+
+4.  **Run the Blueprint:**
+    *   **Single Instruction:**
+        ```bash
+        swarm-cli run echocraft --instruction "Hello from CLI!"
+        ```
+    *   **Interactive Mode:**
+        ```bash
+        swarm-cli run echocraft
+        # Now you can chat with the blueprint interactively
+        ```
+
+5.  **(Optional) Install as Command:**
+    ```bash
+    swarm-cli install echocraft
+    # Now run (ensure ~/.local/share/swarm/bin is in your PATH):
+    echocraft --instruction "I am a command now!"
+    ```
+
+---
+
+## Quickstart 2: Deploying `swarm-api` Service (via Docker)
+
+This section covers deploying the API service using Docker.
+
+### Option A: Docker Compose (Recommended for Flexibility)
+
+This method uses `docker-compose.yaml` and is best if you need to customize volumes, environment variables easily, or manage related services (like Redis).
+
+**Prerequisites:**
+*   Docker ([Install Docker](https://docs.docker.com/engine/install/))
+*   Docker Compose ([Install Docker Compose](https://docs.docker.com/compose/install/))
+*   Git
+
+**Steps:**
+
+1.  **Clone the Repository:** (Needed for `docker-compose.yaml` and config files)
+    ```bash
+    git clone https://github.com/matthewhand/open-swarm.git
+    cd open-swarm
+    ```
+
+2.  **Configure Environment:**
+    *   Copy `cp .env.example .env` and edit `.env` with your API keys (e.g., `OPENAI_API_KEY`, `SWARM_API_KEY`).
+
+3.  **Prepare Blueprints & Config:**
+    *   Place blueprints in `./blueprints`.
+    *   Ensure `./swarm_config.json` exists and is configured.
+
+4.  **Configure Overrides (Optional):**
+    *   Copy `cp docker-compose.override.yaml.example docker-compose.override.yaml`.
+    *   Edit the override file to mount additional volumes, change ports, etc.
+
+5.  **Start the Service:**
+    ```bash
+    docker compose up -d
+    ```
+
+6.  **Verify API:** (Default port 8000)
+    *   Models: `curl http://localhost:8000/v1/models`
+    *   Chat: `curl http://localhost:8000/v1/chat/completions -H "Content-Type: application/json" -d '{"model": "echocraft", ...}'` (Add `-H "Authorization: Bearer <key>"` if needed).
+
+### Option B: Direct `docker run` (Simpler for Single Container)
+
+This method runs the pre-built image directly from Docker Hub. Good for quick tests or simple deployments without cloning the repo. Customization requires careful use of `-v` (volume) and `-e` (environment) flags.
+
+**Prerequisites:**
+*   Docker ([Install Docker](https://docs.docker.com/engine/install/))
+
+**Steps:**
+
+1.  **Prepare Local Files (If Customizing):**
+    *   Create a directory for your blueprints (e.g., `~/my_swarm_blueprints`).
+    *   Create your `swarm_config.json` file locally (e.g., `~/my_swarm_config.json`).
+    *   Create a `.env` file locally (e.g., `~/swarm.env`) with your API keys (`OPENAI_API_KEY`, `SWARM_API_KEY`, etc.).
+
+2.  **Run the Container:**
+    ```bash
+    docker run -d \
+      --name open-swarm-api \
+      -p 8000:8000 \
+      --env-file ~/swarm.env \
+      -v ~/my_swarm_blueprints:/app/blueprints:ro \
+      -v ~/my_swarm_config.json:/app/swarm_config.json:ro \
+      -v open_swarm_db:/app/db.sqlite3 \
+      --restart unless-stopped \
+      mhand79/open-swarm:latest
+    ```
+    *   `-d`: Run detached (in background).
+    *   `--name`: Assign a name to the container.
+    *   `-p 8000:8000`: Map host port 8000 to container port 8000 (adjust if needed).
+    *   `--env-file`: Load environment variables from your local file.
+    *   `-v ...:/app/blueprints:ro`: Mount your local blueprints directory (read-only). **Required** if you want to use custom blueprints.
+    *   `-v ...:/app/swarm_config.json:ro`: Mount your local config file (read-only). **Required** for custom LLM/MCP settings.
+    *   `-v open_swarm_db:/app/db.sqlite3`: Use a named Docker volume for the database to persist data.
+    *   `--restart unless-stopped`: Automatically restart the container unless manually stopped.
+    *   `mhand79/open-swarm:latest`: The image name on Docker Hub.
+
+3.  **Verify API:** (Same as Docker Compose)
+    *   Models: `curl http://localhost:8000/v1/models`
+    *   Chat: `curl http://localhost:8000/v1/chat/completions ...` (Add `-H "Authorization: Bearer <key>"` if needed).
+
+---
+
+## Usage Modes Summary
+
+*   **`swarm-api` (via Docker or `manage.py runserver`):** Exposes blueprints as an OpenAI-compatible REST API. Ideal for integrations. Requires `SWARM_API_KEY` for security in non-local deployments.
+*   **`swarm-cli run` (via PyPI install):** Executes managed blueprints locally, either with a single instruction or in interactive chat mode. Good for testing and local tasks.
+*   **`swarm-cli install` (via PyPI install):** Creates standalone command-line executables from managed blueprints.
+*   **Direct Python Execution (via Git clone):** Running `uv run python <blueprint_file.py>` is mainly for development and testing individual files.
+
+---
+
+## Further Documentation
+
+This README provides a high-level overview and quickstart guides. For more detailed information, please refer to:
+
+*   **User Guide (`USERGUIDE.md`):** Detailed instructions on using `swarm-cli` commands for managing blueprints and configuration locally.
+*   **Development Guide (`DEVELOPMENT.md`):** Information for contributors and developers, including architecture details, testing strategies, project layout, API details, and advanced topics.
+*   **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 → open_swarm-0.1.1743364176}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "open-swarm"
-version = "0.1.1743362777"
+version = "0.1.1743364176"
 description = "Open Swarm: Orchestrating AI Agent Swarms with Django"
 readme = "README.md"
 requires-python = ">=3.10"
@@ -58,6 +58,7 @@ dependencies = [
     "openai-agents>=0.0.1",
     "jinja2>=3.1.6",
     "drf-spectacular>=0.28.0",
+    "jmespath>=1.0.1",
 ]
 
 [project.urls]

open_swarm-0.1.1743362777/README.md

@@ -1,131 +0,0 @@
-# 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.