swarmforge 0.1.0__py3-none-any.whl

swarmforge/__init__.py

@@ -0,0 +1,5 @@
+"""Headless multi-agent chat and evaluation framework."""
+
+__version__ = "0.1.0"
+
+__all__ = ["api", "authoring", "evaluation", "swarm"]

swarmforge/api/__init__.py

@@ -0,0 +1,5 @@
+"""HTTP API integrations."""
+
+from .fastapi import create_fastapi_app
+
+__all__ = ["create_fastapi_app"]

swarmforge/api/fastapi.py

@@ -0,0 +1,485 @@
+"""FastAPI integration for exposing the swarm runtime over HTTP."""
+
+from __future__ import annotations
+
+import json
+import uuid
+from typing import Any, AsyncGenerator, Callable, Dict, List
+
+from fastapi import Body, FastAPI, HTTPException, Response
+from fastapi.middleware.cors import CORSMiddleware
+from fastapi.responses import StreamingResponse
+from pydantic import BaseModel, Field
+
+from ..authoring import build_swarm_definition
+from ..evaluation.provider import ModelConfig, OpenAIClientWrapper
+from ..evaluation.swarm import serialize_checkpoints
+from ..swarm import InMemorySessionStore, SessionStore, SwarmSession, process_swarm_stream
+from ..swarm.orchestrator import AgentTurnConfig, StreamAgentIteration
+from ..swarm.tools import FrameworkToolRegistry, ToolRegistry
+
+RUN_SWARM_OPENAPI_EXAMPLES = {
+    "openrouter": {
+        "summary": "Run a swarm turn with OpenRouter",
+        "value": {
+            "swarm": {
+                "id": "support",
+                "name": "Support Swarm",
+                "nodes": [
+                    {
+                        "node_key": "assistant",
+                        "name": "Assistant",
+                        "system_prompt": "You are a helpful assistant.",
+                        "intent": "Handle the full request",
+                        "capabilities": ["Answer questions"],
+                        "is_entry_node": True,
+                    }
+                ],
+                "edges": [],
+                "variables": [],
+            },
+            "user_input": "Give me a concise answer.",
+            "provider": {
+                "provider": "openrouter",
+                "model": "openrouter/auto",
+                "site_url": "https://your-app.example",
+                "app_name": "Your App Name",
+            },
+        },
+    },
+    "gemini": {
+        "summary": "Run a swarm turn with Gemini OpenAI-compat",
+        "value": {
+            "swarm": {
+                "id": "support",
+                "name": "Support Swarm",
+                "nodes": [
+                    {
+                        "node_key": "assistant",
+                        "name": "Assistant",
+                        "system_prompt": "You are a helpful assistant.",
+                        "intent": "Handle the full request",
+                        "capabilities": ["Answer questions"],
+                        "is_entry_node": True,
+                    }
+                ],
+                "edges": [],
+                "variables": [],
+            },
+            "user_input": "Explain the answer briefly.",
+            "provider": {
+                "provider": "gemini",
+                "model": "gemini-3-flash-preview",
+                "default_chat_params": {"reasoning_effort": "low"},
+            },
+        },
+    },
+}
+
+SEND_MESSAGE_OPENAPI_EXAMPLES = {
+    "openrouter": {
+        "summary": "Send a session message with OpenRouter",
+        "value": {
+            "user_input": "Help me with this request.",
+            "provider": {
+                "provider": "openrouter",
+                "model": "openrouter/auto",
+                "site_url": "https://your-app.example",
+                "app_name": "Your App Name",
+            },
+        },
+    },
+    "gemini": {
+        "summary": "Send a session message with Gemini OpenAI-compat",
+        "value": {
+            "user_input": "Help me with this request.",
+            "provider": {
+                "provider": "gemini",
+                "model": "gemini-3-flash-preview",
+                "default_chat_params": {"reasoning_effort": "low"},
+            },
+        },
+    },
+}
+
+CREATE_SESSION_OPENAPI_EXAMPLE = {
+    "summary": "Create a swarm session",
+    "value": {
+        "session_id": "session-1",
+        "swarm": {
+            "id": "single-agent",
+            "name": "Single Agent",
+            "nodes": [
+                {
+                    "node_key": "assistant",
+                    "name": "Assistant",
+                    "system_prompt": "You are a helpful assistant.",
+                    "intent": "Handle the full request",
+                    "capabilities": ["Answer questions"],
+                    "is_entry_node": True,
+                }
+            ],
+            "edges": [],
+            "variables": [],
+        },
+        "global_variables": {},
+    },
+}
+
+
+class ProviderConfigPayload(BaseModel):
+    provider: str | None = None
+    base_url: str | None = None
+    api_key: str | None = None
+    model: str | None = None
+    temperature: float | None = None
+    max_tokens: int | None = None
+    site_url: str | None = None
+    app_name: str | None = None
+    default_headers: Dict[str, str] | None = None
+    default_chat_params: Dict[str, Any] | None = None
+
+    def to_model_config(self, base: ModelConfig | None = None) -> ModelConfig:
+        base = base or ModelConfig()
+        provider = self.provider or base.provider
+        same_provider = provider == base.provider
+        return ModelConfig(
+            provider=provider,
+            base_url=self.base_url if self.base_url is not None else (base.base_url if same_provider else None),
+            api_key=self.api_key if self.api_key is not None else (base.api_key if same_provider else None),
+            model=self.model or base.model,
+            temperature=self.temperature if self.temperature is not None else base.temperature,
+            max_tokens=self.max_tokens if self.max_tokens is not None else base.max_tokens,
+            site_url=self.site_url,
+            app_name=self.app_name,
+            default_headers=self.default_headers if self.default_headers is not None else (base.default_headers if same_provider else None),
+            default_chat_params=self.default_chat_params if self.default_chat_params is not None else (base.default_chat_params if same_provider else None),
+        )
+
+
+class SwarmVariablePayload(BaseModel):
+    key_name: str
+    description: str = ""
+    reducer_rule: str = "overwrite"
+
+
+class SwarmEdgePayload(BaseModel):
+    source_node_key: str
+    target_node_key: str
+    handoff_description: str
+    required_variables: List[str] = Field(default_factory=list)
+
+
+class SwarmNodePayload(BaseModel):
+    node_key: str
+    name: str
+    system_prompt: str = ""
+    intent: str = ""
+    capabilities: List[str] = Field(default_factory=list)
+    persona: str = ""
+    model_choice: str = ""
+    enabled_tools: List[Dict[str, Any]] = Field(default_factory=list)
+    behavior_config: Dict[str, Any] = Field(default_factory=dict)
+    is_entry_node: bool = False
+
+
+class SwarmDefinitionPayload(BaseModel):
+    id: str = "swarm"
+    name: str = "Swarm"
+    graph_version: int = 1
+    nodes: List[SwarmNodePayload]
+    edges: List[SwarmEdgePayload] = Field(default_factory=list)
+    variables: List[SwarmVariablePayload] = Field(default_factory=list)
+
+    def to_runtime(self):
+        return build_swarm_definition(
+            {
+                "nodes": [node.model_dump(mode="python") for node in self.nodes],
+                "edges": [edge.model_dump(mode="python") for edge in self.edges],
+                "variables": [variable.model_dump(mode="python") for variable in self.variables],
+            },
+            swarm_id=self.id,
+            name=self.name,
+            graph_version=self.graph_version,
+        )
+
+
+class CreateSessionRequest(BaseModel):
+    session_id: str | None = None
+    swarm: SwarmDefinitionPayload
+    global_variables: Dict[str, Any] = Field(default_factory=dict)
+
+
+class SendMessageRequest(BaseModel):
+    user_input: str
+    provider: ProviderConfigPayload | None = None
+
+
+class RunSwarmRequest(BaseModel):
+    session_id: str | None = None
+    swarm: SwarmDefinitionPayload
+    user_input: str
+    global_variables: Dict[str, Any] = Field(default_factory=dict)
+    provider: ProviderConfigPayload | None = None
+
+
+def _session_payload(session: SwarmSession) -> Dict[str, Any]:
+    return {
+        "id": session.id,
+        "swarm_id": session.swarm.id,
+        "swarm_name": session.swarm.name,
+        "graph_version": session.swarm.graph_version,
+        "current_node_id": session.current_node_id,
+        "current_node_key": session.current_node.node_key if session.current_node else None,
+        "current_agent": session.current_node.name if session.current_node else None,
+        "snapshot": session.snapshot(),
+    }
+
+
+def _sse_event(event: str, payload: Dict[str, Any]) -> str:
+    return f"event: {event}\ndata: {json.dumps(payload, ensure_ascii=False)}\n\n"
+
+
+def build_openai_compatible_stream_agent_iteration(client: OpenAIClientWrapper) -> StreamAgentIteration:
+    async def _stream_agent_iteration(
+        *,
+        agent_node,
+        contents,
+        config: AgentTurnConfig,
+    ) -> AsyncGenerator[tuple[str, List[Dict[str, Any]], Any], None]:
+        del agent_node
+        messages: List[Dict[str, Any]] = []
+        if config.system_instruction:
+            messages.append({"role": "system", "content": config.system_instruction})
+
+        for item in contents:
+            role = str(item.get("role") or "user").strip()
+            if role == "model":
+                role = "assistant"
+            message: Dict[str, Any] = {"role": role, "content": item.get("content", "")}
+            if role == "tool":
+                if item.get("tool_call_id"):
+                    message["tool_call_id"] = item.get("tool_call_id")
+                if item.get("name"):
+                    message["name"] = item.get("name")
+            messages.append(message)
+
+        response = client.chat_completion(messages=messages, tools=config.tools)
+        assistant_message = response.choices[0].message
+        tool_calls: List[Dict[str, Any]] = []
+        if assistant_message.tool_calls:
+            for tool_call in assistant_message.tool_calls:
+                args = tool_call.function.arguments
+                if not isinstance(args, dict):
+                    args = json.loads(args or "{}")
+                tool_calls.append(
+                    {
+                        "id": tool_call.id,
+                        "name": tool_call.function.name,
+                        "args": args,
+                    }
+                )
+        yield assistant_message.content or "", tool_calls, response
+
+    return _stream_agent_iteration
+
+
+class _SwarmApiRuntime:
+    def __init__(self, store: SessionStore) -> None:
+        self.store = store
+
+    async def create_session(self, *, swarm, session_id: str | None, global_variables: Dict[str, Any]) -> SwarmSession:
+        resolved_session_id = session_id or uuid.uuid4().hex
+        existing = await self.store.get_session(resolved_session_id)
+        if existing is not None:
+            raise ValueError(f"Session '{resolved_session_id}' already exists")
+        session = SwarmSession(
+            id=resolved_session_id,
+            swarm=swarm,
+            global_variables=dict(global_variables or {}),
+        )
+        await self.store.save_session(session)
+        return session
+
+    async def get_session(self, session_id: str) -> SwarmSession:
+        session = await self.store.get_session(session_id)
+        if session is None:
+            raise KeyError(session_id)
+        return session
+
+
+def create_fastapi_app(
+    *,
+    default_model_config: ModelConfig | None = None,
+    session_store: SessionStore | None = None,
+    stream_agent_iteration_factory: Callable[[ModelConfig], StreamAgentIteration] | None = None,
+    tool_registry: ToolRegistry | FrameworkToolRegistry | None = None,
+    tool_state: Any = None,
+    cors_allow_origins: List[str] | None = None,
+) -> FastAPI:
+    resolved_store = session_store or InMemorySessionStore()
+    app = FastAPI(title="SwarmForge API", version="0.1.0")
+    app.add_middleware(
+        CORSMiddleware,
+        allow_origins=cors_allow_origins or ["*"],
+        allow_credentials=False,
+        allow_methods=["*"],
+        allow_headers=["*"],
+    )
+    app.state.runtime = _SwarmApiRuntime(resolved_store)
+    app.state.default_model_config = default_model_config
+    app.state.tool_registry = tool_registry
+    app.state.tool_state = tool_state
+    app.state.stream_agent_iteration_factory = stream_agent_iteration_factory or (
+        lambda config: build_openai_compatible_stream_agent_iteration(OpenAIClientWrapper(config))
+    )
+
+    def _resolve_config(provider: ProviderConfigPayload | None) -> ModelConfig:
+        base_config = app.state.default_model_config
+        return provider.to_model_config(base_config) if provider is not None else (base_config or ModelConfig())
+
+    async def _run_turn(session: SwarmSession, user_input: str, provider: ProviderConfigPayload | None) -> Dict[str, Any]:
+        iteration = app.state.stream_agent_iteration_factory(_resolve_config(provider))
+        events: List[Dict[str, Any]] = []
+        async for event in process_swarm_stream(
+            session,
+            user_input,
+            store=app.state.runtime.store,
+            stream_agent_iteration=iteration,
+            tool_registry=app.state.tool_registry,
+            tool_state=app.state.tool_state,
+        ):
+            events.append(event)
+        checkpoints = await app.state.runtime.store.list_checkpoints(session.id)
+        return {
+            "events": events,
+            "session": _session_payload(session),
+            "checkpoints": serialize_checkpoints(checkpoints),
+        }
+
+    async def _stream_turn(session: SwarmSession, user_input: str, provider: ProviderConfigPayload | None):
+        async def event_generator():
+            try:
+                iteration = app.state.stream_agent_iteration_factory(_resolve_config(provider))
+                async for event in process_swarm_stream(
+                    session,
+                    user_input,
+                    store=app.state.runtime.store,
+                    stream_agent_iteration=iteration,
+                    tool_registry=app.state.tool_registry,
+                    tool_state=app.state.tool_state,
+                ):
+                    yield _sse_event(event["event"], event["data"])
+                checkpoints = await app.state.runtime.store.list_checkpoints(session.id)
+                yield _sse_event("session", _session_payload(session))
+                yield _sse_event("checkpoints", {"items": serialize_checkpoints(checkpoints)})
+            except Exception as exc:
+                yield _sse_event("error", {"message": str(exc)})
+
+        return StreamingResponse(
+            event_generator(),
+            media_type="text/event-stream",
+            headers={
+                "Cache-Control": "no-cache",
+                "Connection": "keep-alive",
+                "X-Accel-Buffering": "no",
+            },
+        )
+
+    @app.get("/")
+    async def root() -> Dict[str, str]:
+        return {
+            "name": "SwarmForge API",
+            "status": "ok",
+            "docs": "/docs",
+            "health": "/health",
+        }
+
+    @app.get("/favicon.ico")
+    async def favicon() -> Response:
+        return Response(status_code=204)
+
+    @app.get("/health")
+    async def health() -> Dict[str, str]:
+        return {"status": "ok"}
+
+    @app.post("/v1/sessions")
+    async def create_session(
+        request: CreateSessionRequest = Body(..., openapi_examples={"default": CREATE_SESSION_OPENAPI_EXAMPLE})
+    ) -> Dict[str, Any]:
+        swarm = request.swarm.to_runtime()
+        try:
+            session = await app.state.runtime.create_session(
+                swarm=swarm,
+                session_id=request.session_id,
+                global_variables=request.global_variables,
+            )
+        except ValueError as exc:
+            raise HTTPException(status_code=409, detail=str(exc)) from exc
+        return {"session": _session_payload(session)}
+
+    @app.get("/v1/sessions/{session_id}")
+    async def get_session(session_id: str) -> Dict[str, Any]:
+        try:
+            session = await app.state.runtime.get_session(session_id)
+        except KeyError as exc:
+            raise HTTPException(status_code=404, detail="Session not found") from exc
+        checkpoints = await app.state.runtime.store.list_checkpoints(session.id)
+        return {
+            "session": _session_payload(session),
+            "checkpoints": serialize_checkpoints(checkpoints),
+        }
+
+    @app.post("/v1/sessions/{session_id}/messages")
+    async def send_message(
+        session_id: str,
+        request: SendMessageRequest = Body(..., openapi_examples=SEND_MESSAGE_OPENAPI_EXAMPLES),
+    ) -> Dict[str, Any]:
+        try:
+            session = await app.state.runtime.get_session(session_id)
+        except KeyError as exc:
+            raise HTTPException(status_code=404, detail="Session not found") from exc
+        return await _run_turn(session, request.user_input, request.provider)
+
+    @app.post("/v1/sessions/{session_id}/messages/stream")
+    async def stream_message(
+        session_id: str,
+        request: SendMessageRequest = Body(..., openapi_examples=SEND_MESSAGE_OPENAPI_EXAMPLES),
+    ):
+        try:
+            session = await app.state.runtime.get_session(session_id)
+        except KeyError as exc:
+            raise HTTPException(status_code=404, detail="Session not found") from exc
+        return await _stream_turn(session, request.user_input, request.provider)
+
+    @app.post("/v1/swarm/run")
+    async def run_swarm(
+        request: RunSwarmRequest = Body(..., openapi_examples=RUN_SWARM_OPENAPI_EXAMPLES)
+    ) -> Dict[str, Any]:
+        swarm = request.swarm.to_runtime()
+        try:
+            session = await app.state.runtime.create_session(
+                swarm=swarm,
+                session_id=request.session_id,
+                global_variables=request.global_variables,
+            )
+        except ValueError as exc:
+            raise HTTPException(status_code=409, detail=str(exc)) from exc
+        return await _run_turn(session, request.user_input, request.provider)
+
+    @app.post("/v1/swarm/run/stream")
+    async def stream_swarm_run(
+        request: RunSwarmRequest = Body(..., openapi_examples=RUN_SWARM_OPENAPI_EXAMPLES)
+    ):
+        swarm = request.swarm.to_runtime()
+        try:
+            session = await app.state.runtime.create_session(
+                swarm=swarm,
+                session_id=request.session_id,
+                global_variables=request.global_variables,
+            )
+        except ValueError as exc:
+            raise HTTPException(status_code=409, detail=str(exc)) from exc
+        return await _stream_turn(session, request.user_input, request.provider)
+
+    return app

swarmforge/authoring/__init__.py

@@ -0,0 +1,25 @@
+"""Authoring helpers for prompt generation and graph validation."""
+
+from .prompts import META_PROMPT_EDGE, META_PROMPT_NODE, META_PROMPT_SWARM
+from .validators import (
+    VALID_REDUCER_RULES,
+    apply_swarm_graph_payload,
+    build_generated_variables_from_swarm_payload,
+    build_swarm_definition,
+    validate_generated_edge_payload,
+    validate_generated_swarm_payload,
+    validate_swarm_definition,
+)
+
+__all__ = [
+    "META_PROMPT_EDGE",
+    "META_PROMPT_NODE",
+    "META_PROMPT_SWARM",
+    "VALID_REDUCER_RULES",
+    "apply_swarm_graph_payload",
+    "build_generated_variables_from_swarm_payload",
+    "build_swarm_definition",
+    "validate_generated_edge_payload",
+    "validate_generated_swarm_payload",
+    "validate_swarm_definition",
+]

swarmforge/authoring/prompts.py

@@ -0,0 +1,165 @@
+"""Prompt templates for swarm authoring workflows."""
+
+META_PROMPT_NODE = """
+You are the SwarmForge Node Authoring Skill.
+
+Your job is to write the production-ready `system_prompt` text for one `swarmforge.swarm.SwarmNode`.
+
+Framework context:
+- This prompt becomes the value of the node's `system_prompt` field.
+- The runtime injects routing rules, handoff guidance, visible global variables, tool schemas, and behavior config separately.
+- Do not hardcode graph structure, downstream agents, transfer logic, or orchestration internals into the prompt.
+- If tools exist, the prompt may describe when to use them, but it must not invent tools that were not provided.
+
+Node inputs:
+- Agent Name: {node_name}
+- User Need / Intent: {user_intent}
+- Capabilities: {capabilities_summary}
+- Persona Guidance: {persona_summary}
+
+Write a system prompt that:
+- defines the node's job, scope boundaries, and success criteria
+- explains how the listed capabilities shape the node's work
+- tells the node what facts it should gather before acting when information is incomplete
+- keeps the node task-focused, concrete, and usable in a real runtime
+- uses persona guidance for tone and collaboration style only
+- avoids delegation policy, handoff conditions, routing rules, or references to `transfer_to_agent`
+- does not mention JSON, schemas, graph nodes, or framework implementation details
+
+Output rules:
+- Return only the prompt text
+- Do not wrap it in JSON, markdown, or code fences
+""".strip()
+
+
+META_PROMPT_EDGE = """
+You are the SwarmForge Edge Authoring Skill.
+
+Your job is to generate one SwarmForge edge payload describing when a source node should hand off to a target node.
+
+Framework context:
+- The result will be used as a `SwarmEdge` authoring payload.
+- `handoff_description` becomes runtime guidance for when a transfer is valid.
+- `required_variables` must contain only the minimum shared facts the source node should gather before transfer.
+
+Route inputs:
+- Source Agent: {source_name}
+- Source Intent: {source_intent}
+- Target Agent: {target_name}
+- Target Intent: {target_intent}
+
+Generate:
+1. `handoff_description`
+	One sentence that tells the source node when the user's request should be routed to the target node.
+2. `required_variables`
+	A list of 0 to 3 variable keys the source node should collect before the transfer.
+
+Rules for `handoff_description`:
+- It must require the source node to identify or confirm the user's intent before transfer.
+- It must transfer only when the request clearly matches the target node's scope.
+- It must not encourage handoff based on a weak keyword match.
+- It must describe the business condition for transfer, not implementation details.
+
+Rules for `required_variables`:
+- Use short snake_case keys.
+- Include only facts that the target node genuinely needs.
+- Return an empty array if no shared variable is required.
+- Do not invent internal-only state or transport fields.
+
+Return only valid JSON matching this schema:
+{{"handoff_description": "...", "required_variables": ["..."]}}
+""".strip()
+
+
+META_PROMPT_SWARM = """
+You are the SwarmForge Swarm Authoring Skill.
+
+Your job is to convert a user request into a runnable SwarmForge graph payload that can be passed directly to `build_swarm_definition(...)`.
+
+User request:
+{global_intent}
+
+Framework schema:
+- Return one JSON object with `nodes`, `edges`, and optionally `variables`.
+- The payload must match the SwarmForge authoring model used by `swarmforge.authoring.build_swarm_definition`.
+- Favor the smallest graph that can solve the request.
+- Use a single node when one agent can handle the task. Introduce a triage/router node only when the request clearly requires multiple specialized agents or intent-based routing.
+
+Each node may contain:
+- `node_key`: short stable snake_case key
+- `name`: human-readable unique display name
+- `intent`: clear business responsibility for the node
+- `capabilities`: array of 2 to 5 concrete capabilities
+- `persona`: optional tone/style guidance, or an empty string
+- `system_prompt`: production-ready prompt text for this node
+- `model_choice`: optional model override, or an empty string
+- `enabled_tools`: array of tool definitions, usually `[]` unless the request clearly requires known tools
+- `behavior_config`: object, usually `{}` unless the request clearly needs non-default behavior
+- `is_entry_node`: boolean
+
+Each edge may contain:
+- `source_node_key`
+- `target_node_key`
+- `handoff_description`
+- `required_variables`
+
+Each top-level variable may contain:
+- `key_name`
+- `description`
+- `reducer_rule` where the value is `overwrite`, `append`, or `keep_first`
+
+Generation rules:
+- Produce between 1 and 6 nodes.
+- Mark exactly one node as `is_entry_node=true`.
+- Every node must have a concrete and non-overlapping responsibility.
+- Every `intent` must be specific enough to drive routing and evaluation.
+- Every `system_prompt` must be ready to run and must stay inside the node's own scope.
+- Do not put graph-wide routing rules inside node `system_prompt` values.
+- Every edge must reference existing node keys and may not self-target.
+- Only create edges for realistic handoffs.
+- `required_variables` should be the minimum facts that the target node needs from the source node.
+- Only create top-level `variables` for facts that are shared across nodes or required by handoffs.
+- Use `overwrite` unless there is a clear reason to preserve the first value or accumulate a list.
+- If tools are not explicitly available from the request context, use `enabled_tools: []`.
+- If no custom behavior is necessary, use `behavior_config: {}`.
+- If no model override is necessary, use `model_choice: ""`.
+- Do not invent framework fields outside the schema above.
+
+Return only valid JSON with this shape:
+{
+	"nodes": [
+		{
+			"node_key": "...",
+			"name": "...",
+			"intent": "...",
+			"capabilities": ["..."],
+			"persona": "...",
+			"system_prompt": "...",
+			"model_choice": "",
+			"enabled_tools": [],
+			"behavior_config": {},
+			"is_entry_node": true
+		}
+	],
+	"edges": [
+		{
+			"source_node_key": "...",
+			"target_node_key": "...",
+			"handoff_description": "...",
+			"required_variables": ["..."]
+		}
+	],
+	"variables": [
+		{
+			"key_name": "...",
+			"description": "...",
+			"reducer_rule": "overwrite"
+		}
+	]
+}
+
+Output rules:
+- Return raw JSON only
+- Do not use markdown fences
+- Do not include explanations before or after the JSON
+""".strip()