mas-compiler

# MAS Compiler Implements the MAS→SAS compilation from arXiv 2601.04748 ("When Single-Agent with Skills Replace Multi-Agent Systems and When They Fail"). Input: a MAS codebase, paper, or description. Output: a compiled skill directory with `SKILL.md` + `tools/`. See `references/compilation_theory.md` for the formal definitions (ℳ, 𝒮, Φ, C1–C3). See `references/output_format.md` for the exact output template. --- ## Step 1 — Check Compilability (C1, C2, C3) Before compiling, verify all three conditions hold. Report violations clearly. **C1 — Serializable communication**: The communication graph 𝒢 admits a topological ordering. Fails if there are cycles (debate loops, circular routing, adversarial negotiation). **C2 — Shared history**: Every agent's output depends only on the shared conversation history h; no agent maintains private state or hidden objectives. **C3 — Homogeneous backbone**: All agents run on the same underlying model. If a condition fails, state which condition and why. Ask whether to proceed with an approximation (e.g., serialize a near-cyclic step) before continuing. --- ## Step 2 — Extract the Communication Graph Read the MAS source and record: For each agent aᵢ: - `name`: identifier used in the codebase - `role` ρᵢ: what this agent does (from its system prompt or role description) - `policy` ϕᵢ: the behavioral instructions governing how it operates - `tools`: any external libraries, APIs, or computation the agent calls For the communication graph 𝒢: - List all directed edges (aᵢ → aⱼ) — data flows from aᵢ to aⱼ - List N_out(aᵢ) = {aⱼ | (aᵢ, aⱼ) ∈ E} for each agent - Produce a topological ordering of agents For each edge (aᵢ → aⱼ), record the output contract: what format does aᵢ produce, and what does aⱼ expect to receive? --- ## Step 3 — Phase 1: Capability Decomposition Apply `Kᵢ = f_decomp(ρᵢ)` to each agent. For each agent aᵢ, extract its atomic capabilities κ — discrete, independently executable functions derived from its role description ρᵢ. One agent may yield 1–3 capabilities. Name each κ as a verb phrase (e.g., "decompose question", "explore schema", "generate SQL"). Produce a table: `agent → [κ₁, κ₂, ...]` for all agents. --- ## Step 4 — Phase 2: Backend Assignment Apply `ξ = f_backend(κ)` to each capability. | Condition | Backend | Action | |-----------|---------|--------| | κ requires external computation, data access, or a deterministic algorithm | External: ξ = t ∈ 𝒯 | Write a tool in `tools/` | | κ is purely cognitive (reasoning, generation, analysis) | Internal: ξ = ∅ | Embed as policy text | For each externalized capability, write a tool file in `tools/`: - One function per capability; inputs are JSON-serializable; return a flat dict - No LLM calls inside tools - All imports at top of file - Wrap body in `try/except Exception as e: return {"error": str(e)}` After each tool file, run: ```bash python -c "import sys; sys.path.insert(0, '<SKILL_DIR>'); from tools.<module> import <fn>; print('OK')" ``` --- ## Step 5 — Phase 3: Topology Internalization Apply `πκ^final = f_inject(πκ^base, N_out(aᵢ))` to each capability. For each capability κ from agent aᵢ with downstream set N_out(aᵢ): ``` πκ^final = πκ^base ⊕ ⋃_{aⱼ ∈ N_out(aᵢ)} Handover(aᵢ → aⱼ) ``` `⊕` is string concatenation. The **Handover** block appended to each section's policy specifies: - **Required output fields**: what the downstream phase needs - **Output format**: structure (e.g., list of tuples, dict with keys X and Y) - **Completion signal**: how the agent knows this phase is done This replaces explicit inter-agent message passing with implicit output format constraints embedded in each section's policy. --- ## Step 6 — Write the Compiled SKILL.md Follow the template in `references/output_format.md`. Each capability κ becomes one `[PHASE_NAME]` section. Sections are ordered by the topological sort of 𝒢. The compiled agent is instructed to execute phases in this order. Each section contains: - A `[PHASE_NAME]` header - **Role**: 1–2 sentences from ρᵢ - **Execute**: the finalized policy πκ^final (base policy + handover instruction) - **Tools** (if ξ ≠ ∅): tool name, file location, one-line description - **Handover → NEXT_PHASE**: the required output fields (omit on the final phase) --- ## Step 7 — Validate Check the compiled output: 1. One `[PHASE]` section per capability (matches the capability table from Step 3) 2. One tool file per externalized capability (from Step 4) 3. Every non-final section has a Handover block (from Step 5) 4. Sections are in topological order (matches 𝒢 from Step 2) Report what was compiled. Note any approximations made (e.g., a near-cyclic step that was serialized, a partially private agent that was treated as shared-history).