Metadata-Version: 2.4
Name: swarmforge
Version: 3.0.9
Summary: Python SDK for authoring, building, running, and evaluating multi-agent systems.
License-Expression: MIT
Project-URL: Homepage, https://github.com/Rvey/swarm-forge
Project-URL: Repository, https://github.com/Rvey/swarm-forge
Project-URL: Documentation, https://github.com/Rvey/swarm-forge/tree/main/docs
Project-URL: Issues, https://github.com/Rvey/swarm-forge/issues
Keywords: agents,multi-agent,swarm,openrouter,fastapi,evaluation
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Operating System :: OS Independent
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: openai>=1.0.0
Requires-Dist: pydantic>=2.0.0
Requires-Dist: python-dotenv>=1.0.0
Provides-Extra: api
Requires-Dist: fastapi>=0.104.0; extra == "api"
Requires-Dist: uvicorn>=0.24.0; extra == "api"
Provides-Extra: dev
Requires-Dist: build>=1.2.0; extra == "dev"
Requires-Dist: pytest>=8.0.0; extra == "dev"
Requires-Dist: fastapi>=0.104.0; extra == "dev"
Requires-Dist: httpx>=0.27.0; extra == "dev"
Requires-Dist: twine>=5.1.0; extra == "dev"
Dynamic: license-file

# SwarmForge

SwarmForge is a Python SDK for authoring, running, exposing, and evaluating single-agent and multi-agent systems. You define the swarm graph in Python, keep runtime state explicit, and reuse the same orchestration model in direct SDK flows, FastAPI services, and evaluation pipelines.

## Why SwarmForge

- Build graph-based agent systems with explicit nodes, handoffs, tools, and shared state.
- Run swarms directly in Python with streamed runtime events and persisted checkpoints.
- Expose the same runtime through FastAPI for stateless or session-backed HTTP flows.
- Use OpenAI-compatible providers such as OpenRouter, Gemini, and OpenAI.
- Score routing, tool usage, checkpoints, and final state with transport-agnostic evaluation helpers.

## Choose an integration surface

| Surface | Main entrypoints | Use when |
| --- | --- | --- |
| SDK runtime | `SwarmDefinition`, `SwarmSession`, `process_swarm_stream(...)` | You want direct Python control over orchestration, state, and tool execution. |
| FastAPI transport | `create_fastapi_app(...)`, `create_swarm_app(...)` | You want HTTP endpoints on top of the same runtime model. |
| Evaluation | `build_graph_snapshot(...)`, `evaluate_scenario_artifacts(...)` | You want to score runtime behavior in SDK or FastAPI tests. |

## Installation

SwarmForge requires Python `3.11+`.

Install the SDK:

```bash
pip install swarmforge
```

Install the FastAPI transport too:

```bash
pip install "swarmforge[api]"
```

The documentation in this repository tracks the current `main` branch. If you are using a released package from PyPI, prefer the docs that match that version or tag.

## Configure a model provider

Provider-backed examples and local API runs load a nearby `.env` automatically. Start from the repository example file:

```bash
cp .env.example .env
```

Set:

- `MODEL_PROVIDER`
- `LLM_MODEL`
- the matching provider API key such as `OPENROUTER_API_KEY`, `GEMINI_API_KEY`, `GOOGLE_API_KEY`, or `OPENAI_API_KEY`
- optional for OpenRouter: `OPENROUTER_FALLBACK_MODELS` (comma-separated model slugs)

Example `.env` values:

```dotenv
MODEL_PROVIDER=openrouter
LLM_MODEL=openrouter/auto
OPENROUTER_API_KEY=sk-or-...
OPENROUTER_FALLBACK_MODELS=openai/gpt-4o-mini,anthropic/claude-3.5-sonnet
```

```dotenv
MODEL_PROVIDER=gemini
LLM_MODEL=gemini-3-flash-preview
GEMINI_API_KEY=...
```

## Quick start: run a swarm in Python

This example defines a single-node swarm and runs it with the default provider-backed turn runner.

```python
import asyncio
import json

from swarmforge.env import require_env_vars
from swarmforge.evaluation.provider import ModelConfig
from swarmforge.swarm import (
    InMemorySessionStore,
    SwarmDefinition,
    SwarmNode,
    SwarmSession,
    build_turn_runner,
    process_swarm_stream,
)


swarm = SwarmDefinition(
    id="assistant",
    name="Assistant Swarm",
    nodes=[
        SwarmNode(
            id="assistant",
            node_key="assistant",
            name="Assistant",
            system_prompt="You are a concise assistant.",
            is_entry_node=True,
        )
    ],
)


async def main():
    require_env_vars("MODEL_PROVIDER", "LLM_MODEL")
    session = SwarmSession(id="session-1", swarm=swarm)
    store = InMemorySessionStore()
    turn_runner = build_turn_runner(ModelConfig())

    async for event in process_swarm_stream(
        session,
        "Give me a concise summary of SwarmForge.",
        store=store,
        turn_runner=turn_runner,
    ):
        print(json.dumps(event, indent=2))


if __name__ == "__main__":
    asyncio.run(main())
```

Use session state when you want to inject application facts into the runtime:

```python
session = SwarmSession(
    id="session-1",
    swarm=swarm,
    global_variables={"account_id": "ACME-991", "priority": "high"},
)
```

## Quick start: expose the runtime with FastAPI

SwarmForge supports two FastAPI shapes:

- `create_fastapi_app(...)` when the client sends swarm JSON at request time
- `create_swarm_app(...)` when your backend defines the swarm in Python once and exposes a fixed route surface

Installed-package server:

```bash
uvicorn swarmforge.api.fastapi:create_fastapi_app --factory --reload
```

Code-defined swarm server:

```python
from swarmforge.api import create_swarm_app
from swarmforge.evaluation.provider import ModelConfig

app = create_swarm_app(swarm, default_model_config=ModelConfig())
```

Both FastAPI factories use the same runtime model as `process_swarm_stream(...)`, including sessions, handoffs, tools, checkpoints, and state updates.

## Quick start: score runtime behavior

SwarmForge evaluation helpers work on runtime artifacts, so the same scoring flow applies to SDK runs and FastAPI runs.

```python
from swarmforge.evaluation import build_graph_snapshot, evaluate_scenario_artifacts

graph_snapshot = build_graph_snapshot(swarm)

result = evaluate_scenario_artifacts(
    graph_snapshot,
    scenario_seed,
    event_log=events,
    checkpoints=checkpoints,
)

print(result["overall_score"])
```

Use this flow when you want to score routing, state updates, tool usage, minimum turns, and agent coverage.

## Documentation

| Goal | Guide |
| --- | --- |
| Install and orient yourself | [Getting Started](https://github.com/Rvey/swarm-forge/blob/main/docs/getting-started.md) |
| Build a first single-agent swarm | [Create Your First Agent](https://github.com/Rvey/swarm-forge/blob/main/docs/create-first-agent.md) |
| Build a routed multi-agent swarm | [Create Your First Multi-Agent Swarm](https://github.com/Rvey/swarm-forge/blob/main/docs/create-first-multi-agent-swarm.md) |
| Compile and validate swarm definitions | [Authoring](https://github.com/Rvey/swarm-forge/blob/main/docs/authoring.md) |
| Build a conversational prompt-builder flow | [Agent Builder](https://github.com/Rvey/swarm-forge/blob/main/docs/agent-builder.md) |
| Understand orchestration, sessions, tools, and state | [Orchestration](https://github.com/Rvey/swarm-forge/blob/main/docs/orchestration.md) |
| Configure hosted model providers | [Providers](https://github.com/Rvey/swarm-forge/blob/main/docs/providers.md) |
| Add an HTTP layer with FastAPI | [FastAPI](https://github.com/Rvey/swarm-forge/blob/main/docs/api.md) |
| Evaluate SDK and FastAPI runs | [Evaluation](https://github.com/Rvey/swarm-forge/blob/main/docs/evaluation.md) |
| Browse runnable examples | [Examples](https://github.com/Rvey/swarm-forge/blob/main/docs/examples.md) |

## Examples

The repository includes runnable reference flows under [`examples/`](https://github.com/Rvey/swarm-forge/tree/main/examples), including:

- [build_support_swarm.py](https://github.com/Rvey/swarm-forge/blob/main/examples/build_support_swarm.py)
- [run_support_swarm.py](https://github.com/Rvey/swarm-forge/blob/main/examples/run_support_swarm.py)
- [evaluate_support_swarm.py](https://github.com/Rvey/swarm-forge/blob/main/examples/evaluate_support_swarm.py)
- [fastapi_authoring_server.py](https://github.com/Rvey/swarm-forge/blob/main/examples/fastapi_authoring_server.py)
- [fastapi_server.py](https://github.com/Rvey/swarm-forge/blob/main/examples/fastapi_server.py)
- [fastapi_swarm.py](https://github.com/Rvey/swarm-forge/blob/main/examples/fastapi_swarm.py)

## Project status

SwarmForge `3.0.0` is available on PyPI. The package is still classified as **Alpha**, so expect the API to keep improving as the runtime and transport layers evolve.

## Contributing

See [CONTRIBUTING.md](https://github.com/Rvey/swarm-forge/blob/main/CONTRIBUTING.md) for local development, docs work, demo UI, and release instructions.

## License

Released under the [MIT License](https://github.com/Rvey/swarm-forge/blob/main/LICENSE).
