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.

What Operon Is Opinionated About

Agent frameworks tend to converge on a similar feature set — tools, memory, handoffs, retries. Operon is deliberately opinionated on a different axis: what kinds of claim the library lets you make about the system you have built.

• Structural guarantees as verifiable proofs. A gate is not just a conditional. Certificate pairs a theorem name with a verify_fn that re-checks the claim externally; ApprovalToken carries proofs through two-key execution. Quality, priority gating, and integrity become artifacts you can re-verify, not assertions you trust.
• Topology is a first-class, analyzable object.advise_topology() and EpistemicAnalysis classify a wiring diagram's risk profile — observability, routing cost, convergence depth — before a run. You can reason about the shape of the system, not only its outputs.
• Framework-neutral by design.operon_ai.convergence adapts six external agent frameworks (Swarms, DeerFlow, AnimaWorks, Ralph, A-Evolve, Scion) into a common IR and back out, with certificates transporting across framework boundaries via A2A parts. Operon is meant to wrap your existing runner, not replace it.
• Theory you can inspect. Six papers in article/ develop the foundations — epistemic topology, categorical convergence, structural-guarantee benchmarks, harness-as-categorical-architecture — alongside the code that implements them. Biological motifs (gene regulatory networks, immune systems, metabolic priority gating, quorum sensing) are applied concretely, not as metaphor.

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

fromoperon_aiimportadvise_topologyadvice=advise_topology(
task_shape="sequential",
tool_count=2,
subtask_count=3,
error_tolerance=0.02,
)
print(advice.recommended_pattern) # single_worker_with_reviewerprint(advice.suggested_api) # reviewer_gate(...)print(advice.rationale)

Add a reviewer gate

fromoperon_aiimportreviewer_gategate=reviewer_gate(
executor=lambdaprompt: f"EXECUTE: {prompt}",
reviewer=lambdaprompt, candidate: "safe"inprompt.lower(),
)
result=gate.run("Deploy safe schema migration")
print(result.allowed)
print(result.output)

Build a skill organism

fromoperon_aiimportMockProvider, Nucleus, SkillStage, TelemetryProbe, skill_organismfast=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=lambdatask: {"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 concurrentlySkillStage(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?").

fromoperon_aiimportBiTemporalMemory, MockProvider, Nucleus, SkillStage, skill_organismmem=BiTemporalMemory()
nucleus=Nucleus(provider=MockProvider(responses={}))
organism=skill_organism(
stages=[
SkillStage(
name="research",
role="Researcher",
handler=lambdatask: {"risk": "medium", "sector": "fintech"},
emit_output_fact=True, # records output under subject=task
),
SkillStage(
name="strategist",
role="Strategist",
handler=lambdatask, 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.

fromoperon_aiimportPatternLibraryfromoperon_ai.convergenceimport (
parse_swarm_topology, analyze_external_topology,
seed_library_from_swarms, get_builtin_swarms_patterns,
)
# Analyze a Swarms workflow with Operon's epistemic theoremstopology=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 patternslibrary=PatternLibrary()
seed_library_from_swarms(library, get_builtin_swarms_patterns())

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

fromoperon_ai.convergenceimportorganism_to_swarms, organism_to_scionswarms_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]):

fromoperon_ai.convergence.langgraph_compilerimportrun_organism_langgraph# Works with any organism — multi-stage pipelines includedresult=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 (122 runnable examples)
• Wiring diagrams (49 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