swarmforge 0.3.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]"

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.

OpenRouter setup:

export OPENROUTER_API_KEY=sk-or-...
export OPENROUTER_SITE_URL=https://your-app.example
export OPENROUTER_APP_NAME="Your App Name"

Gemini setup:

export GEMINI_API_KEY=...

Minimal client setup:

from swarmforge.evaluation.provider import ModelConfig, OpenAIClientWrapper

client = OpenAIClientWrapper(
    ModelConfig(
        provider="openrouter",
        model="openrouter/auto",
    )
)

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.

Contributing

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