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)

python -m echo.smoke_test

Run with a real model

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).