Authoring

This guide explains how SwarmForge turns generated or hand-written graph payloads into validated SwarmDefinition objects. It does not explain runtime orchestration or provider setup.

This guide is for developers building graph editors, prompt pipelines, or code generators that emit swarm JSON. It assumes that you already understand the runtime concepts at a high level.

After reading this guide, you should be able to:

• understand the generated payload contract
• validate node, edge, and variable data
• compile JSON payloads into runnable swarm definitions
• locate the bundled editor skills

The authoring package turns generated, UI-authored, or hand-written graph payloads into validated SwarmDefinition objects for the SwarmForge SDK.

Package Responsibilities

• ship skills.sh-compatible editor skill folders for copy/paste installation
• validate generated JSON payloads before runtime execution
• infer variable definitions from edge requirements when variables are omitted
• compile normalized payloads into runtime graph objects
• support code-driven and UI-driven graph exports as the integration format

Skills

SwarmForge ships skills.sh-compatible editor skills under skills/ for users who want to copy a skill folder into their editor agent.

Editor Skills

The skills/ folder uses the standard skill layout from the skills.sh ecosystem:

• one folder per skill
• one SKILL.md file with name and description frontmatter
• optional bundled references/ files for deeper SwarmForge context

Available editor skills:

• skills/generate_agent with SKILL.md and references/
• skills/generate_agent_api with SKILL.md and references/
• skills/generate_swarm with SKILL.md and references/
• skills/generate_swarm_api with SKILL.md and references/

To use one in GitHub Copilot for VS Code, copy the chosen folder into .github/skills/<skill-name>/ in the target workspace.

Generated Payload Contract

Nodes must include:

• node_key
• name
• is_entry_node

Optional node metadata:

• intent
• capabilities

Edges must include:

• source_node_key
• target_node_key
• handoff_description
• required_variables

Optional top-level variables can be supplied explicitly. If omitted, SwarmForge derives them from edge requirements.

This payload shape works well as an integration contract for graph editors such as React Flow or any internal builder that exports JSON.

Build a swarm from generated JSON

from swarmforge.authoring import build_swarm_definition

generated = {
    "nodes": [
        {
            "node_key": "triage",
            "name": "Triage",
            "persona": "",
            "is_entry_node": True,
        },
        {
            "node_key": "billing",
            "name": "Billing",
            "persona": "Direct and calm",
            "is_entry_node": False,
        },
    ],
    "edges": [
        {
            "source_node_key": "triage",
            "target_node_key": "billing",
            "handoff_description": "Transfer only after confirming the request is billing-related.",
            "required_variables": ["account_id"],
        }
    ],
}

swarm = build_swarm_definition(generated, swarm_id="support", name="Support Swarm")

Validation Rules

• exactly one node must be the entry node
• node_key values must be unique
• node display names must be unique case-insensitively
• edge endpoints must reference existing nodes
• self-targeting edges are rejected
• variable reducer rules must be valid

Validation failures raise ValueError before the graph reaches the runtime layer.

Reference example

The example below shows the core authoring path: generated JSON, graph compilation, and evaluation-ready inspection output.

from pprint import pprint

from swarmforge.authoring import (
    build_swarm_definition,
)
from swarmforge.evaluation import (
    build_graph_snapshot,
    build_swarm_scenario_generation_context,
)


generated = {
    "nodes": [
        {
            "node_key": "triage",
            "name": "Triage",
            "persona": "",
            "is_entry_node": True,
        },
        {
            "node_key": "billing",
            "name": "Billing",
            "persona": "Calm and direct",
            "is_entry_node": False,
        },
        {
            "node_key": "technical",
            "name": "Technical",
            "persona": "Structured and concise",
            "is_entry_node": False,
        },
    ],
    "edges": [
        {
            "source_node_key": "triage",
            "target_node_key": "billing",
            "handoff_description": "Transfer after confirming the request is about charges, invoices, or payments.",
            "required_variables": ["account_id"],
        },
        {
            "source_node_key": "triage",
            "target_node_key": "technical",
            "handoff_description": "Transfer after confirming the request is about app behavior, errors, or device issues.",
            "required_variables": ["affected_device_model"],
        },
    ],
}

swarm = build_swarm_definition(generated, swarm_id="support", name="Support Swarm")
graph_snapshot = build_graph_snapshot(swarm)

print("Runtime snapshot:")
pprint(graph_snapshot)
print()
print("Scenario generation context:")
print(build_swarm_scenario_generation_context(graph_snapshot))

Resulting Artifacts

• generated stands in for the JSON your application, a React Flow canvas, or an LLM-backed generator would produce.
• build_swarm_definition(...) validates the payload, normalizes it, and returns a runnable SwarmDefinition.
• build_graph_snapshot(...) converts that runtime object into a plain inspection artifact that is easier to print, diff, score, or feed into evaluation helpers.
• build_swarm_scenario_generation_context(...) turns the graph snapshot into a compact text summary for scenario generation and evaluation prompts.

The outputs are useful across different parts of the SDK:

• The runtime snapshot shows the normalized IDs, variables, and default behavior config that the runtime will actually use.
• The scenario context gives you a human-readable summary of reachable routes and required variables, which is useful before you run conversations.