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 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 telemetrymanaged_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)
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")
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 (108 runnable examples)
- Wiring diagrams (63 architecture diagrams)
- Main whitepaper
- Epistemic topology paper
- PyPI package
- 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.31.1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| operon_ai-0.31.1.tar.gz | 1.8 MB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| operon_ai-0.31.1-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 2.1 MB
Release files / operon_ai-0.31.1.tar.gz
| Download URL | operon_ai-0.31.1.tar.gz |
|---|---|
| Size | 1.8 MB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
0f50f8fe2ef1acdaf0b35c0031547653e7bf9049e93d9b607b189f50967b578a
|
|
BLAKE2b-256 checksum How to use checksums |
7bafc6691424d25e7499e021ef18883baa8d705047d25dcb7d32b296645851a4
|
| 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 Apr 12, 2026.
Transparency logRelease files / operon_ai-0.31.1-py3-none-any.whl
| Download URL | operon_ai-0.31.1-py3-none-any.whl |
|---|---|
| Size | 324.2 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
95d93d2e9e9272c24c14a506d20dc38f49a95ca5a0010e3155a43da96c3ed648
|
|
BLAKE2b-256 checksum How to use checksums |
c7e9a126457c8bcb63b6ac5cf497759fbd4869040887ec45276d8f20a8b480fb
|
| 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 Apr 12, 2026.
Transparency log
