echo/README.md

# The Echo — An Agentic Tree of the Lives You Didn't Live

You name one fork in your life. The Echo grows a *tree* of alternate selves —
each branch a dramatic turn, each node a coherent life that speaks to you in
your own voice. You navigate the branches; the AI lives them.

This is an **agentic** system, not a chatbot: three specialized agents plus
tools cooperate to keep "the same you" recognizable across every branch. That
coherence is the magic — and the technical "how is it doing that?".

## Why agentic (and why it helps the small-model fit)
Each agent does ONE small, focused job, so a ≤4B model can handle each step even
when it would fail doing everything at once. This is what makes the **Tiny
Titan** experiment realistic — and the orchestrator measures the regeneration
rate so you can compare 14B vs 3B with data.

## Module map (separated by function)

### `core/` — state & control (no ML deps)
| File | Function |
|------|----------|
| `world_state.py` | `WorldState`: the structured, checkable memory of one alternate life (facts, emotion, voice). |
| `tree.py` | `LifeTree`: the branching graph; branch-history reconstruction; export for the visual map. |
| `orchestrator.py` | The conductor: Curator→Verifier loop, voice, Screenwriter planning, telemetry. |

### `agents/` — the three minds
| File | Function |
|------|----------|
| `curator.py` | Grows a child life as a *causal consequence* of its parent. Keeps "the same you". |
| `screenwriter.py` | Plans the next two dramatic, life-specific forks. The narrative agency. |
| `verifier.py` | Audits each new branch for contradictions; triggers regeneration. The polish. |

### `tools/` — what the agents can do
| File | Function |
|------|----------|
| `research.py` | World-grounding (real location/era detail) so lives feel anchored, not vague. |
| `voice.py` | TTS: each echo speaks; pitch shifts subtly by emotional valence. |

### `llm/` — the brain, swappable
| File | Function |
|------|----------|
| `client.py` | `LLMClient` interface; `MockLLM` (offline/testing) + `LocalLLM` (Qwen 3B/14B). |

### Top level
| File | Function |
|------|----------|
| `smoke_test.py` | Runs the entire agentic loop with mocks — no GPU, no ML deps. |

## Verify (no GPU)
```bash
python -m echo.smoke_test
```

## Run with a real model
```python
from echo.llm.client import LocalLLM, LLMConfig
from echo.tools.research import MockResearch
from echo.tools.voice import PiperVoice
from echo.core.orchestrator import Orchestrator

llm = LocalLLM(LLMConfig(model_name="Qwen/Qwen2.5-3B-Instruct")); llm.load()
orch = Orchestrator(llm, MockResearch(), PiperVoice("voices/en.onnx"))
root = orch.seed("I stayed instead of moving abroad", base_age=24)
child = orch.choose_fork(root.node_id, fork_index=0, years=5)
```

## Gradio integration (next)
The app calls `orch.seed(...)` once, then `orch.choose_fork(node_id, i)` per
click, and renders `orch.graph()` as the gold/dark tree (D3 / vis-network).
Audio comes from each node's `voice_audio_path`. Nothing in core changes.

### Award surface
Thousand Token Wood (delight) · Best Agent (true multi-agent + tools) ·
Off-Brand (the living tree UI) · Best Demo (voice + emotional reveal) ·
Tiny Titan (if the ≤4B regeneration rate holds).