operon-ai 0.36.1

Biomimetic wiring diagrams for robust agentic systems.

Operon 🧬

Biologically inspired architectures for more reliable AI agent systems

From agent heuristics toward structural guarantees.

Operon is a research-grade library and reference implementation for biologically inspired agent control patterns. The API is still evolving.

The Problem: Fragile Agents

Most agent systems fail structurally, not just locally.

A worker can hallucinate and nobody checks it. A sequential chain accumulates handoff cost. A tool-rich workflow becomes harder to route safely than a single-agent baseline. In practice, adding more agents often adds more failure surface unless the wiring is doing real control work.

Operon is a library for making that structure explicit. It gives you pattern-first building blocks like reviewer gates, specialist swarms, skill organisms, and topology advice, while keeping the lower-level wiring and analysis layers available when you need them.

Installation

pip install operon-ai

For provider-backed stages, configure whichever model backend you want to use through the existing Nucleus provider layer.

Start Here: Pattern-First API

If you are new to Operon, start here rather than with the full biological vocabulary.

• advise_topology(...) when you want architecture guidance
• reviewer_gate(...) when you want one worker plus a review bottleneck
• specialist_swarm(...) when you want centralized specialist decomposition
• skill_organism(...) when you want a provider-bound workflow with cheap vs expensive stages and attachable telemetry — supports parallel stage groups via stages=[[s1, s2], [s3]]
• managed_organism(...) when you want the full stack — adaptive assembly, watcher, substrate, development, social learning — in one call

Get topology advice

from operon_ai import advise_topology

advice = advise_topology(
    task_shape="sequential",
    tool_count=2,
    subtask_count=3,
    error_tolerance=0.02,
)

print(advice.recommended_pattern)  # single_worker_with_reviewer
print(advice.suggested_api)        # reviewer_gate(...)
print(advice.rationale)

Add a reviewer gate

from operon_ai import reviewer_gate

gate = reviewer_gate(
    executor=lambda prompt: f"EXECUTE: {prompt}",
    reviewer=lambda prompt, candidate: "safe" in prompt.lower(),
)

result = gate.run("Deploy safe schema migration")
print(result.allowed)
print(result.output)

Build a skill organism

from operon_ai import MockProvider, Nucleus, SkillStage, TelemetryProbe, skill_organism

fast = Nucleus(provider=MockProvider(responses={
    "return a deterministic routing label": "EXECUTE: billing",
}))
deep = Nucleus(provider=MockProvider(responses={
    "billing": "EXECUTE: escalate to the billing review workflow",
}))

organism = skill_organism(
    stages=[
        SkillStage(name="intake", role="Normalizer", handler=lambda task: {"request": task}),
        SkillStage(
            name="router",
            role="Classifier",
            instructions="Return a deterministic routing label.",
            mode="fixed",
        ),
        SkillStage(
            name="planner",
            role="Planner",
            instructions="Use the routing result to propose the next action.",
            mode="fuzzy",
        ),
    ],
    fast_nucleus=fast,
    deep_nucleus=deep,
    components=[TelemetryProbe()],
)

result = organism.run("Customer says the refund never posted.")
print(result.final_output)

Stages can be grouped for parallel execution:

organism = skill_organism(
    stages=[
        [  # These two run concurrently
            SkillStage(name="research_a", role="Researcher", instructions="...", mode="fixed"),
            SkillStage(name="research_b", role="Researcher", instructions="...", mode="fixed"),
        ],
        SkillStage(name="synthesize", role="Writer", instructions="...", mode="fuzzy"),
    ],
    fast_nucleus=fast,
    deep_nucleus=deep,
)

Drop down a layer when you need to

The pattern layer is additive, not a separate framework. You can still inspect the generated structure and analysis underneath. For a gate returned by reviewer_gate(...):

• gate.diagram
• gate.analysis

For a swarm returned by specialist_swarm(...):

• swarm.diagram
• swarm.analysis

Bi-Temporal Memory

Append-only factual memory with dual time axes (valid time vs record time) for auditable decision-making. Stages can read from and write to a shared BiTemporalMemory substrate, enabling belief-state reconstruction ("what did the organism know when stage X decided?").

from operon_ai import BiTemporalMemory, MockProvider, Nucleus, SkillStage, skill_organism

mem = BiTemporalMemory()
nucleus = Nucleus(provider=MockProvider(responses={}))

organism = skill_organism(
    stages=[
        SkillStage(
            name="research",
            role="Researcher",
            handler=lambda task: {"risk": "medium", "sector": "fintech"},
            emit_output_fact=True,  # records output under subject=task
        ),
        SkillStage(
            name="strategist",
            role="Strategist",
            handler=lambda task, state, outputs, stage, view: f"Recommend based on {len(view.facts)} facts",
            read_query="Review account acct:1",  # must match the task string used as subject
        ),
    ],
    fast_nucleus=nucleus,
    deep_nucleus=nucleus,
    substrate=mem,
)

result = organism.run("Review account acct:1")
print(mem.history("Review account acct:1"))  # full append-only audit trail

See the Bi-Temporal Memory docs, examples 69–71, and the interactive explorer.

Convergence: Structural Analysis for External Frameworks

The operon_ai.convergence package provides typed adapters for 6 external agent frameworks (Swarms, DeerFlow, AnimaWorks, Ralph, A-Evolve, Scion) into Operon's structural analysis layer. No external dependencies — all operate on plain dicts.

from operon_ai import PatternLibrary
from operon_ai.convergence import (
    parse_swarm_topology, analyze_external_topology,
    seed_library_from_swarms, get_builtin_swarms_patterns,
)

# Analyze a Swarms workflow with Operon's epistemic theorems
topology = parse_swarm_topology(
    "HierarchicalSwarm",
    agent_specs=[
        {"name": "manager", "role": "Manager"},
        {"name": "coder", "role": "Developer"},
        {"name": "reviewer", "role": "Reviewer"},
    ],
    edges=[("manager", "coder"), ("manager", "reviewer")],
)
result = analyze_external_topology(topology)
print(result.risk_score, result.warnings)

# Seed a PatternLibrary from Swarms' built-in patterns
library = PatternLibrary()
seed_library_from_swarms(library, get_builtin_swarms_patterns())

Compile organisms into deployment configs for Swarms, DeerFlow, Ralph, and Scion:

from operon_ai.convergence import organism_to_swarms, organism_to_scion
swarms_config = organism_to_swarms(organism)
scion_config = organism_to_scion(organism, runtime="docker")

Compile to LangGraph with all structural guarantees enforced natively (requires pip install operon-ai[langgraph]):

from operon_ai.convergence.langgraph_compiler import run_organism_langgraph

# Works with any organism — multi-stage pipelines included
result = run_organism_langgraph(organism, task="Review this code")
print(result.output, result.interventions, result.certificates_verified)

See examples 86–108 and the Convergence docs.

Learn More

Public docs now live at banu.be/operon. The tracked source for that docs shell lives in the repo under docs/site/.

• Getting Started
• Pattern-First API
• Skill Organisms
• Bi-Temporal Memory
• Convergence
• Examples
• Concepts and Architecture
• Theory and Papers
• API Overview
• Hugging Face Spaces
• Release Notes

Direct links:

• Examples index (116 runnable examples)
• Wiring diagrams (63 architecture diagrams)
• Main whitepaper
• Epistemic topology paper
• PyPI package
• Harness Inspector — explore the Architecture triple (G, Know, Φ)
• Escalation Lab — quality-based model escalation demo
• LangGraph Visualizer — per-stage graph topology
• Epistemic Topology Explorer
• Diagram Builder
• Bi-Temporal Memory Explorer

Contributing

Issues and pull requests are welcome. Start with the pattern-first examples, then drop into the lower-level layers only when the problem actually needs them.

License

MIT