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.
Certificatepairs a theorem name with averify_fnthat re-checks the claim externally;ApprovalTokencarries 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()andEpistemicAnalysisclassify 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.convergenceadapts 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 guidancereviewer_gate(...)when you want one worker plus a review bottleneckspecialist_swarm(...)when you want centralized specialist decompositionskill_organism(...)when you want a provider-bound workflow with cheap vs expensive stages and attachable telemetry — supports parallel stage groups viastages=[[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.diagramgate.analysis
For a swarm returned by specialist_swarm(...):
swarm.diagramswarm.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 (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
1 maintainer
Metadata
1 maintainer
Release files for operon-ai 0.39.10
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | |
|---|---|---|---|---|
| operon_ai-0.39.10.tar.gz | 3.0 MB | With provenance | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| operon_ai-0.39.10-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 3.4 MB
Release files / operon_ai-0.39.10.tar.gz
| Download URL | operon_ai-0.39.10.tar.gz |
|---|---|
| Size | 3.0 MB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
3ee92bbf5237822388f631a7091a214abe61942dbebc81ea80284e8713e8c0e5
|
|
BLAKE2b-256 checksum How to use checksums |
008f00fc2e82670c57cf6c51c8e90be1dd98b6639a759622fdf72887310ef5e5
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.12
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Jul 3, 2026.
Transparency logRelease files / operon_ai-0.39.10-py3-none-any.whl
| Download URL | operon_ai-0.39.10-py3-none-any.whl |
|---|---|
| Size | 371.2 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
d89a957c7be4d47fc0a91f5ab5eae500c3538bf9fbd5a11bc75def051cc9bdae
|
|
BLAKE2b-256 checksum How to use checksums |
9f225e4aa10e4e6b0bc31ae54966321975e71e38eb4dfb12a502e0f2cac33562
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.12
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Jul 3, 2026.
Transparency logSecurity for operon-ai 0.39.10
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
All 2 files in this release have been uploaded with provenance metadata.
Attestation for operon_ai-0.39.10.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Jul 3, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.
