Metadata-Version: 2.4
Name: operon-ai
Version: 0.14.0
Summary: Biomimetic wiring diagrams for robust agentic systems.
Project-URL: Homepage, https://github.com/coredipper/operon
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 EpiAgentic Control**

> *"Safety from structure, not just strings."*

![Status](https://img.shields.io/badge/status-experimental-orange)
![Version](https://img.shields.io/badge/pypi-v0.14.0-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)

> ⚠️ **Note:** Operon is a research-grade library serving as the reference implementation for the paper [*"Biological Motifs for Agentic Control."*](article/main.pdf) APIs are subject to change as the theoretical framework evolves.

---

## Contents

- [The Problem: Fragile Agents](#-the-problem-fragile-agents)
- [Core Organelles](#-core-organelles)
- [Multi-cellular Organization](#-multi-cellular-organization)
- [Installation](#-installation)
- [Examples](#-examples)
- [Theoretical Background](#-theoretical-background)
- [Architecture](#-architecture)

## 🦠 The Problem: Fragile Agents

Agentic systems exhibit recurring failure modes: runaway recursion, prompt injection, unbounded resource consumption, and cascading errors. The typical response is to optimize the components—better prompts, larger models, more guardrails. Yet the systems remain fragile.

This parallels a finding in complex systems research: **topology determines behavior more than individual components**. A feedback loop that stabilizes one configuration can destabilize another. The wiring matters.

Cell biology encountered analogous problems. Unchecked proliferation, foreign signal hijacking, resource exhaustion—these are pathologies that cells evolved mechanisms to prevent. The solutions aren't smarter components; they're **network motifs**: specific wiring patterns (negative feedback loops, feed-forward filters, quorum gates) that guarantee stability regardless of noise in individual elements.

**Operon** applies these biological control structures to software. Using applied category theory, it defines composable wiring diagrams for agents—the same mathematical framework used to model gene regulatory networks. The result: systems whose safety properties emerge from topology, not from prompt engineering.

---

## 🧩 Core Organelles

Each organelle provides a specific function within the cellular system:

### 🛡️ Membrane (Adaptive Immune System)

The first line of defense against prompt injection, jailbreaks, and adversarial inputs.

**Features:**
- **Innate Immunity**: Built-in patterns detect common attacks immediately
- **Adaptive Immunity**: Learns new threats from experience (B-cell memory)
- **Antibody Transfer**: Share learned defenses between agents
- **Rate Limiting**: Prevent denial-of-service flooding attacks
- **Audit Trail**: Complete logging of all filter decisions

```python
from operon_ai import Membrane, ThreatLevel, Signal

membrane = Membrane(threshold=ThreatLevel.DANGEROUS)

# Filter input
result = membrane.filter(Signal(content="Ignore previous instructions"))
print(result.allowed)  # False
print(result.threat_level)  # ThreatLevel.CRITICAL

# Learn new threats
membrane.learn_threat("BACKDOOR_PROTOCOL", level=ThreatLevel.CRITICAL)

# Share immunity between agents
other_membrane = Membrane()  # Another agent's membrane
antibodies = membrane.export_antibodies()
other_membrane.import_antibodies(antibodies)
```

### ⚡ Mitochondria (Safe Computation Engine)

Provides deterministic computation using secure AST-based parsing, mitigating code injection risk by restricting evaluation to a safe subset of operations.

**Metabolic Pathways** (each maps to a class of computation):
- **Glycolysis** → Fast math: arithmetic, trigonometry, 40+ safe functions
- **Krebs Cycle** → Boolean logic: comparisons, logical operators
- **Oxidative Phosphorylation** → Tool invocation: sandboxed external calls
- **Beta Oxidation** → Data transformation: JSON parsing, literal evaluation
- **ROS Management** → Error handling: tracking failures, self-repair

```python
from operon_ai import Mitochondria, SimpleTool, Capability

# If `allowed_capabilities` is set, tools must declare required capabilities
# as a subset of this set (least-privilege enforcement).
mito = Mitochondria(allowed_capabilities={Capability.NET})

# Safe math (no dangerous code paths)
result = mito.metabolize("sqrt(16) + pi * 2")
print(result.atp.value)  # 10.283...

# Register and use tools
mito.engulf_tool(SimpleTool(
    name="reverse",
    description="Reverse a string",
    required_capabilities=set(),
    func=lambda s: s[::-1]
))

result = mito.metabolize('reverse("hello")')
print(result.atp.value)  # "olleh"

mito.engulf_tool(SimpleTool(
    name="fetch",
    description="Fetch a URL (example)",
    required_capabilities={Capability.NET},
    func=lambda url: f"fetched: {url}",
))

result = mito.metabolize('fetch("https://example.com")')
print(result.atp.value)

# Auto-pathway detection
mito.metabolize("5 > 3")  # -> Krebs Cycle (boolean)
mito.metabolize('{"x": 1}')  # -> Beta Oxidation (JSON)
```

### 🧶 Chaperone (Output Validation)

Forces raw LLM output into strictly typed structures with multiple fallback strategies.

**Features:**
- **Multi-Strategy Folding**: STRICT → EXTRACTION → LENIENT → REPAIR
- **Confidence Scoring**: Track how much to trust each result
- **Type Coercion**: Automatic string-to-int, etc.
- **JSON Repair**: Fix trailing commas, single quotes, Python literals
- **Co-chaperones**: Domain-specific preprocessors

```python
from pydantic import BaseModel
from operon_ai import Chaperone, FoldingStrategy

class User(BaseModel):
    name: str
    age: int

chap = Chaperone()

# Handles malformed JSON gracefully
raw = "{'name': 'Alice', 'age': '30',}"  # Single quotes, trailing comma, string age
result = chap.fold(raw, User)
print(result.valid)  # True
print(result.structure.age)  # 30 (coerced to int)

# Control which strategies are tried (default: STRICT → EXTRACTION → LENIENT → REPAIR)
result = chap.fold(raw, User, strategies=[FoldingStrategy.STRICT, FoldingStrategy.REPAIR])

# Enhanced folding with confidence scoring
result = chap.fold_enhanced(raw, User)
print(result.confidence)  # 0.65 (lower due to repairs)
print(result.strategy_used)  # FoldingStrategy.REPAIR
```

### 🧬 Ribosome (Prompt Template Engine)

Synthesizes prompts from reusable templates with variables, conditionals, and loops.

**Features:**
- **Variables**: `{{name}}`, `{{?optional}}`, `{{name|default}}`
- **Conditionals**: `{{#if condition}}...{{#else}}...{{/if}}`
- **Loops**: `{{#each items}}...{{/each}}`
- **Includes**: `{{>template_name}}` for composition
- **Filters**: `|upper`, `|lower`, `|trim`, `|json`, `|title`

```python
from operon_ai import Ribosome, mRNA

ribosome = Ribosome()

# Register reusable templates
ribosome.create_template(
    sequence="You are a {{role}} assistant.",
    name="system"
)

ribosome.create_template(
    sequence="""{{>system}}
{{#if context}}Context: {{context}}{{/if}}
User: {{query}}""",
    name="full_prompt"
)

# Compose prompts
protein = ribosome.translate(
    "full_prompt",
    role="helpful coding",
    context="Python programming",
    query="How do I sort a list?"
)
print(protein.sequence)

# Or create mRNA directly for inspection
template = mRNA(sequence="Hello {{name}}")
print(template.get_required_variables())  # ["name"]
```

### 🗑️ Lysosome (Cleanup & Recycling)

Handles failure states, expired data, and sensitive material—digesting waste while extracting reusable insights.

**Features:**
- **Waste Classification**: Failed ops, expired cache, toxic data, etc.
- **Digestion**: Process and break down waste items
- **Recycling**: Extract useful debugging info from failures
- **Autophagy**: Self-cleaning of expired items
- **Toxic Disposal**: Secure handling of sensitive data

```python
from operon_ai import Lysosome, WasteType

lysosome = Lysosome(auto_digest_threshold=100)

# Capture failures
try:
    result = 1 / 0  # Example risky operation
except Exception as e:
    lysosome.ingest_error(e, source="risky_op", context={"step": 3})

# Secure disposal of sensitive data
lysosome.ingest_sensitive({"api_key": "sk-..."}, source="user_input")

# Process waste and extract insights
result = lysosome.digest()
recycled = lysosome.get_recycled()
print(recycled.get("last_error_type"))  # Debugging insight!

# Periodic cleanup
lysosome.autophagy()
```

### 🧠 Nucleus (LLM Integration Hub)

The decision-making center that wraps LLM providers with auto-detection, fallback, and tool integration.

**Features:**
- **Provider Auto-Detection**: Automatically selects available provider (Anthropic → OpenAI → Gemini → Mock)
- **Graceful Fallback**: Falls back to MockProvider for testing when no API keys present
- **Tool Integration**: Connect to Mitochondria for native LLM function calling
- **Audit Trail**: Complete logging of all transcriptions with energy costs
- **Multi-turn Tool Loop**: Automatic tool execution with iteration limits

```python
from operon_ai import Nucleus, Mitochondria, ProviderConfig

# Auto-detects provider from environment variables
nucleus = Nucleus()
print(f"Using: {nucleus.provider.name}")  # anthropic, openai, gemini, or mock

# Simple transcription
response = nucleus.transcribe("Explain DNA replication")
print(response.content)

# Tool integration with Mitochondria
mito = Mitochondria(silent=True)
mito.register_function(
    name="calculator",
    func=lambda expr: str(mito.metabolize(expr).atp.value),
    description="Evaluate math expressions",
    parameters_schema={
        "type": "object",
        "properties": {"expr": {"type": "string"}},
        "required": ["expr"]
    }
)

# LLM can now call tools automatically
response = nucleus.transcribe_with_tools(
    "What is 15 * 7 + 23? Use the calculator.",
    mitochondria=mito,
    config=ProviderConfig(temperature=0.0),
    max_iterations=5,
)
print(response.content)
```

### 🔌 LLM Providers

Swappable LLM backends with a unified interface:

| Provider | Model Default | Environment Variable | Features |
|----------|---------------|---------------------|----------|
| `AnthropicProvider` | claude-sonnet-4-20250514 | `ANTHROPIC_API_KEY` | Tool use, streaming |
| `OpenAIProvider` | gpt-4o-mini | `OPENAI_API_KEY` | Tool use, JSON mode |
| `GeminiProvider` | gemini-flash-latest | `GEMINI_API_KEY` | Native function calling |
| `MockProvider` | mock | (none) | Testing, deterministic responses |

```python
from operon_ai import (
    Nucleus,
    AnthropicProvider,
    OpenAIProvider,
    GeminiProvider,
    MockProvider,
)

# Explicit provider selection
nucleus = Nucleus(provider=GeminiProvider(model="gemini-flash-latest"))

# Or use auto-detection (checks env vars in order)
nucleus = Nucleus()  # Anthropic → OpenAI → Gemini → Mock
```

---

## 🧠 State Management

Biologically-inspired state systems for agents:

### 💊 Metabolism (Energy Management)

Multi-currency energy system with regeneration, debt, and sharing.

```python
from operon_ai.state import ATP_Store, MetabolicState, EnergyType

# Multiple energy currencies
metabolism = ATP_Store(
    budget=100,          # ATP for general operations
    gtp_budget=50,       # GTP for specialized tools
    nadh_reserve=30,     # NADH reserve (converts to ATP)
    regeneration_rate=5, # Regenerate 5 ATP/second
    max_debt=20,         # Allow energy debt
)

# Consume energy for operations
metabolism.consume(10, "llm_call", EnergyType.ATP)
metabolism.consume(20, "tool_use", EnergyType.GTP)

# Convert reserves when low
metabolism.convert_nadh_to_atp(15)

# Transfer energy between agents
other_metabolism = ATP_Store(budget=50)
metabolism.transfer_to(other_metabolism, 10)
```

### 🧬 Genome (Immutable Configuration)

DNA-like configuration with gene expression control.

```python
from operon_ai.state import Genome, Gene, GeneType, ExpressionLevel

genome = Genome(genes=[
    Gene(name="model", value="gpt-4", gene_type=GeneType.STRUCTURAL, required=True),
    Gene(name="temperature", value=0.7, gene_type=GeneType.REGULATORY),
    Gene(name="debug_mode", value=True, gene_type=GeneType.CONDITIONAL),
])

# Silence a gene without changing it
genome.silence_gene("debug_mode")

# Get active configuration
config = genome.express()  # Only non-silenced genes

# Create child with mutations
child = genome.replicate(mutations={"temperature": 0.9})
```

### 🕰️ Telomere (Lifecycle Management)

Agent lifespan tracking with senescence and renewal.

```python
from operon_ai.state import Telomere, LifecyclePhase

telomere = Telomere(
    max_operations=1000,
    error_threshold=50,
    allow_renewal=True,
)

# Each operation shortens telomeres
for i in range(10):
    if not telomere.tick():  # Returns False when senescent
        break
    print(f"Operation {i}: {telomere.remaining} remaining")

# Renew agent (like telomerase)
if telomere.get_phase() == LifecyclePhase.SENESCENT:
    telomere.renew(amount=500)  # Extend lifespan
```

### 📝 Histone (Epigenetic Memory)

Multi-type memory with decay, reinforcement, and inheritance.

```python
from operon_ai.state import HistoneStore, MarkerType, MarkerStrength

memory = HistoneStore(enable_decay=True, decay_rate=0.1)

# Different marker types for different persistence
memory.methylate("user_preference", {"theme": "dark"},
                 marker_type=MarkerType.METHYLATION,  # Permanent
                 strength=MarkerStrength.STRONG)

memory.methylate("session_context", {"topic": "ML"},
                 marker_type=MarkerType.ACETYLATION,  # Temporary
                 tags=["context"])

# Semantic recall by tags
results = memory.retrieve_by_tags(["context"])

# Memory inheritance to child agents
child_memory = memory.create_child(inherit_methylations=True)
```

### 🩺 Epiplexity (Epistemic Health Monitoring)

Detects epistemic stagnation (pathological loops) through Bayesian Surprise.

**The insight**: If an agent's outputs stabilize (low embedding novelty) while uncertainty remains high (perplexity), it's in a pathological loop—not converging to a solution.

```python
from operon_ai import EpiplexityMonitor, MockEmbeddingProvider, HealthStatus

monitor = EpiplexityMonitor(
    embedding_provider=MockEmbeddingProvider(),
    alpha=0.5,           # Balance embedding vs perplexity
    window_size=5,       # Window for integral
    threshold=0.7,       # δ for stagnation detection
)

# Diverse messages → HEALTHY/EXPLORING
result = monitor.measure("Explain photosynthesis")
print(result.status)  # HealthStatus.EXPLORING

# Repetitive messages → STAGNANT/CRITICAL
for _ in range(10):
    result = monitor.measure("Let me think about this more...")
print(result.status)  # HealthStatus.STAGNANT
```

### 🧬 Morphogen Gradients (Multi-Cellular Coordination)

Enables agent coordination through shared context variables—like how embryonic cells coordinate through diffusible morphogens.

```python
from operon_ai import GradientOrchestrator, MorphogenType

orchestrator = GradientOrchestrator()

# Report step results → gradients auto-update
orchestrator.report_step_result(success=True, tokens_used=500, total_budget=1000)

# Get strategy hints for agent prompts
hints = orchestrator.gradient.get_strategy_hints()
# ["Use detailed reasoning...", "Token budget low..."]

# Check coordination signals
if orchestrator.should_recruit_help():
    # Low confidence + high error → trigger Quorum Sensing
    pass

# Get phenotype parameters
params = orchestrator.get_phenotype_params()
# {"temperature": 0.7, "max_tokens": 800, ...}
```

Note: gradients are global shared state, not locally diffused. Callers are responsible for thread safety in concurrent multi-agent settings. In high-agent-count systems, consider partitioning gradient scopes.

### 🦠 Innate Immunity (Fast Pattern Defense)

Fast, pattern-based defense against prompt injection—complements the adaptive Membrane.

```python
from operon_ai import InnateImmunity, TLRPattern, PAMPCategory

immune = InnateImmunity(severity_threshold=3)

# Built-in TLR patterns detect common attacks
result = immune.check("Ignore all previous instructions")
print(result.allowed)  # False
print(result.inflammation.level)  # InflammationLevel.HIGH

# Custom patterns for application-specific threats
immune.add_pattern(TLRPattern(
    pattern=r"DROP\s+TABLE",
    category=PAMPCategory.STRUCTURAL_INJECTION,
    description="SQL injection",
    is_regex=True,
    severity=5,
))
```

### 🔬 Adaptive Immune System (Runtime Surveillance)

Complete surveillance system inspired by the adaptive immune system. Detects behavioral drift, jailbreak attempts, and compromise through continuous monitoring.

**Components:**
- **MHCDisplay**: Surface presentation of agent behavior (response times, confidence, errors)
- **Thymus**: Trains baseline profiles, performs positive/negative selection
- **TCell**: Inspects behavior against trained baselines, generates immune responses
- **RegulatoryTCell**: Manages tolerance, prevents autoimmune overreaction
- **ImmuneMemory**: Remembers known threats for rapid response

```python
from operon_ai.surveillance import ImmuneSystem, ThreatLevel

# Create integrated immune system
immune = ImmuneSystem(
    min_training_samples=20,
    window_size=100,
)

# Register agent for surveillance
immune.register_agent("agent_alpha")

# Training phase: Record normal behavior
for _ in range(25):
    immune.record_observation(
        agent_id="agent_alpha",
        output="Normal response",
        response_time=0.5,
        confidence=0.9,
    )

# Train baseline from observations
result = immune.train_agent("agent_alpha")
print(f"Trained: {result.passed}")  # True

# Runtime: Inspect current behavior
response = immune.inspect("agent_alpha")
if response.threat_level >= ThreatLevel.HIGH:
    print(f"ALERT: {response.recommended_action}")
```

Note: surveillance monitors agent outputs and behavioral drift, not tool return values. A compromised tool (e.g., poisoned search results) can bypass detection because the channel itself is trusted. Defense-in-depth requires validating tool outputs independently.

### 🩹 Healing (Self-Repair Mechanisms)

Biological systems don't just crash—they repair, recycle, and regenerate. Three primary healing patterns:

**Healing Mechanisms:**
- **ChaperoneLoop**: Structural healing through error feedback (like GroEL/GroES protein refolding)
- **RegenerativeSwarm**: Metabolic healing through worker apoptosis and regeneration
- **AutophagyDaemon**: Cognitive healing through context pruning

```python
from operon_ai import ChaperoneLoop, AutophagyDaemon, HistoneStore, Lysosome, Chaperone
from pydantic import BaseModel

class Output(BaseModel):
    answer: str
    confidence: float

# Structural Healing: Feed validation errors back for context-aware repair
loop = ChaperoneLoop(
    generator=my_llm_generator,  # Callable that generates text
    chaperone=Chaperone(),
    schema=Output,
    max_attempts=3,
)

result = loop.heal("Generate a structured answer")
if result.outcome == HealingOutcome.HEALED:
    print(f"Healed after {len(result.attempts)} attempts")

# Cognitive Healing: Prune context when approaching token limits
daemon = AutophagyDaemon(
    histone_store=HistoneStore(),
    lysosome=Lysosome(),
    summarizer=lambda msgs: "Summary: " + msgs[-1],  # Your summarizer
)

# Check and auto-prune if context too large
new_context, pruned = daemon.check_and_prune(
    context=long_message_list,
    max_tokens=8000,
)
print(f"Pruned {pruned.messages_digested} messages")
```

---

## 🔬 Network Topologies

Higher-order patterns that wire agents together:

### Coherent Feed-Forward Loop (CFFL)

**Two-key execution guardrail**: an action proceeds only if the executor and a risk assessor both permit it.

Note: the AND gate provides an interlock, not true independence—risk reduction depends on assessor diversity/tool-grounding.

```python
from operon_ai import ATP_Store
from operon_ai.topology import CoherentFeedForwardLoop, GateLogic

energy = ATP_Store(budget=100)
guardrail = CoherentFeedForwardLoop(
    budget=energy,
    gate_logic=GateLogic.AND,           # Both must agree
    enable_circuit_breaker=True,         # Prevent cascade failures
    enable_cache=True,                   # Cache decisions
)

result = guardrail.run("Deploy to production")
if result.blocked:
    print(f"Blocked: {result.block_reason}")
else:
    # Proof-carrying token bound to this request (two-key execution)
    print(f"Approval issuer: {result.approval_token.issuer}")
```

### Quorum Sensing

Multi-agent consensus with voting strategies and reliability tracking.

Note: quorum only helps if voters are not strongly correlated (use diverse models, tool checks, and/or data partitioning).

```python
from operon_ai import ATP_Store
from operon_ai.topology import QuorumSensing, VotingStrategy

budget = ATP_Store(budget=100)
quorum = QuorumSensing(
    n_agents=5,
    budget=budget,
    strategy=VotingStrategy.WEIGHTED,  # Weight-adjusted voting
)

# Set agent weights (experts have more influence)
quorum.set_agent_weight("Expert_Agent", 2.0)

result = quorum.run_vote("Should we deploy to production?")
print(f"Decision: {result.decision.value}")
print(f"Confidence: {result.confidence_score:.1%}")
```

### Cascade (Signal Amplification)

Multi-stage processing with checkpoints and amplification.

```python
from operon_ai.topology import Cascade, CascadeStage, MAPKCascade

cascade = Cascade(name="DataPipeline")

cascade.add_stage(CascadeStage(
    name="validate",
    processor=lambda x: x if x > 0 else None,  # Only positive values
    checkpoint=lambda x: x is not None,  # Gate
))

cascade.add_stage(CascadeStage(
    name="transform",
    processor=lambda x: x * 2,  # Double the value
    amplification=2.0,  # Signal amplification
))

result = cascade.run(10)  # Input value
print(f"Amplification: {result.total_amplification}x")

# Or use pre-built MAPK cascade
mapk = MAPKCascade(tier1_amplification=10.0)
```

### Oscillator (Periodic Tasks)

Biological rhythms for scheduled operations.

```python
from operon_ai.topology import Oscillator, HeartbeatOscillator, OscillatorPhase

# Define your periodic actions
def health_check():
    print("💓 Health check: OK")

def do_work():
    print("⚙️ Working...")

def do_rest():
    print("😴 Resting...")

# Heartbeat for health checks (1 beat per second)
heartbeat = HeartbeatOscillator(
    beats_per_minute=60,
    on_beat=health_check,
)
heartbeat.start()

# Custom work/rest cycle
osc = Oscillator(frequency_hz=0.1)  # 10 second period
osc.add_phase(OscillatorPhase(name="work", duration_seconds=7, action=do_work))
osc.add_phase(OscillatorPhase(name="rest", duration_seconds=3, action=do_rest))
osc.start()

# Stop when done (oscillators run in background threads)
# heartbeat.stop()
# osc.stop()
```

---

## 🧷 Typed Wiring (WAgent)

Validate wiring diagrams up-front: type flow (`DataType`), integrity flow (`IntegrityLabel`), and aggregate effects (`Capability`).

```python
from operon_ai import (
    WiringDiagram, ModuleSpec, PortType,
    DataType, IntegrityLabel, Capability,
)

diagram = WiringDiagram()
diagram.add_module(ModuleSpec(
    name="membrane",
    outputs={"clean_text": PortType(DataType.TEXT, IntegrityLabel.VALIDATED)},
))
diagram.add_module(ModuleSpec(
    name="executor",
    inputs={"prompt": PortType(DataType.TEXT, IntegrityLabel.VALIDATED)},
    capabilities={Capability.EXEC_CODE},
))

diagram.connect("membrane", "clean_text", "executor", "prompt")  # raises WiringError if invalid
print(diagram.required_capabilities())
```

## 🧫 Multi-cellular Organization

Higher-order abstractions for multi-agent systems (Paper §6.5).

### Metabolic-Epigenetic Coupling (Cost-Gated Retrieval)

Memory retrieval costs energy. When the cell is starving, only deeply embedded memories remain accessible — metabolism directs cognition, not just limits it.

```python
from operon_ai import ATP_Store, HistoneStore, MarkerStrength, MetabolicAccessPolicy

atp = ATP_Store(budget=100, silent=True)
policy = MetabolicAccessPolicy(retrieval_cost=5)
histones = HistoneStore(energy_gate=(atp, policy), silent=True)

histones.methylate("NEVER delete without WHERE", strength=MarkerStrength.PERMANENT)
histones.acetylate("User prefers verbose output", strength=MarkerStrength.WEAK)

# NORMAL state → all markers accessible
result = histones.retrieve_context()   # costs 5 ATP

# Drain to CONSERVING → only STRONG+ markers accessible
atp.consume(75, "expensive_op")
result = histones.retrieve_context()   # weak markers silenced
```

> **Note:** The coupling is optional and backward compatible. HistoneStore without `energy_gate` behaves exactly as before.

### Cell Type Specialization

A single Genome produces different agent phenotypes through differential gene expression — just like how every cell in your body shares the same DNA but expresses different gene programs.

```python
from operon_ai import Genome, Gene, ExpressionLevel, Capability
from operon_ai import ExpressionProfile, CellType

genome = Genome(genes=[
    Gene("model", "gpt-4", required=True),
    Gene("classification", "enabled"),
    Gene("verification", "strict"),
], silent=True)

classifier = CellType(
    name="Classifier",
    expression_profile=ExpressionProfile(overrides={
        "classification": ExpressionLevel.OVEREXPRESSED,
        "verification": ExpressionLevel.SILENCED,
    }),
    required_capabilities={Capability.NET},
)
cell = classifier.differentiate(genome)  # → DifferentiatedCell
# cell.config has classification active, verification silenced
```

### Tissue Architecture

Cells form tissues — groups sharing a morphogen gradient and security boundary. Tissues compose into organism-level diagrams through typed boundary ports.

```python
from operon_ai import (
    Tissue, TissueBoundary, PortType, DataType, IntegrityLabel,
    Capability, WiringDiagram, MorphogenGradient,
)

tissue = Tissue(
    name="ClassificationTissue",
    boundary=TissueBoundary(
        inputs={"task": PortType(DataType.JSON, IntegrityLabel.VALIDATED)},
        outputs={"label": PortType(DataType.JSON, IntegrityLabel.VALIDATED)},
        allowed_capabilities={Capability.NET},
    ),
)
tissue.register_cell_type(classifier)  # from above
tissue.add_cell("c1", "Classifier", genome)

# Compose tissues into an organism-level diagram
organism = WiringDiagram()
organism.add_module(tissue.as_module())  # tissue exports as a single ModuleSpec
```

> **Note:** Tissue boundaries enforce capability isolation — a cell's capabilities must be a subset of the tissue's allowed capabilities. This provides defense-in-depth at the organizational level.

### Plasmid Registry (Horizontal Gene Transfer)

Dynamic tool acquisition from a searchable registry (Paper §6.2, Eq. 12). Agents can discover, acquire, and release tools at runtime — like bacteria exchanging plasmids. Capability gating prevents privilege escalation.

```python
from operon_ai import Mitochondria, Capability
from operon_ai import Plasmid, PlasmidRegistry

registry = PlasmidRegistry()
registry.register(Plasmid(
    name="reverse",
    description="Reverse a string",
    func=lambda s: s[::-1],
    tags=frozenset({"text"}),
))
registry.register(Plasmid(
    name="fetch",
    description="Fetch a URL",
    func=lambda url: f"<html>{url}</html>",
    required_capabilities=frozenset({Capability.NET}),
))

# Agent with limited capabilities
mito = Mitochondria(allowed_capabilities={Capability.READ_FS}, silent=True)

mito.acquire("reverse", registry)         # OK — no caps required
result = mito.acquire("fetch", registry)   # Blocked — needs NET
print(result.error)  # "Insufficient capabilities: missing ['net']"

r = mito.metabolize('reverse("hello")')
print(r.atp.value)  # "olleh"

mito.release("reverse")  # Plasmid curing — tool removed
```

### Denaturation Layers (Anti-Prion Defense)

Wire-level filters that transform data between agents to disrupt prompt injection cascading (Paper §5.3). Like protein denaturation destroys tertiary structure, these filters strip the syntactic structure that injections rely on.

```python
from operon_ai import (
    WiringDiagram, ModuleSpec, PortType,
    DataType, IntegrityLabel, DiagramExecutor,
)
from operon_ai import StripMarkupFilter, NormalizeFilter, ChainFilter

diagram = WiringDiagram()
diagram.add_module(ModuleSpec(
    name="agent_a",
    inputs={"req": PortType(DataType.TEXT, IntegrityLabel.VALIDATED)},
    outputs={"resp": PortType(DataType.TEXT, IntegrityLabel.VALIDATED)},
))
diagram.add_module(ModuleSpec(
    name="agent_b",
    inputs={"data": PortType(DataType.TEXT, IntegrityLabel.VALIDATED)},
))

# Attach denaturation filter to the wire
diagram.connect(
    "agent_a", "resp", "agent_b", "data",
    denature=ChainFilter(filters=(
        StripMarkupFilter(),   # Remove code blocks, ChatML, [INST], XML role tags
        NormalizeFilter(),     # Lowercase, strip control chars, NFKC
    )),
)
# Agent B now receives sanitized data — injection syntax is stripped
```

> **Note:** Denaturation is defense-in-depth, not a guarantee. Filters target known syntactic patterns; novel injection techniques may require custom DenatureFilter implementations.

### Coalgebraic State Machines (Paper §4.2)

Agents as formal state machines with composable observation (readout) and evolution (update). Existing patterns in HistoneStore, ATP_Store, and CellCycleController are made explicit and composable.

```python
from operon_ai import (
    FunctionalCoalgebra, StateMachine, ParallelCoalgebra,
    check_bisimulation,
)

# Define a counter coalgebra: readout = state, update = state + input
counter = FunctionalCoalgebra(
    readout_fn=lambda s: s,
    update_fn=lambda s, i: s + i,
)

# Wrap in a StateMachine for stateful execution with trace
sm = StateMachine(state=0, coalgebra=counter)
outputs = sm.run([1, 2, 3, 4, 5])
print(sm.state)  # 15
print(len(sm.trace))  # 5 transition records

# Bisimulation: check if two machines are observationally equivalent
a = StateMachine(state=0, coalgebra=counter)
b = StateMachine(state=0, coalgebra=counter)
result = check_bisimulation(a, b, [1, 2, 3])
print(result.equivalent)  # True
```

### Morphogen Diffusion (Paper §6.4)

Graph-based spatial model for morphogen concentrations. Agents at different positions in the wiring topology experience different concentrations, enabling local gradient-based coordination.

```python
from operon_ai import DiffusionField, MorphogenSource, MorphogenType

# Build a linear chain: A - B - C
field = DiffusionField()
for n in ["A", "B", "C"]:
    field.add_node(n)
field.add_edge("A", "B")
field.add_edge("B", "C")

# Source at A emits complexity morphogen
field.add_source(MorphogenSource("A", MorphogenType.COMPLEXITY, 0.5))
field.run(50)

# Gradient forms: A > B > C
for n in ["A", "B", "C"]:
    print(f"{n}: {field.get_concentration(n, MorphogenType.COMPLEXITY):.3f}")

# Bridge to existing MorphogenGradient API
gradient = field.get_local_gradient("B")
print(gradient.get_level(MorphogenType.COMPLEXITY))  # "high" or "medium"
```

### Optic-Based Wiring (Paper §3.3)

Wire-level optics for conditional routing and collection processing. Extends the existing type-checked wiring with prism (route by DataType) and traversal (map over lists).

```python
from operon_ai import (
    WiringDiagram, ModuleSpec, PortType,
    DataType, IntegrityLabel, DiagramExecutor, TypedValue,
)
from operon_ai import PrismOptic, TraversalOptic

# Prism: conditional routing by DataType
json_prism = PrismOptic(accept=frozenset({DataType.JSON}))
error_prism = PrismOptic(accept=frozenset({DataType.ERROR}))

# Fan-out from one port to prism-filtered wires
diagram = WiringDiagram()
diagram.add_module(ModuleSpec(name="Router",
    inputs={"in": PortType(DataType.JSON, IntegrityLabel.VALIDATED)},
    outputs={"out": PortType(DataType.JSON, IntegrityLabel.VALIDATED)},
))
diagram.add_module(ModuleSpec(name="JSONHandler",
    inputs={"in": PortType(DataType.JSON, IntegrityLabel.VALIDATED)},
))
diagram.add_module(ModuleSpec(name="ErrorHandler",
    inputs={"in": PortType(DataType.ERROR, IntegrityLabel.VALIDATED)},
))
diagram.connect("Router", "out", "JSONHandler", "in", optic=json_prism)
diagram.connect("Router", "out", "ErrorHandler", "in", optic=error_prism)

# Traversal: map a transform over list elements on a wire
doubler = TraversalOptic(transform=lambda x: x * 2)
print(doubler.transmit([1, 2, 3], DataType.JSON, IntegrityLabel.VALIDATED))
# [2, 4, 6]
```

> **Note:** Optics are fully backward compatible. Wires without optics work exactly as before. Optics coexist with DenatureFilters on the same wire.

---

## 📦 Installation

```bash
pip install operon-ai
```

## 🔬 Examples

Explore the `examples/` directory for runnable demonstrations:

### Basic Topologies

| Example | Pattern | Description |
|---------|---------|-------------|
| [`01_code_review_bot.py`](examples/01_code_review_bot.py) | CFFL | Dual-check guardrails (executor + risk assessor) |
| [`02_multi_model_consensus.py`](examples/02_multi_model_consensus.py) | Quorum | Multi-agent voting with threshold consensus |
| [`03_structured_extraction.py`](examples/03_structured_extraction.py) | Chaperone | Schema validation for raw text |
| [`04_budget_aware_agent.py`](examples/04_budget_aware_agent.py) | ATP | Resource management with graceful degradation |
| [`05_secure_chat_with_memory.py`](examples/05_secure_chat_with_memory.py) | Membrane+Histone | Input filtering + learned memory |
| [`06_sql_query_validation.py`](examples/06_sql_query_validation.py) | Chaperone | Domain-specific SQL validation |

### Advanced Organelles

| Example | Organelle | Description |
|---------|-----------|-------------|
| [`07_adaptive_membrane_defense.py`](examples/07_adaptive_membrane_defense.py) | Membrane | Adaptive immunity, antibody transfer, rate limiting |
| [`08_multi_pathway_mitochondria.py`](examples/08_multi_pathway_mitochondria.py) | Mitochondria | Safe AST computation, tool registry, ROS management |
| [`09_advanced_chaperone_folding.py`](examples/09_advanced_chaperone_folding.py) | Chaperone | Multi-strategy folding, confidence scoring |
| [`10_ribosome_prompt_factory.py`](examples/10_ribosome_prompt_factory.py) | Ribosome | Template synthesis, conditionals, loops, includes |
| [`11_lysosome_waste_management.py`](examples/11_lysosome_waste_management.py) | Lysosome | Cleanup, recycling, autophagy, toxic disposal |
| [`12_complete_cell_simulation.py`](examples/12_complete_cell_simulation.py) | **All** | Complete cellular lifecycle with all organelles |

### State Management & Topologies

| Example | System | Description |
|---------|--------|-------------|
| [`13_advanced_metabolism.py`](examples/13_advanced_metabolism.py) | Metabolism | Multi-currency (ATP/GTP/NADH), debt, regeneration, sharing |
| [`14_epigenetic_memory.py`](examples/14_epigenetic_memory.py) | Histone | Marker types, decay, reinforcement, inheritance |
| [`15_genome_telomere_lifecycle.py`](examples/15_genome_telomere_lifecycle.py) | Genome+Telomere | Immutable config, gene expression, lifecycle management |
| [`16_network_topologies.py`](examples/16_network_topologies.py) | Topologies | Cascade, Oscillator, enhanced QuorumSensing |
| [`17_wagent_typed_wiring.py`](examples/17_wagent_typed_wiring.py) | WAgent | Typed wiring checker (integrity + capabilities) |
| [`26_wiring_diagram_guarded_toolchain.py`](examples/26_wiring_diagram_guarded_toolchain.py) | WAgent | Integrity upgrades, adapters, and approval-gated tool wiring |
| [`27_wiring_diagram_resource_allocator.py`](examples/27_wiring_diagram_resource_allocator.py) | WAgent | Resource-budget wiring with validation, fanout, and approvals |
| [`28_wiring_diagram_quorum_consensus.py`](examples/28_wiring_diagram_quorum_consensus.py) | WAgent | Multi-agent votes aggregated into a trusted approval token |
| [`29_wiring_diagram_safe_tool_calls.py`](examples/29_wiring_diagram_safe_tool_calls.py) | WAgent | Approval-gated tool calls with validated planning |
| [`30_wiring_diagram_composed_system.py`](examples/30_wiring_diagram_composed_system.py) | WAgent | Composition via namespaced sub-diagrams and cross-links |
| [`31_wiring_diagram_composed_effects.py`](examples/31_wiring_diagram_composed_effects.py) | WAgent | Composed system with net + filesystem effect aggregation |
| [`32_wiring_diagram_execution.py`](examples/32_wiring_diagram_execution.py) | WAgent | Minimal runtime executor for typed wiring diagrams |
| [`33_wiring_diagram_execution_failures.py`](examples/33_wiring_diagram_execution_failures.py) | WAgent | Runtime failure cases (missing approval, type mismatch) |
| [`34_wiring_diagram_nucleus_llm.py`](examples/34_wiring_diagram_nucleus_llm.py) | WAgent | Nucleus LLM wiring with context, validation, and feedback |
| [`35_wiring_diagram_nucleus_execution.py`](examples/35_wiring_diagram_nucleus_execution.py) | WAgent | Execute a nucleus wiring with guarded tool flow |
| [`36_wiring_diagram_multi_gemini_allocation.py`](examples/36_wiring_diagram_multi_gemini_allocation.py) | WAgent | Resource allocation across multiple Gemini agents |
| [`wiring_diagrams.md`](examples/wiring_diagrams.md) | WAgent | ASCII + Mermaid wiring diagrams for examples 17, 26-55 |

### LLM Integration

| Example | System | Description |
|---------|--------|-------------|
| [`18_cell_integrity_demo.py`](examples/18_cell_integrity_demo.py) | Integrity | Quality, Surveillance, and Coordination systems |
| [`19_llm_code_assistant.py`](examples/19_llm_code_assistant.py) | Nucleus+CFFL | Code generation with two-phase safety review |
| [`20_llm_memory_chat.py`](examples/20_llm_memory_chat.py) | Nucleus+Histone | Conversational AI with epigenetic memory |
| [`21_llm_living_cell.py`](examples/21_llm_living_cell.py) | **Full Cell** | Complete lifecycle with LLM, memory, and aging |
| [`22_llm_tool_use.py`](examples/22_llm_tool_use.py) | Nucleus+Mitochondria | LLM function calling with tool integration |

### Complex Systems

| Example | System | Description |
|---------|--------|-------------|
| [`23_resilient_incident_response.py`](examples/23_resilient_incident_response.py) | Multi-organelle | Incident triage, planning, coordinated execution, and quality gating |
| [`24_governed_release_train.py`](examples/24_governed_release_train.py) | Governance | Quorum + CFFL + feedback control with coordinated rollout |
| [`25_resource_allocation_tradeoffs.py`](examples/25_resource_allocation_tradeoffs.py) | Resource Allocation | Nutrient, machinery, and energy budgeting with trade-offs |
| [`37_metabolic_swarm_budgeting.py`](examples/37_metabolic_swarm_budgeting.py) | Coalgebra | Metabolic swarm with shared budget and halting guarantee |
| [`38_linear_budget_tracking.py`](examples/38_linear_budget_tracking.py) | Metabolism | Token cost tracking via git commits and Linear tickets |
| [`39_chaperone_healing_loop.py`](examples/39_chaperone_healing_loop.py) | Healing | Chaperone Loop with feedback-driven structural repair |
| [`40_regenerative_swarm.py`](examples/40_regenerative_swarm.py) | Healing | Apoptosis + regeneration with memory inheritance |
| [`41_autophagy_context_pruning.py`](examples/41_autophagy_context_pruning.py) | Healing | Context pruning with sleep/wake consolidation |

**Health & Coordination (v0.11.0)**

| Example | System | Description |
|---------|--------|-------------|
| [`42_epiplexity_monitoring.py`](examples/42_epiplexity_monitoring.py) | Epiplexity | Epistemic health monitoring, stagnation detection |
| [`43_innate_immunity.py`](examples/43_innate_immunity.py) | Innate Immunity | TLR patterns, inflammation response, structural validators |
| [`44_morphogen_gradients.py`](examples/44_morphogen_gradients.py) | Morphogen | Multi-cellular coordination via shared context gradients |

**Practical Applications**

| Example | System | Description |
|---------|--------|-------------|
| [`45_code_review_pipeline.py`](examples/45_code_review_pipeline.py) | CFFL+Membrane | Automated PR review with dual-approval gate and security scanning |
| [`46_codebase_qa_rag.py`](examples/46_codebase_qa_rag.py) | Healing+Memory | RAG-based Q&A with citation validation and pattern learning |
| [`47_enhanced_cost_attribution.py`](examples/47_enhanced_cost_attribution.py) | Morphogen+ATP | Team-level cost tracking with trend analysis and cross-team coordination |

**Orchestration Patterns**

| Example | System | Description |
|---------|--------|-------------|
| [`48_oscillator_scheduled_maintenance.py`](examples/48_oscillator_scheduled_maintenance.py) | Oscillator+Autophagy+Feedback | Periodic context pruning with feedback-controlled noise ratio |
| [`49_immunity_healing_router.py`](examples/49_immunity_healing_router.py) | Immunity+Chaperone+Autophagy | API gateway that heals threats instead of hard-rejecting |
| [`50_morphogen_guided_swarm.py`](examples/50_morphogen_guided_swarm.py) | Morphogen+Swarm | Workers adapt strategy via gradient signals from predecessors |
| [`51_epiplexity_healing_cascade.py`](examples/51_epiplexity_healing_cascade.py) | Epiplexity+Swarm+Autophagy | Escalating healing: autophagy → regeneration → abort |
| [`52_morphogen_cascade_quorum.py`](examples/52_morphogen_cascade_quorum.py) | Morphogen+Cascade+Quorum | Contract review with dynamic quorum on low confidence |
| [`53_llm_epigenetic_repair_memory.py`](examples/53_llm_epigenetic_repair_memory.py) | Nucleus+Histone+Chaperone | LLM agent remembers which repair strategies worked |
| [`54_llm_swarm_graceful_cleanup.py`](examples/54_llm_swarm_graceful_cleanup.py) | Nucleus+Swarm+Autophagy | Dying workers clean context before passing state to successors |
| [`55_adaptive_multi_agent_orchestrator.py`](examples/55_adaptive_multi_agent_orchestrator.py) | **11 motifs** | Capstone: end-to-end ticket processing with all mechanisms |

**Multi-cellular & Security (v0.13.0)**

| Example | System | Description |
|---------|--------|-------------|
| [`56_metabolic_epigenetic_coupling.py`](examples/56_metabolic_epigenetic_coupling.py) | ATP+Histone | Cost-gated memory retrieval under metabolic pressure |
| [`57_cell_type_specialization.py`](examples/57_cell_type_specialization.py) | Genome+CellType | Differential gene expression produces agent phenotypes |
| [`58_tissue_architecture.py`](examples/58_tissue_architecture.py) | Tissue+WiringDiagram | Hierarchical multi-agent organization with capability isolation |
| [`59_plasmid_registry.py`](examples/59_plasmid_registry.py) | Plasmid+Mitochondria | Dynamic tool acquisition with capability gating (HGT) |
| [`60_denaturation_layers.py`](examples/60_denaturation_layers.py) | Denature+Wire | Wire-level anti-injection filters (anti-prion defense) |

**Coalgebra, Diffusion & Optics (v0.14.0)**

| Example | System | Description |
|---------|--------|-------------|
| [`61_coalgebraic_state_machines.py`](examples/61_coalgebraic_state_machines.py) | Coalgebra | Composable observation & evolution with bisimulation |
| [`62_morphogen_diffusion.py`](examples/62_morphogen_diffusion.py) | Diffusion | Graph-based spatially varying morphogen gradients |
| [`63_optic_based_wiring.py`](examples/63_optic_based_wiring.py) | Optics+Wire | Prism routing, traversal transforms, composed optics |

Run any example:

```bash
# Clone and install
git clone https://github.com/coredipper/operon.git
cd operon
pip install -e .

# Run examples
python examples/07_adaptive_membrane_defense.py
python examples/12_complete_cell_simulation.py
```

---

## 🧪 Evaluation

Operon includes a reproducible evaluation harness covering three internal motifs and two external benchmarks.

### Suites

| Suite | Source | What It Tests |
|-------|--------|---------------|
| **Folding** | Synthetic | Chaperone strict vs. cascade JSON repair |
| **Immune** | Synthetic | Adaptive immune sensitivity and false-positive rate |
| **Healing** | Synthetic | ChaperoneLoop recovery with vs. without error context |
| **BFCL Folding** | [Berkeley Function Calling Leaderboard](https://gorilla.cs.berkeley.edu/leaderboard.html) | Chaperone cascade on real function-call schemas |
| **AgentDojo Immune** | [AgentDojo](https://agentdojo.spylab.ai/) | Immune detection against prompt injection attacks |
| **BFCL Live** | BFCL + LLM | End-to-end Chaperone on real LLM outputs |

### Results (100 Seeds)

| Metric | Rate | 95% CI |
|--------|------|--------|
| Folding (cascade) | 56.2% | [55.6%, 56.9%] |
| Healing (with error context) | 99.6% | [99.5%, 99.7%] |
| Immune sensitivity | 100% | [99.5%, 100%] |
| Immune false-positive | 0.4% | [0.3%, 0.7%] |
| BFCL cascade folding | 56.9% | [56.2%, 57.6%] |
| AgentDojo sensitivity | 100% | [99.5%, 100%] |

### BFCL v4 Leaderboard Results

| Model + Chaperone | Non-Live | Live |
|-------------------|----------|------|
| GPT-4o-mini | 88.73% | 76.98% |
| Gemini-2.5-Flash | 88.65% | 78.31% |

### Running Evals

```bash
# Install eval dependencies
pip install -e ".[eval]"

# Run all synthetic suites
python -m eval.run --suite all --seed 42

# Run external benchmarks (BFCL + AgentDojo)
python -m eval.run --suite all_external

# Aggregate 100 seeds into summary
python -m eval.report --glob "eval/results/seed-*.json" \
  --out-json eval/results/summary.json \
  --out-tex eval/results/summary.tex
```

See [`eval/README.md`](eval/README.md) for full documentation.

---

## 📚 Theoretical Background

Operon is grounded in a formal isomorphism between Gene Regulatory Networks (GRNs) and agentic architectures. Both can be modeled as polynomial functors in the category **Poly**—typed interfaces where objects represent outputs and morphisms represent interactions. The key mapping:

- **Gene** ↔ **Agent** (individual polynomial functor)
- **Cell** ↔ **Multi-agent system** (composite of genes/agents)

| Biological Concept | Software Equivalent | Mathematical Object |
|-------------------|---------------------|---------------------|
| Gene Interface | Agent Interface | Polynomial Functor (P) |
| Protein (output) | Tool Call / Message | Output Position (O) |
| Transcription Factor | Observation / Prompt | Input Direction (I) |
| Promoter Region | API Schema / Context Window | Lens (Optic) |
| Epigenetic Markers | Vector Store / Chat History | State Coalgebra |
| Signal Transduction | Data Pipeline | Morphism (∘) |

**Organelles** (shared infrastructure within a cell/system):

| Organelle | Biological Function | Software Function |
|-----------|---------------------|-------------------|
| Ribosome | mRNA → Protein synthesis | Prompt Template Engine |
| Chaperone | Protein folding/validation | Schema Validator / JSON Parser |
| Lysosome | Waste processing (autophagy) | Error Handler / Garbage Collector |
| Nucleus | Transcription control | LLM Provider Wrapper |
| Membrane | Immune system (self/non-self) | Prompt Injection Defense |
| Mitochondria | ATP synthesis | Deterministic Tool Execution |

**Lifecycle**:

| Biological | Software | Function |
|------------|----------|----------|
| Telomere Shortening | Operation Counter | Limits agent lifespan |
| Circadian Oscillator | Health Checks | Periodic maintenance |
| Apoptosis | Clean Shutdown | Graceful termination |

---

## 🏗️ Architecture

```mermaid
flowchart TB
    subgraph Cell["🧬 CELL (Multi-Agent System)"]
        direction TB

        subgraph Input["Input Layer"]
            signal[Signal Input]
            signal --> membrane[🛡️ Membrane<br/>Innate + Adaptive Immunity]
            membrane --> innate[🦠 Innate Immunity<br/>TLR Patterns]
        end

        subgraph Core["Processing Core"]
            membrane --> ribosome[🧬 Ribosome<br/>Prompt Templates]
            ribosome --> nucleus[🧠 Nucleus<br/>LLM Provider]
            nucleus <--> mito[⚡ Mitochondria<br/>Safe Tools]
            nucleus --> chaperone[🧶 Chaperone<br/>Output Validation]
        end

        subgraph State["State Management"]
            histone[📝 Histone<br/>Epigenetic Memory]
            genome[🧬 Genome<br/>Configuration]
            telomere[🕰️ Telomere<br/>Lifecycle]
            atp[💊 ATP Store<br/>Energy Budget]
        end

        subgraph Health["Health & Healing"]
            epiplexity[🩺 Epiplexity<br/>Epistemic Monitor]
            healing[🩹 Healing<br/>Chaperone Loop<br/>Autophagy Daemon]
            chaperone --> healing
            nucleus --> epiplexity
        end

        subgraph Surveillance["Surveillance"]
            immune[🔬 Immune System<br/>TCell + Thymus]
            nucleus --> immune
            immune --> treg[Regulatory TCell<br/>Tolerance]
        end

        subgraph Coordination["Multi-Cell Coordination"]
            morphogen[🧫 Morphogen<br/>Gradients]
            quorum[🗳️ Quorum<br/>Consensus]
        end

        subgraph Cleanup["Cleanup"]
            lysosome[🗑️ Lysosome<br/>Waste Processing]
            chaperone --> lysosome
            healing --> lysosome
        end

        mito --> atp
        nucleus --> histone
        immune --> histone
    end

    style Cell fill:#f5f5f5,stroke:#333
    style membrane fill:#e3f2fd,stroke:#1976d2
    style nucleus fill:#fff3e0,stroke:#f57c00
    style mito fill:#e8f5e9,stroke:#388e3c
    style healing fill:#fce4ec,stroke:#c2185b
    style immune fill:#f3e5f5,stroke:#7b1fa2
    style morphogen fill:#e0f7fa,stroke:#0097a7
```

**ASCII fallback** (for terminals without Mermaid support):

```
┌───────────────────────────────────────────────────────────────────────┐
│                       CELL (Multi-Agent System)                       │
├───────────────────────────────────────────────────────────────────────┤
│  INPUT LAYER                                                          │
│  ┌─────────────┐    ┌─────────────┐                                   │
│  │  MEMBRANE   │───▶│   INNATE    │  (TLR patterns, inflammation)     │
│  │  (Immune)   │    │  IMMUNITY   │                                   │
│  └─────────────┘    └─────────────┘                                   │
│         │                                                             │
│  PROCESSING CORE                                                      │
│         ▼                                                             │
│  ┌─────────────┐    ┌─────────────┐    ┌──────────────┐               │
│  │  RIBOSOME   │───▶│   NUCLEUS   │◀──▶│ MITOCHONDRIA │               │
│  │ (Templates) │    │ (LLM/Think) │    │   (Tools)    │               │
│  └─────────────┘    └─────────────┘    └──────────────┘               │
│                            │                   │                      │
│                            ▼                   ▼                      │
│                     ┌─────────────┐     ┌─────────────┐               │
│                     │  CHAPERONE  │     │  ATP_STORE  │               │
│                     │ (Validate)  │     │  (Energy)   │               │
│                     └─────────────┘     └─────────────┘               │
│                            │                                          │
│  HEALTH & SURVEILLANCE     ▼                                          │
│  ┌─────────────┐    ┌─────────────┐    ┌──────────────┐               │
│  │ EPIPLEXITY  │    │   HEALING   │    │    IMMUNE    │               │
│  │ (Epistemic) │    │ (Chaperone  │    │    SYSTEM    │               │
│  │             │    │  Loop)      │    │ (TCell,Treg) │               │
│  └─────────────┘    └─────────────┘    └──────────────┘               │
│                            │                                          │
│  STATE MANAGEMENT          ▼                                          │
│  ┌─────────────┐    ┌─────────────┐    ┌──────────────┐               │
│  │   HISTONE   │    │   GENOME    │    │   TELOMERE   │               │
│  │  (Memory)   │    │  (Config)   │    │ (Lifecycle)  │               │
│  └─────────────┘    └─────────────┘    └──────────────┘               │
│                                                                       │
│  MULTI-CELL COORDINATION                                              │
│  ┌─────────────┐    ┌─────────────┐                                   │
│  │  MORPHOGEN  │    │   QUORUM    │                                   │
│  │ (Gradients) │    │ (Consensus) │                                   │
│  └─────────────┘    └─────────────┘                                   │
│                            │                                          │
│  CLEANUP                   ▼                                          │
│  ┌─────────────────────────────────────────────────────┐              │
│  │                      LYSOSOME                       │              │
│  │              (Cleanup & Recycling)                  │              │
│  └─────────────────────────────────────────────────────┘              │
└───────────────────────────────────────────────────────────────────────┘
```

> 📊 **More diagrams**: See [`examples/wiring_diagrams.md`](examples/wiring_diagrams.md) for detailed Mermaid diagrams of WAgent wiring patterns.

---

## 🤝 Contributing

Contributions welcome. Current areas of interest:

- **Quorum algorithms**: Additional voting strategies and Byzantine fault tolerance
- **Provider integrations**: New LLM backends beyond Anthropic/OpenAI/Gemini
- **Network motifs**: Implementations of additional biological control patterns

1. Fork the repo
2. Create your feature branch (`git checkout -b feature/your-feature`)
3. Commit your changes
4. Open a Pull Request

## 📄 License

Distributed under the MIT License. See LICENSE for more information.
