swarmforge 0.4.0

Headless framework for multi-agent chat runtime and evaluation.

SwarmForge

SwarmForge is a Python package for authoring, running, and evaluating multi-agent swarms. You define the swarm graph, provide the model-turn callback, and keep sessions, handoffs, tools, checkpoints, and evaluation artifacts under your control.

• Explicit graph-based multi-agent runtime
• Python tool execution with inferred JSON schema
• OpenRouter, Gemini, and other OpenAI-compatible provider support
• FastAPI transport for stateless and session-backed HTTP flows
• Evaluation helpers for graph snapshots, scenario seeds, and artifact scoring

Install

Python 3.11+ is required.

pip install swarmforge

If you want the FastAPI transport too:

pip install "swarmforge[api]"

Provider-backed examples, the demo UI, and local API runs load a nearby .env automatically. Copy .env.example to .env before using them:

cp .env.example .env

Quick Start

The shortest path is a single-node swarm with a stubbed model callback:

import asyncio
import json

from swarmforge.swarm import (
    AgentTurnResult,
    InMemorySessionStore,
    SwarmDefinition,
    SwarmNode,
    SwarmSession,
    process_swarm_stream,
)


class ExampleTurnRunner:
    async def run_turn(self, *, agent_node, contents, config):
        del agent_node, contents, config
        return AgentTurnResult(response_text="Here is a direct answer from SwarmForge.")


swarm = SwarmDefinition(
    id="assistant",
    name="Assistant Swarm",
    nodes=[
        SwarmNode(
            id="assistant",
            node_key="assistant",
            name="Assistant",
            intent="Handle general requests",
            system_prompt="You are a concise assistant.",
            capabilities=["Answer questions"],
            is_entry_node=True,
        )
    ],
)


async def main():
    session = SwarmSession(id="session-1", swarm=swarm)
    store = InMemorySessionStore()
    async for event in process_swarm_stream(
        session,
        "Give me a concise summary.",
        store=store,
        turn_runner=ExampleTurnRunner(),
    ):
        print(json.dumps(event, indent=2))


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

When you are ready to add routing, continue with the multi-agent flow in the docs.

Package Surfaces

• swarmforge.swarm Runtime models, session state, orchestration, tool execution, and stores.
• swarmforge.authoring Prompt templates, payload validation, and graph compilation helpers.
• swarmforge.evaluation Graph snapshots, scenario generation, feasibility checks, and artifact scoring.
• swarmforge.api FastAPI application factory built on the same runtime primitives.

Providers

SwarmForge ships with an OpenAI-compatible provider wrapper. OpenRouter is the default path, and Gemini is built in as an alternative mode.

Start from the repository .env.example and fill in the provider you want to use.

OpenRouter .env:

MODEL_PROVIDER=openrouter
NORMAL_MODEL=openrouter/auto
OPENROUTER_API_KEY=sk-or-...
OPENROUTER_SITE_URL=https://your-app.example
OPENROUTER_APP_NAME="Your App Name"

Gemini .env:

MODEL_PROVIDER=gemini
NORMAL_MODEL=gemini-3-flash-preview
GEMINI_API_KEY=...

Minimal client setup:

from swarmforge.evaluation.provider import ModelConfig, OpenAIClientWrapper

client = OpenAIClientWrapper(ModelConfig())

ModelConfig() reads MODEL_PROVIDER, NORMAL_MODEL, and the matching API key from .env or the shell environment.

FastAPI Transport

You can expose the runtime over HTTP without changing your swarm definitions:

pip install "swarmforge[api]"
uvicorn swarmforge.api.fastapi:create_fastapi_app --factory --reload

That app exposes both stateless run endpoints and session-backed endpoints with SSE streaming.

Documentation

• Getting Started
• Create Your First Agent
• Create Your First Multi-Agent Swarm
• Authoring
• Orchestration
• Providers
• API
• Evaluation
• Examples

Source Examples

The repository includes end-to-end example scripts under examples/. Those scripts are useful when you want runnable reference flows for authoring, orchestration, evaluation, provider integration, or FastAPI transport. Provider-backed examples and the local FastAPI example read from .env.example-style settings.

The demo UI under demo-ui/ reads the same root .env for its default API base, provider, and model. Its Vite scripts create .env from .env.example automatically when the file is missing.

Contributing

Core modification, docs development, demo UI work, and PyPI release steps are documented in CONTRIBUTING.md.