{"id":34048934,"url":"https://github.com/coredipper/operon","last_synced_at":"2026-04-19T16:05:41.237Z","repository":{"id":328423776,"uuid":"1112638322","full_name":"coredipper/operon","owner":"coredipper","description":"Biologically Inspired Architectures for EpiAgentic Control","archived":false,"fork":false,"pushed_at":"2026-04-10T22:45:11.000Z","size":10296,"stargazers_count":28,"open_issues_count":1,"forks_count":2,"subscribers_count":3,"default_branch":"main","last_synced_at":"2026-04-11T00:22:03.168Z","etag":null,"topics":["agents","biology","category-theory","complex-systems","llm","reliability"],"latest_commit_sha":null,"homepage":"https://pypi.org/project/operon-ai/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/coredipper.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2025-12-08T22:42:29.000Z","updated_at":"2026-04-10T16:04:28.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/coredipper/operon","commit_stats":null,"previous_names":["coredipper/operon"],"tags_count":47,"template":false,"template_full_name":null,"purl":"pkg:github/coredipper/operon","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/coredipper%2Foperon","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/coredipper%2Foperon/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/coredipper%2Foperon/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/coredipper%2Foperon/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/coredipper","download_url":"https://codeload.github.com/coredipper/operon/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/coredipper%2Foperon/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31753550,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-13T09:16:15.125Z","status":"ssl_error","status_checked_at":"2026-04-13T09:16:05.023Z","response_time":93,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agents","biology","category-theory","complex-systems","llm","reliability"],"created_at":"2025-12-14T00:16:28.043Z","updated_at":"2026-04-19T16:05:41.211Z","avatar_url":"https://github.com/coredipper.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Operon 🧬\n\n**Biologically inspired architectures for more reliable AI agent systems**\n\n\u003e *From agent heuristics toward structural guarantees.*\n\n![Status](https://img.shields.io/badge/status-experimental-orange)\n![Version](https://img.shields.io/badge/pypi-v0.35.0-blue)\n![License](https://img.shields.io/badge/license-MIT-green)\n[![Publish to PyPI](https://github.com/coredipper/operon/actions/workflows/publish.yml/badge.svg)](https://github.com/coredipper/operon/actions/workflows/publish.yml)\n\n\u003e Operon is a research-grade library and reference implementation for biologically inspired agent control patterns. The API is still evolving.\n\n## The Problem: Fragile Agents\n\nMost agent systems fail structurally, not just locally.\n\nA 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.\n\nOperon 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.\n\n## Installation\n\n```bash\npip install operon-ai\n```\n\nFor provider-backed stages, configure whichever model backend you want to use through the existing `Nucleus` provider layer.\n\n## Start Here: Pattern-First API\n\nIf you are new to Operon, start here rather than with the full biological vocabulary.\n\n- `advise_topology(...)` when you want architecture guidance\n- `reviewer_gate(...)` when you want one worker plus a review bottleneck\n- `specialist_swarm(...)` when you want centralized specialist decomposition\n- `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]]`\n- `managed_organism(...)` when you want the full stack — adaptive assembly, watcher, substrate, development, social learning — in one call\n\n### Get topology advice\n\n```python\nfrom operon_ai import advise_topology\n\nadvice = advise_topology(\n    task_shape=\"sequential\",\n    tool_count=2,\n    subtask_count=3,\n    error_tolerance=0.02,\n)\n\nprint(advice.recommended_pattern)  # single_worker_with_reviewer\nprint(advice.suggested_api)        # reviewer_gate(...)\nprint(advice.rationale)\n```\n\n### Add a reviewer gate\n\n```python\nfrom operon_ai import reviewer_gate\n\ngate = reviewer_gate(\n    executor=lambda prompt: f\"EXECUTE: {prompt}\",\n    reviewer=lambda prompt, candidate: \"safe\" in prompt.lower(),\n)\n\nresult = gate.run(\"Deploy safe schema migration\")\nprint(result.allowed)\nprint(result.output)\n```\n\n### Build a skill organism\n\n```python\nfrom operon_ai import MockProvider, Nucleus, SkillStage, TelemetryProbe, skill_organism\n\nfast = Nucleus(provider=MockProvider(responses={\n    \"return a deterministic routing label\": \"EXECUTE: billing\",\n}))\ndeep = Nucleus(provider=MockProvider(responses={\n    \"billing\": \"EXECUTE: escalate to the billing review workflow\",\n}))\n\norganism = skill_organism(\n    stages=[\n        SkillStage(name=\"intake\", role=\"Normalizer\", handler=lambda task: {\"request\": task}),\n        SkillStage(\n            name=\"router\",\n            role=\"Classifier\",\n            instructions=\"Return a deterministic routing label.\",\n            mode=\"fixed\",\n        ),\n        SkillStage(\n            name=\"planner\",\n            role=\"Planner\",\n            instructions=\"Use the routing result to propose the next action.\",\n            mode=\"fuzzy\",\n        ),\n    ],\n    fast_nucleus=fast,\n    deep_nucleus=deep,\n    components=[TelemetryProbe()],\n)\n\nresult = organism.run(\"Customer says the refund never posted.\")\nprint(result.final_output)\n```\n\nStages can be grouped for parallel execution:\n\n```python\norganism = skill_organism(\n    stages=[\n        [  # These two run concurrently\n            SkillStage(name=\"research_a\", role=\"Researcher\", instructions=\"...\", mode=\"fixed\"),\n            SkillStage(name=\"research_b\", role=\"Researcher\", instructions=\"...\", mode=\"fixed\"),\n        ],\n        SkillStage(name=\"synthesize\", role=\"Writer\", instructions=\"...\", mode=\"fuzzy\"),\n    ],\n    fast_nucleus=fast,\n    deep_nucleus=deep,\n)\n```\n\n### Drop down a layer when you need to\n\nThe 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(...)`:\n\n- `gate.diagram`\n- `gate.analysis`\n\nFor a swarm returned by `specialist_swarm(...)`:\n\n- `swarm.diagram`\n- `swarm.analysis`\n\n### Bi-Temporal Memory\n\nAppend-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?\").\n\n```python\nfrom operon_ai import BiTemporalMemory, MockProvider, Nucleus, SkillStage, skill_organism\n\nmem = BiTemporalMemory()\nnucleus = Nucleus(provider=MockProvider(responses={}))\n\norganism = skill_organism(\n    stages=[\n        SkillStage(\n            name=\"research\",\n            role=\"Researcher\",\n            handler=lambda task: {\"risk\": \"medium\", \"sector\": \"fintech\"},\n            emit_output_fact=True,  # records output under subject=task\n        ),\n        SkillStage(\n            name=\"strategist\",\n            role=\"Strategist\",\n            handler=lambda task, state, outputs, stage, view: f\"Recommend based on {len(view.facts)} facts\",\n            read_query=\"Review account acct:1\",  # must match the task string used as subject\n        ),\n    ],\n    fast_nucleus=nucleus,\n    deep_nucleus=nucleus,\n    substrate=mem,\n)\n\nresult = organism.run(\"Review account acct:1\")\nprint(mem.history(\"Review account acct:1\"))  # full append-only audit trail\n```\n\nSee the [Bi-Temporal Memory docs](https://banu.be/operon/bitemporal-memory/), [examples 69–71](examples/), and the [interactive explorer](https://huggingface.co/spaces/coredipper/operon-bitemporal).\n\n### Convergence: Structural Analysis for External Frameworks\n\nThe `operon_ai.convergence` package provides typed adapters for 6 external agent frameworks ([Swarms](https://github.com/kyegomez/swarms), [DeerFlow](https://github.com/bytedance/deer-flow), [AnimaWorks](https://github.com/xuiltul/animaworks), [Ralph](https://github.com/mikeyobrien/ralph-orchestrator), [A-Evolve](https://github.com/A-EVO-Lab/a-evolve), [Scion](https://github.com/GoogleCloudPlatform/scion)) into Operon's structural analysis layer. No external dependencies — all operate on plain dicts.\n\n```python\nfrom operon_ai import PatternLibrary\nfrom operon_ai.convergence import (\n    parse_swarm_topology, analyze_external_topology,\n    seed_library_from_swarms, get_builtin_swarms_patterns,\n)\n\n# Analyze a Swarms workflow with Operon's epistemic theorems\ntopology = parse_swarm_topology(\n    \"HierarchicalSwarm\",\n    agent_specs=[\n        {\"name\": \"manager\", \"role\": \"Manager\"},\n        {\"name\": \"coder\", \"role\": \"Developer\"},\n        {\"name\": \"reviewer\", \"role\": \"Reviewer\"},\n    ],\n    edges=[(\"manager\", \"coder\"), (\"manager\", \"reviewer\")],\n)\nresult = analyze_external_topology(topology)\nprint(result.risk_score, result.warnings)\n\n# Seed a PatternLibrary from Swarms' built-in patterns\nlibrary = PatternLibrary()\nseed_library_from_swarms(library, get_builtin_swarms_patterns())\n```\n\nCompile organisms into deployment configs for [Swarms](https://github.com/kyegomez/swarms), [DeerFlow](https://github.com/bytedance/deer-flow), [Ralph](https://github.com/mikeyobrien/ralph-orchestrator), and [Scion](https://github.com/GoogleCloudPlatform/scion):\n\n```python\nfrom operon_ai.convergence import organism_to_swarms, organism_to_scion\nswarms_config = organism_to_swarms(organism)\nscion_config = organism_to_scion(organism, runtime=\"docker\")\n```\n\nCompile to LangGraph with all structural guarantees enforced natively (requires `pip install operon-ai[langgraph]`):\n\n```python\nfrom operon_ai.convergence.langgraph_compiler import run_organism_langgraph\n\n# Works with any organism — multi-stage pipelines included\nresult = run_organism_langgraph(organism, task=\"Review this code\")\nprint(result.output, result.interventions, result.certificates_verified)\n```\n\nSee [examples 86–108](examples/) and the [Convergence docs](https://banu.be/operon/convergence/).\n\n## Learn More\n\nPublic docs now live at [banu.be/operon](https://banu.be/operon/). The tracked source for that docs shell lives in the repo under [`docs/site/`](https://github.com/coredipper/operon/tree/main/docs/site).\n\n- [Getting Started](https://banu.be/operon/getting-started/)\n- [Pattern-First API](https://banu.be/operon/pattern-first-api/)\n- [Skill Organisms](https://banu.be/operon/skill-organisms/)\n- [Bi-Temporal Memory](https://banu.be/operon/bitemporal-memory/)\n- [Convergence](https://banu.be/operon/convergence/)\n- [Examples](https://banu.be/operon/examples/)\n- [Concepts and Architecture](https://banu.be/operon/concepts/)\n- [Theory and Papers](https://banu.be/operon/theory/)\n- [API Overview](https://banu.be/operon/api/)\n- [Hugging Face Spaces](https://banu.be/operon/spaces/)\n- [Release Notes](https://banu.be/operon/releases/)\n\nDirect links:\n\n- [Examples index](https://github.com/coredipper/operon/blob/main/examples/README.md) (116 runnable examples)\n- [Wiring diagrams](https://github.com/coredipper/operon/blob/main/examples/wiring_diagrams.md) (63 architecture diagrams)\n- [Main whitepaper](https://github.com/coredipper/operon/blob/main/article/main.pdf)\n- [Epistemic topology paper](https://github.com/coredipper/operon/blob/main/article/paper1/main.pdf)\n- [PyPI package](https://pypi.org/project/operon-ai/)\n- [Harness Inspector](https://huggingface.co/spaces/coredipper/operon-harness-inspector) — explore the Architecture triple (G, Know, Φ)\n- [Escalation Lab](https://huggingface.co/spaces/coredipper/operon-escalation-lab) — quality-based model escalation demo\n- [LangGraph Visualizer](https://huggingface.co/spaces/coredipper/operon-langgraph-visualizer) — per-stage graph topology\n- [Epistemic Topology Explorer](https://huggingface.co/spaces/coredipper/operon-epistemic)\n- [Diagram Builder](https://huggingface.co/spaces/coredipper/operon-diagram-builder)\n- [Bi-Temporal Memory Explorer](https://huggingface.co/spaces/coredipper/operon-bitemporal)\n\n## Contributing\n\nIssues 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.\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcoredipper%2Foperon","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcoredipper%2Foperon","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcoredipper%2Foperon/lists"}