🐝 Swarm Builder

OMP Swarm Builder

The Perfected Agentic Swarm Expert Cluster Designer Synthesis

Architecture

The OMP Swarm Builder is a visual IDE and compiler that translates human-authored agent topologies into deterministic, machine-executable multi-agent orchestrations.

graph LR
    %% Subgraphs for Waves
    subgraph wave1 ["Wave 1: Discovery"]
        A["Agent: Code Scout"]
        B["Agent: Log Parser"]
    end
    
    subgraph wave2 ["Wave 2: Synthesis"]
        C["Agent: Architect"]
    end
    
    subgraph wave3 ["Wave 3: Action"]
        D["Agent: Fixer"]
    end

    %% Relationships
    A -->|"reports_to (Artifacts)"| C
    B -->|"reports_to (Artifacts)"| C
    C -.->|"waits_for (Clearance)"| D

    %% Styling
    classDef wave fill:#1e1e2e,stroke:#6366f1,stroke-width:2px,color:#fff;
    classDef waveGroup fill:#0f172a,stroke:#3b82f6,stroke-width:1px,stroke-dasharray: 5 5,color:#cbd5e1;
    
    class A,B,C,D wave;
    class wave1,wave2,wave3 waveGroup;

1. Graph Theory & Wave Compilation (The Engine)

The core compiler transforms scattered node configurations into Execution Waves—strict concurrency barriers where no agent in Wave $N+1$ begins until all agents in Wave $N$ successfully yield.

• Topological Sorting: The builder constructs a Directed Acyclic Graph (DAG) from waits_for (inbound) and reports_to (outbound) edges. It processes this via Kahn’s Algorithm in $O(V+E)$ time.
• Deterministic Execution: To guarantee identical execution runs, nodes within the exact same wave are sorted alphabetically by ID before being pushed to the runtime.
• Pre-execution Cycle Detection: If the graph refuses to resolve (e.g., a mutual deadlock), the compiler statically isolates the orphaned cycleIds. Rather than throwing a fatal AST error, it gracefully tags the specific nodes in the UI for targeted correction.

2. Atomic State Machine (The Interface)

The UI is not just a canvas; it is a strict, two-way bound state machine built on reactive runes, enforcing structural parity between the visual layer and the underlying YAML AST.

• Idempotent Serialization ($Canvas\to YAML$): Node mutations instantly rebuild the YAML payload. Stripped of nulls and strictly formatted, the output is pure. Identifiers are forcefully sanitized via ^[A-Za-z0-9_-]+$ to immunize the compiler against YAML key injection or shattered graph edges.
• Fail-Safe Hydration ($YAML\to Canvas$): Pasting code triggers an Atomic Apply. The parser builds an abstract syntax tree and evaluates all schema constraints (scalar arrays, edge validations, mode checks).
  • If valid: The canvas state mutates exactly once, resolving new nodes to deterministic grid coordinates (x = 100 + (i % 3) * 260).
  • If invalid: The transaction is dropped entirely, preserving the existing working state while surfacing precise, schema-compatible error traces.

3. Execution Topologies (The Fallbacks)

When a user bypasses explicit DAG edges, the builder compiles based on the global mode constraint:

• pipeline (Linear): Compiles an implicit sequence based on declarative order (W1 → W2 → W3). Uniquely supports target_count > 1 to create iterative, multi-pass refinement loops (e.g., Write $\to$ Test $\to$ Fix $\circlearrowright$).
• parallel (Scatter-Gather): Flattens all independent nodes into a single, massive $O(1)$ wave. Ideal for wide-net data gathering (e.g., 10 agents concurrently auditing 10 different files).
• sequential (Isolated): Enforces a strict one-by-one execution queue, isolating execution boundaries without the strict sequential data-passing contract of a pipeline.

4. The Runtime Contract (The Handoff)

The compiled .yaml is a contract handed to the OMP Orchestrator.

• The Blackboard Pattern: Agents execute in completely sandboxed contexts. They share zero memory. They communicate purely by reading and writing files (artifacts) to the defined workspace.
• Immutable Personas: An agent’s behavior is rigidly scoped by its role (system prompt), task (assignment), and extra_context (targeted file injections), preventing logic drift during massive parallel executions.

Example Interactive Definition

name: Code Audit Swarm
mode: parallel
nodes:
  - id: CodeScout
    agent: explore
    assignment: Find all markdown files
  - id: Architect
    agent: plan
    assignment: Review architecture
    waits_for:
      - CodeScout