Metadata-Version: 2.4
Name: operon-ai
Version: 0.18.2
Summary: Biomimetic wiring diagrams for robust agentic systems.
Project-URL: Homepage, https://github.com/coredipper/operon
Project-URL: Documentation, https://coredipper.github.io/operon/
Project-URL: Repository, https://github.com/coredipper/operon
Project-URL: Changelog, https://coredipper.github.io/operon/releases/
Author-email: Bogdan Banu <bogdan@banu.be>
License-Expression: MIT
License-File: LICENSE
Keywords: agents,biology,category-theory,llm,reliability
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.11
Requires-Dist: pydantic>=2.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == 'dev'
Provides-Extra: eval
Requires-Dist: agentdojo>=0.1.35; extra == 'eval'
Requires-Dist: bfcl-eval>=2026.2; extra == 'eval'
Provides-Extra: llm
Requires-Dist: anthropic>=0.18.0; extra == 'llm'
Requires-Dist: google-genai>=1.0.0; extra == 'llm'
Requires-Dist: openai>=1.0.0; extra == 'llm'
Description-Content-Type: text/markdown

# Operon 🧬

**Biologically inspired architectures for more reliable AI agent systems**

> *Safety from structure, not just strings.*

![Status](https://img.shields.io/badge/status-experimental-orange)
![Version](https://img.shields.io/badge/pypi-v0.18.2-blue)
![License](https://img.shields.io/badge/license-MIT-green)
[![Publish to PyPI](https://github.com/coredipper/operon/actions/workflows/publish.yml/badge.svg)](https://github.com/coredipper/operon/actions/workflows/publish.yml)

> 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

```bash
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

### Get topology advice

```python
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

```python
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

```python
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:

- `gate.diagram`
- `gate.analysis`
- `swarm.diagram`
- `swarm.analysis`

## Learn More

Public docs now live at [coredipper.github.io/operon](https://coredipper.github.io/operon/). The tracked source for that docs shell lives in the repo under [`docs/site/`](https://github.com/coredipper/operon/tree/main/docs/site).

- [Getting Started](https://coredipper.github.io/operon/getting-started/)
- [Pattern-First API](https://coredipper.github.io/operon/pattern-first-api/)
- [Skill Organisms](https://coredipper.github.io/operon/skill-organisms/)
- [Examples](https://coredipper.github.io/operon/examples/)
- [Concepts and Architecture](https://coredipper.github.io/operon/concepts/)
- [Theory and Papers](https://coredipper.github.io/operon/theory/)
- [API Overview](https://coredipper.github.io/operon/api/)
- [Hugging Face Spaces](https://coredipper.github.io/operon/spaces/)
- [Release Notes](https://coredipper.github.io/operon/releases/)

Direct links:

- [Examples index](https://github.com/coredipper/operon/blob/main/examples/README.md)
- [Main whitepaper](https://github.com/coredipper/operon/blob/main/article/main.pdf)
- [Epistemic topology paper](https://github.com/coredipper/operon/blob/main/article/paper1/main.pdf)
- [PyPI package](https://pypi.org/project/operon-ai/)
- [Epistemic Topology Explorer](https://huggingface.co/spaces/coredipper/operon-epistemic)
- [Diagram Builder](https://huggingface.co/spaces/coredipper/operon-diagram-builder)

## Status

The recommended front door is now the pattern-first API. The lower-level wiring, epistemic, and biologically inspired modules still exist, but new users should not need to start there.

## 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
