# Operon Examples

This directory contains 70 runnable numbered examples demonstrating the
`operon_ai` library, progressing from basic concepts to complete
LLM-powered cell simulations.

## Recommended Starting Points

If you are evaluating Operon for practical value rather than formal structure,
start here:

- [`68_skill_organism_runtime.py`](68_skill_organism_runtime.py) if you want
  the clearest answer to “can this improve a real workflow?” It binds stages to
  fast vs deep models, preserves structure, and lets you add telemetry without
  rewriting the skill.
- [`67_pattern_first_api.py`](67_pattern_first_api.py) if you want the shortest
  path to topology advice, reviewer gates, and specialist swarms without
  touching the substrate directly.
- [`66_epistemic_topology.py`](66_epistemic_topology.py) if you want to inspect
  the structural analysis underneath those recommendations.

The older examples still matter, but these two are the fastest way to answer
the question most engineers actually care about: does this help me build a
better agent system?

For **temporal memory** scenarios — tracking facts that change over time and
reconstructing past belief states:
- [`69_bitemporal_memory.py`](69_bitemporal_memory.py) — core valid-time vs
  record-time divergence with corrections
- [`70_bitemporal_compliance_audit.py`](70_bitemporal_compliance_audit.py) —
  multi-fact compliance audit with belief-state reconstruction
- [`71_bitemporal_skill_organism.py`](71_bitemporal_skill_organism.py) —
  multi-stage organism with bi-temporal substrate for auditable shared facts
- [`72_pattern_repository.py`](72_pattern_repository.py) —
  register, retrieve, and score reusable collaboration pattern templates
- [`73_watcher_component.py`](73_watcher_component.py) —
  runtime monitoring with signal classification and retry/escalate/halt interventions
- [`74_adaptive_assembly.py`](74_adaptive_assembly.py) —
  task fingerprinting, template selection, automatic organism construction, and outcome recording
- [`75_experience_driven_watcher.py`](75_experience_driven_watcher.py) —
  watcher experience pool with intervention history driving future recommendations
- [`76_cognitive_modes.py`](76_cognitive_modes.py) —
  System A/B cognitive mode annotations with watcher mode balance reporting
- [`77_sleep_consolidation.py`](77_sleep_consolidation.py) —
  sleep consolidation cycle: replay, compress, counterfactual, histone promotion
- [`78_social_learning.py`](78_social_learning.py) —
  cross-organism template sharing with trust-weighted adoption (epistemic vigilance)
- [`79_curiosity_driven_exploration.py`](79_curiosity_driven_exploration.py) —
  curiosity signals triggering escalation on novel inputs

## Import Style Guide

All examples should follow this import pattern:

```python
# Standard library imports first
import sys
import time
from dataclasses import dataclass
from pathlib import Path

# Third-party imports
from pydantic import BaseModel

# Operon imports - grouped with parentheses for multiple imports
from operon_ai import (
    ATP_Store,
    Membrane,
    Signal,
    ThreatLevel,
)

# Operon submodule imports - separate import statements
from operon_ai.organelles.nucleus import Nucleus
from operon_ai.providers import MockProvider, ProviderConfig
```

## Example Progression

| Range | Focus | Key Concepts |
|-------|-------|--------------|
| 01-07 | Basics | Topologies, Budget, Membrane |
| 08-11 | Organelles | Mitochondria, Chaperone, Ribosome, Lysosome |
| 12-16 | Integration | Complete Cell, Metabolism, Memory, Lifecycle |
| 17-18 | Advanced | WAgent, Cell Integrity |
| 19-25 | LLM Integration | Real providers, Memory, Tools |
| 26-36 | Wiring Diagrams | Visual architecture, Composition |
| 37 | Formal Theory | Metabolic Coalgebra, budget-bounded halting conditions |
| 38-41 | Healing | Budget Tracking, Chaperone Loop, Regenerative Swarm, Autophagy |
| 42-44 | Health & Coordination | Epiplexity, Innate Immunity, Morphogen Gradients |
| 45-47 | Practical Applications | Code Review, Codebase Q&A, Cost Attribution |
| 48-55 | Orchestration | Multi-motif composition, LLM integration, capstone |
| 56-63 | Advanced Biology | Epigenetic coupling, Cell types, Tissue, Plasmids, Morphogens |
| 64-65 | Optimization & Providers | Diagram optimization, OpenAI-compatible servers |
| 66 | Epistemic Topology | Classification, error bounds, parallelism, recommendations |
| 67 | Pattern-First API | Reviewer gates, specialist swarms, topology advice |
| 68 | Skill Organisms | Provider-bound stages, fast/deep routing, attachable telemetry |
| 69-70 | Temporal Memory | Bi-temporal facts, belief-state reconstruction, compliance audit |

## Running Examples

```bash
# Basic examples (no LLM required)
python examples/01_code_review_bot.py

# Practical entry point (no LLM required)
python examples/67_pattern_first_api.py --test

# Provider-bound skill organism (mock providers by default)
python examples/68_skill_organism_runtime.py --test

# LLM examples (requires API key)
ANTHROPIC_API_KEY=sk-... python examples/19_llm_code_assistant.py --demo
```

## Naming Conventions

### Method Names

| Purpose | Preferred Name | Alternatives (avoid) |
|---------|---------------|---------------------|
| Energy consumption | `consume()` | metabolize, drain |
| Signal processing | `process()` | handle, execute |
| Template creation | `create_template()` | add_template, register_template |
| Output validation | `fold()` | validate, parse |

### Callback Names

Use `on_<event>` pattern:

- `on_state_change` - state transitions
- `on_error` - error events
- `on_complete` - completion events

### Variable Names

- `result` - operation outcomes
- `response` - LLM responses
- `signal` - input signals
- `vitals` - health status
