Deploy The Echo (MockLLM path): Gradio app + echo package

README.md

@@ -1,13 +1,21 @@
 ---
 title: The Echo
-emoji: 🌖
-colorFrom: pink
-colorTo: red
+emoji: 🌳
+colorFrom: yellow
+colorTo: gray
 sdk: gradio
 sdk_version: 6.16.0
-python_version: '3.13'
 app_file: app.py
 pinned: false
+short_description: an agentic tree of the lives you didn't live
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# The Echo
+
+An agentic tree of the lives you didn't live. One fork in a life grows a tree of
+alternate selves; each echo speaks back in a subtly altered version of your own
+voice.
+
+This Space currently runs on the offline **MockLLM** path — placeholder lives
+that exercise the full UX (plant a seed, grow branches, walk the tree). The real
+small-model generation is wired in separately.

app.py

@@ -0,0 +1,7 @@
+"""HF Spaces entrypoint. The real app lives in the `echo` package."""
+from echo.app import build_demo
+
+demo = build_demo()
+
+if __name__ == "__main__":
+    demo.launch()

echo/CLAUDE.md

@@ -0,0 +1,138 @@
+# CLAUDE.md
+
+Guidance for working on **The Echo** — an agentic tree of the lives you didn't live.
+
+## What this project is
+
+The Echo takes one fork in a person's life ("I left Brazil instead of staying")
+and grows a **tree of alternate selves**. Each node is a coherent alternate life;
+each branch is a dramatic turning point. The user navigates the tree, and each
+echo speaks back in a subtly altered version of their own voice.
+
+It is built for the **Thousand Token Wood** track of a small-model hackathon
+(all models ≤32B, Gradio + HF Spaces, demo video + social post). The award
+surface it targets: Thousand Token Wood (delight), Best Agent (true multi-agent +
+tools), Off-Brand (the living tree UI), Best Demo (voice + emotional reveal), and
+Tiny Titan (if a ≤4B model holds coherence).
+
+**This is an agentic inference system, not an RL project.** There is no training
+loop, no reward, no policy gradient. The "intelligence" is three coordinated
+agents using a frozen LLM zero-shot. Do not add RL unless explicitly asked.
+
+## The core idea that must never break
+
+The single hardest, most important property: **"the same you" stays recognizable
+across every branch.** A child life is always generated as a *causal consequence*
+of its parent's `WorldState` — never invented from scratch. Age math must add up,
+relationships and dependents must persist or change for a reason, carried losses
+must echo forward. The `Verifier` exists to enforce this. If a change would let
+branches drift into unrelated people, it is wrong.
+
+## Architecture (dependency order — leaves first)
+
+```
+core/world_state.py   data: WorldState, LifeFacts, EmotionalTone   (no deps)
+core/tree.py          LifeTree: branching graph + history           (-> world_state)
+llm/client.py         LLMClient; MockLLM (offline) + LocalLLM       (HF model)
+tools/research.py     world-grounding (real place/era detail)       (-> world_state)
+tools/voice.py        TTS; pitch shifts by emotional valence        (-> world_state)
+agents/base.py        thin Agent base                               (-> llm)
+agents/curator.py     grows child life from parent (causal)         (-> base, world_state)
+agents/screenwriter.py plans the next two dramatic forks            (-> base, world_state)
+agents/verifier.py    audits branch coherence; triggers regen       (-> base, world_state)
+core/orchestrator.py  conductor: curator→verifier loop, voice, plan (-> everything)
+smoke_test.py         full pipeline with mocks, no GPU              (-> everything)
+```
+
+When rewriting files, follow this same order: leaves before roots, so the
+project never sits in a broken state.
+
+## The agentic loop (one user choice → one new node)
+
+1. **Curator** reads parent + full branch history (+ research grounding) → child `WorldState`
+2. **Verifier** audits child vs branch; orchestrator regenerates up to `max_regen` times
+3. **Voice tool** synthesizes the child's spoken line (pitch nudged by valence)
+4. **Screenwriter** plans the child's next two forks
+5. node added to `LifeTree`
+
+The orchestrator is UI-agnostic. The (future) Gradio app calls `seed()` once,
+then `choose_fork(node_id, i)` per click, and renders `graph()`.
+
+## Hard rules
+
+- **Keep `MockLLM` and the mock tools working at all times.** `python -m
+  echo.smoke_test` must pass with zero ML dependencies installed. This is the
+  project's correctness gate. Every change is validated here first.
+- **Lazy-import heavy deps.** `torch`, `transformers`, `peft`, `bitsandbytes`,
+  TTS backends are imported *inside* the methods that need them, never at module
+  top level. Importing any `echo` module must stay cheap and dependency-free.
+- **Never import `orchestrator` from `core/__init__.py`.** It pulls in agents +
+  tools, and `tools/voice.py` imports `core.world_state` — importing the
+  orchestrator at package load creates a circular import. Import it explicitly:
+  `from echo.core.orchestrator import Orchestrator`.
+- **Agents stay single-purpose and thin.** One responsibility each. This is what
+  makes the ≤4B (Tiny Titan) path viable — small focused calls instead of one
+  giant generation. Don't merge agents.
+- **All model access goes through `LLMClient`.** Agents never touch
+  `transformers` directly. Swapping 14B ↔ 3B must remain a one-line config
+  change.
+- **Favor concrete, mundane, specific detail over vague profundity** in any
+  prompt or generated content. Specificity is what makes a life feel real;
+  vagueness is the main failure mode.
+
+## Quantization & LoRA (planned, on the `LocalLLM`)
+
+These are the next technical additions and belong only in `llm/client.py`:
+
+- **4-bit quantization** via `BitsAndBytesConfig` (bitsandbytes): `load_in_4bit`,
+  NF4, double quantization. This is what lets a 14B fit on a free-tier GPU and
+  makes the honest small-model fit real.
+- **Optional LoRA adapters** for light *supervised* fine-tuning of an agent (e.g.
+  teaching the Curator format + tone). This is SFT, not RL. Per-agent adapters
+  are loadable but training is out of scope unless asked.
+
+The `MockLLM` must remain untouched by either — it stays the offline test path.
+
+## Tiny Titan experiment
+
+The orchestrator tracks `GrowthStats.regen_rate` (regenerations / nodes grown).
+This is the metric that decides 14B vs ≤4B: run the same pipeline on both and
+compare how often each model breaks branch coherence. A ≤4B model with a low
+regeneration rate wins the honest-fit argument and the Tiny Titan award.
+
+## Tone & safety of the experience
+
+Dramatic forks touch real emotion (loss, regret). The framing must be **wonder,
+not regret** — "look how many vibrant lives lived inside one choice," never "look
+what you lost." The closing artifact (`final_map_summary`) deliberately ends with
+gentleness ("none of them are more real than the one you're in"). Keep that
+spirit in any new generated content. This is a toy that should leave people
+lighter, not heavier.
+
+## How to verify any change
+
+```bash
+python -m echo.smoke_test     # must print "ALL STAGES PASSED ✓"
+```
+
+If that passes, the agentic loop, tree, tools, and serialization are all intact.
+Only after that should you test with a real model.
+
+## Commands
+
+```bash
+# offline correctness gate (no GPU, no ML deps)
+python -m echo.smoke_test
+
+# real model run (requires: pip install -r requirements.txt)
+python -c "
+from echo.llm.client import LocalLLM, LLMConfig
+from echo.tools.research import MockResearch
+from echo.tools.voice import MockVoice
+from echo.core.orchestrator import Orchestrator
+llm = LocalLLM(LLMConfig(model_name='Qwen/Qwen2.5-3B-Instruct')); llm.load()
+orch = Orchestrator(llm, MockResearch(), MockVoice())
+root = orch.seed('I stayed instead of moving abroad', base_age=24)
+print(root.facts.constraints_text())
+"
+```

echo/README.md

@@ -0,0 +1,75 @@
+# 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).

echo/__init__.py

@@ -0,0 +1,3 @@
+"""The Echo: an agentic tree of the lives you didn't live."""
+__version__ = "0.1.0"
+    

echo/agents/__init__.py

@@ -0,0 +1,5 @@
+"""The three specialized agents."""
+from .base import Agent
+from .curator import Curator
+from .screenwriter import Screenwriter
+from .verifier import Verifier, VerdictResult

echo/agents/base.py

@@ -0,0 +1,65 @@
+"""
+echo/agents/base.py
+-------------------
+Common base for the three specialized agents (Curator, Screenwriter,
+Verifier). Each agent owns a system prompt and a single responsibility; the
+orchestrator composes them into the branch-generation loop.
+
+Keeping agents thin and single-purpose is what makes the ≤4B (Tiny Titan)
+experiment viable: each call is a small, focused task rather than one giant
+do-everything generation.
+"""
+
+from __future__ import annotations
+
+from abc import ABC
+
+from ..llm.client import LLMClient
+
+
+# Shared prompt fragments. Split so the auditor (Verifier) and the fork-planner
+# (Screenwriter) only carry what actually applies to them — the voice register
+# has no surface to land on outside the Curator's summary/voice_line, and giving
+# it to other agents would just burn tokens (this targets Thousand Token Wood).
+#
+# Composition:
+#   Curator      = HOUSE_STYLE_WORLD + HOUSE_STYLE_VOICE + responsibility + gold
+#   Screenwriter = HOUSE_STYLE_WORLD + responsibility
+#   Verifier     = standalone (no house style)
+HOUSE_STYLE_WORLD = (
+    "WORLD RULES (everything you write belongs to ONE specific, continuous "
+    "person):\n"
+    "- Favor concrete, mundane, specific detail over vague profundity. Name the "
+    "street, the object, the small habit. Specificity makes a life real; "
+    "vagueness is the failure mode.\n"
+    "- Never write 'unknown', a blank field, or a placeholder. Commit to a "
+    "specific city and a specific occupation.\n"
+    "- Stay true to this life's established facts — age, relationships, "
+    "dependents, carried losses. Anything new must be a plausible consequence "
+    "of what came before, never a different person.\n"
+    "- Write in English.\n"
+)
+
+HOUSE_STYLE_VOICE = (
+    "VOICE (for the summary and the spoken voice_line):\n"
+    "- Second person for the summary (\"You are 41, in Porto...\"). First person "
+    "for the voice_line — this self speaking to the one who never lived this "
+    "life.\n"
+    "- The register is raw and ambivalent: pride and loss can share one breath, "
+    "unresolved. Do not tie it in a bow.\n"
+    "- But every voice_line ends on a thread of light — one small thing still "
+    "alive. Never pure despair.\n"
+    "- Earn feeling through a concrete detail, not an abstract emotion word.\n"
+)
+
+
+class Agent(ABC):
+    #: subclasses set a SYSTEM prompt; the word "curator"/"screenwriter"/
+    #: "verifier" in it also drives MockLLM routing.
+    SYSTEM: str = ""
+
+    def __init__(self, llm: LLMClient):
+        self.llm = llm
+
+    def _complete_json(self, user: str) -> dict:
+        return self.llm.complete_json(self.SYSTEM, user)

echo/agents/curator.py

@@ -0,0 +1,129 @@
+"""
+echo/agents/curator.py
+----------------------
+The Curator builds a child WorldState as a *causal consequence* of its parent.
+
+It is the agent most responsible for the illusion that it's "the same you"
+across branches: it receives the full branch narrative (root -> parent) plus
+the chosen fork, and must produce a life that could plausibly have grown from
+that history. It never invents from scratch.
+
+Optionally consumes grounding facts from the research tool (real-world detail
+for the chosen location/era) to kill vagueness.
+"""
+
+from __future__ import annotations
+
+from typing import Optional
+
+from .base import Agent, HOUSE_STYLE_WORLD, HOUSE_STYLE_VOICE
+from ..core.world_state import WorldState, LifeFacts, EmotionalTone
+
+
+_CURATOR_GOLD = (
+    "GOLD EXAMPLE — match this texture and JSON shape, never reuse its content:\n"
+    "{\n"
+    '  "age": 41,\n'
+    '  "location": "Porto, Portugal",\n'
+    '  "occupation": "night-shift baker",\n'
+    '  "relationships": ["divorced from Inês, still text on Sundays"],\n'
+    '  "dependents": ["a son, Tomás, 9"],\n'
+    '  "scars": ["the Lisbon bakery you lost to the bank"],\n'
+    '  "triumphs": ["Tomás learned to swim this July"],\n'
+    '  "possessions": ["a flour-dusted radio stuck on one station"],\n'
+    '  "valence": -0.1,\n'
+    '  "dominant_feeling": "tired tenderness",\n'
+    '  "voice_hint": "low, even, a little hoarse before dawn",\n'
+    '  "summary": "You are 41, in Porto, baking through the night so Tomás '
+    'wakes to warm bread.",\n'
+    '  "voice_line": "I lost the Lisbon shop and I lost her, but the boy ate '
+    'warm bread this morning and never knew a thing."\n'
+    "}\n\n"
+    "The voice_line earns its weight from one concrete image. Never write the "
+    "abstract version:\n"
+    '  ✗ "It was hard, but it became a journey of self-discovery worth taking."\n'
+    '  ✓ "...the boy ate warm bread this morning and never knew a thing."'
+)
+
+
+class Curator(Agent):
+    SYSTEM = (
+        HOUSE_STYLE_WORLD + "\n" + HOUSE_STYLE_VOICE + "\n"
+        "You are the Curator. You grow ONE human life forward across alternate "
+        "timelines. Given the branch history and the choice that now diverges "
+        "this life, write the NEXT state as a believable causal consequence of "
+        "the parent. The new age must equal the parent's age plus the years "
+        "that pass. Respond ONLY as JSON with keys: age, location, occupation, "
+        "relationships, dependents, scars, triumphs, possessions, valence, "
+        "dominant_feeling, voice_hint, summary, voice_line.\n\n"
+        + _CURATOR_GOLD
+    )
+
+    def grow(self, parent: WorldState, branch_narrative: str,
+             chosen_fork: str, years: int,
+             grounding: Optional[str] = None) -> WorldState:
+        user = (
+            f"BRANCH HISTORY (must stay consistent with all of this):\n"
+            f"{branch_narrative}\n\n"
+            f"PARENT FACTS: {parent.facts.constraints_text()}\n"
+            f"PARENT EMOTION: {parent.tone.dominant_feeling} "
+            f"(valence {parent.tone.valence})\n\n"
+            f"THE CHOICE THAT NOW DIVERGES THIS LIFE: {chosen_fork}\n"
+            f"YEARS THAT PASS: {years}\n"
+        )
+        if grounding:
+            user += f"\nREAL-WORLD GROUNDING (use to add authentic detail):\n{grounding}\n"
+        if parent.facts.location == "unknown" or parent.facts.occupation == "unknown":
+            # Origin node: nothing is established yet. The model must INVENT a
+            # concrete grounding rather than inherit the "unknown" placeholder.
+            user += (
+                "\nThis is the ORIGIN of the life — no location or occupation is "
+                "fixed yet. Establish a SPECIFIC city and occupation that fit the "
+                "diverging choice; do not write 'unknown'."
+            )
+        user += (
+            "\nWrite the resulting life. The new age must equal parent age + "
+            f"{years}. Make one big dramatic turn land — a triumph or a wound."
+        )
+
+        data = self._complete_json(user)
+        return self._assemble(parent, chosen_fork, years, data)
+
+    # ------------------------------------------------------------- assembly
+    def _assemble(self, parent: WorldState, fork: str, years: int,
+                  data: dict) -> WorldState:
+        """Build a WorldState from model JSON, with safe fallbacks."""
+        facts = LifeFacts(
+            age=int(data.get("age", parent.facts.age + years)),
+            location=str(data.get("location", parent.facts.location)),
+            occupation=str(data.get("occupation", parent.facts.occupation)),
+            relationships=_as_list(data.get("relationships")),
+            dependents=_as_list(data.get("dependents")),
+            scars=_as_list(data.get("scars")) or list(parent.facts.scars),
+            triumphs=_as_list(data.get("triumphs")),
+            possessions=_as_list(data.get("possessions")),
+        )
+        tone = EmotionalTone(
+            valence=float(data.get("valence", 0.0)),
+            dominant_feeling=str(data.get("dominant_feeling", "uncertain")),
+            voice_hint=str(data.get("voice_hint", "")),
+        )
+        return WorldState(
+            node_id=WorldState.new_id(),
+            parent_id=parent.node_id,
+            depth=parent.depth + 1,
+            divergence=fork,
+            years_elapsed=years,
+            facts=facts,
+            tone=tone,
+            summary=str(data.get("summary", "")),
+            voice_line=str(data.get("voice_line", "")),
+        )
+
+
+def _as_list(v) -> list[str]:
+    if v is None:
+        return []
+    if isinstance(v, list):
+        return [str(x) for x in v]
+    return [str(v)]

echo/agents/screenwriter.py

@@ -0,0 +1,47 @@
+"""
+echo/agents/screenwriter.py
+---------------------------
+The Screenwriter looks at a life and PLANS its next two dramatic forks. This is
+the agentic narrative drive: the system proposes the decisive turning points
+that fit *this specific* life, rather than asking the user an open question.
+
+It reads the current WorldState (and branch history) and returns two mutually
+distinct, high-stakes choices — the kind that would genuinely reshape a life.
+"""
+
+from __future__ import annotations
+
+from .base import Agent, HOUSE_STYLE_WORLD
+from ..core.world_state import WorldState
+
+
+class Screenwriter(Agent):
+    SYSTEM = (
+        HOUSE_STYLE_WORLD + "\n"
+        "You are the Screenwriter. You design the next TWO forks this specific "
+        "life could face — decisive, concrete turning points, true to who this "
+        "life has made them. The two must pull in genuinely different "
+        "directions (stay vs leave, hold vs risk, reach toward vs turn away) — "
+        "never two flavors of the same move. Each fork is a short, vivid action "
+        "this person could actually take, grounded in their real situation, not "
+        "an abstract theme:\n"
+        '  ✗ "embrace change"\n'
+        '  ✓ "sell the flat and move to her city"\n'
+        'Respond ONLY as JSON: {"forks": ["choice A", "choice B"]}.'
+    )
+
+    def plan(self, state: WorldState, branch_narrative: str) -> list[str]:
+        user = (
+            f"CURRENT LIFE: {state.facts.constraints_text()}\n"
+            f"EMOTION: {state.tone.dominant_feeling} (valence {state.tone.valence})\n"
+            f"BRANCH HISTORY:\n{branch_narrative}\n\n"
+            "Propose the next two decisive forks for THIS life."
+        )
+        data = self._complete_json(user)
+        forks = data.get("forks", [])
+        forks = [str(f) for f in forks][:2]
+        # fallback so the loop never stalls
+        while len(forks) < 2:
+            forks.append("let everything change" if not forks
+                         else "hold on to what you have")
+        return forks

echo/agents/verifier.py

@@ -0,0 +1,84 @@
+"""
+echo/agents/verifier.py
+-----------------------
+The Verifier checks a freshly-grown child WorldState against its branch history
+for contradictions (impossible age math, relationships that vanished, a dead
+parent reappearing, location/era inconsistencies). If it fails, the orchestrator
+regenerates.
+
+This cheap consistency loop is the polish that turns "plausible chatbot output"
+into "how is it keeping all of this straight?" — the technical aha. It also
+provides the metric for the Tiny Titan experiment: regeneration rate by model
+size.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from .base import Agent
+from ..core.world_state import WorldState
+
+
+@dataclass
+class VerdictResult:
+    consistent: bool
+    reason: str = ""
+
+
+class Verifier(Agent):
+    SYSTEM = (
+        "You are the Verifier. You audit a newly written life-state against the "
+        "established history of its branch and decide if it is consistent. Flag "
+        "a contradiction only when something genuinely breaks: age that doesn't "
+        "match the years elapsed, a relationship or dependent that appears or "
+        "vanishes with no cause, a carried loss silently erased, or a "
+        "location/era that's impossible. Do NOT flag a change that the choice "
+        "taken and the passing years plausibly explain — growth, moves, new "
+        "love, and healing are allowed. Be strict about broken facts, generous "
+        "about "
+        "plausible change. Respond ONLY as JSON: "
+        '{"consistent": true/false, "reason": "<short; name the specific '
+        'contradiction>"}.'
+    )
+
+    def check(self, child: WorldState, parent: WorldState,
+              branch_narrative: str) -> VerdictResult:
+        # 1) cheap deterministic checks first (no LLM needed)
+        hard = self._hard_checks(child, parent)
+        if hard is not None:
+            return hard
+
+        # 2) soft semantic check via LLM
+        user = (
+            f"BRANCH HISTORY:\n{branch_narrative}\n\n"
+            f"PARENT: {parent.facts.constraints_text()}\n"
+            f"NEW STATE: {child.facts.constraints_text()}\n"
+            f"CHOICE TAKEN: {child.divergence} (+{child.years_elapsed}y)\n\n"
+            "Is the NEW STATE consistent with everything above?"
+        )
+        data = self._complete_json(user)
+        return VerdictResult(
+            consistent=bool(data.get("consistent", True)),
+            reason=str(data.get("reason", "")),
+        )
+
+    def _hard_checks(self, child: WorldState, parent: WorldState):
+        """Deterministic guards that never need a model."""
+        expected_age = parent.facts.age + child.years_elapsed
+        if abs(child.facts.age - expected_age) > 1:
+            return VerdictResult(False,
+                                 f"age {child.facts.age} != expected {expected_age}")
+        if child.years_elapsed < 0:
+            return VerdictResult(False, "negative time")
+        # a carried scar from the parent should not silently disappear if it was
+        # a permanent loss (heuristic: parent dependents shouldn't vanish)
+        for dep in parent.facts.dependents:
+            # children don't un-exist; allow them to grow but not disappear
+            base = dep.split(",")[0].strip().lower()
+            if base and not any(base in d.lower() for d in child.facts.dependents):
+                # not necessarily fatal (estrangement), so soft-flag only if
+                # the time elapsed is small
+                if child.years_elapsed <= 2:
+                    return VerdictResult(False, f"dependent '{base}' vanished")
+        return None

echo/app.py

@@ -0,0 +1,248 @@
+"""
+echo/app.py
+-----------
+The Gradio front-end: plant a seed, watch the tree of alternate lives grow, and
+walk it. UI-only — it drives the orchestrator and renders LifeTree.to_graph().
+
+First cut runs entirely on MockLLM + mock tools, so it launches offline with no
+GPU and no ML deps. Swapping in the real model later is a one-line change in
+`_new_orchestrator()`.
+
+Run it:
+    python -m echo.app
+
+Design notes:
+* The tree visual is a read-only vis-network embedded via <iframe srcdoc>. We do
+  NOT try to route SVG clicks back into Python (fragile in Gradio); all
+  interaction is native components. Node selection is the dropdown.
+* gr.HTML strips <script>, so the vis-network document is wrapped in an iframe
+  srcdoc, which renders its own document (scripts included).
+* gr.State holds the whole Orchestrator. Fine with MockLLM (tiny). When the real
+  LocalLLM is plugged in (roadmap item 3), the loaded model must NOT live in
+  State — keep only the serialized LifeTree in State and hold the model in a
+  module-global. (Document that in CLAUDE.md when implementing item 3.)
+"""
+
+from __future__ import annotations
+
+import html as _html
+import json
+
+import gradio as gr
+
+# Import the orchestrator explicitly — never via core/__init__ (circular import).
+from .core.orchestrator import Orchestrator
+from .llm.client import MockLLM
+from .tools.research import MockResearch
+from .tools.voice import MockVoice
+
+
+_DEFAULT_SEED = "I stayed instead of moving abroad"
+_AUDIO_EXTS = (".wav", ".mp3", ".ogg", ".flac")
+
+
+def _new_orchestrator() -> Orchestrator:
+    """The one place that wires the engine. Swap MockLLM -> LocalLLM here."""
+    return Orchestrator(MockLLM(), MockResearch(), MockVoice())
+
+
+# --------------------------------------------------------------- tree renderer
+def _valence_color(v: float) -> str:
+    """Continuous gradient: cold slate (struggling) -> warm gold (flourishing)."""
+    v = max(-1.0, min(1.0, float(v)))
+    t = (v + 1.0) / 2.0
+    cold = (0x3A, 0x4A, 0x5A)
+    gold = (0xE8, 0xB8, 0x4B)
+    rgb = tuple(round(cold[i] + (gold[i] - cold[i]) * t) for i in range(3))
+    return "#%02X%02X%02X" % rgb
+
+
+def _render_tree_html(graph: dict, active_id: str) -> str:
+    """Build the vis-network document and wrap it in an iframe srcdoc."""
+    nodes = []
+    for n in graph["nodes"]:
+        is_active = n["id"] == active_id
+        node = {
+            "id": n["id"],
+            "label": n.get("label") or "…",
+            "title": (n.get("summary") or "")[:120],  # tooltip; capped for size
+            "color": {
+                "background": _valence_color(n["valence"]),
+                "border": "#F2D27A" if is_active else "#1c2530",
+            },
+            "borderWidth": 4 if is_active else 1,
+            "shadow": bool(is_active),
+            "font": {"color": "#e8e6df", "size": 13},
+        }
+        if n.get("has_voice"):
+            # a subtle dashed ring marks nodes that have a spoken line
+            node["shapeProperties"] = {"borderDashes": [4, 3]}
+        nodes.append(node)
+
+    edges = [
+        {
+            "from": e["from"],
+            "to": e["to"],
+            "label": (e.get("label") or "")[:35],  # fork text; capped for size
+            "arrows": "to",
+            "font": {"color": "#9aa7b0", "size": 10, "strokeWidth": 0},
+            "color": {"color": "#44525e"},
+        }
+        for e in graph["edges"]
+    ]
+
+    doc = (
+        "<!DOCTYPE html><html><head>"
+        '<script src="https://unpkg.com/vis-network/standalone/umd/'
+        'vis-network.min.js"></script>'
+        "<style>html,body{margin:0;height:100%;background:#11151a;}"
+        "#net{width:100%;height:100%;}</style></head>"
+        '<body><div id="net"></div><script>'
+        "const nodes=new vis.DataSet(" + json.dumps(nodes) + ");"
+        "const edges=new vis.DataSet(" + json.dumps(edges) + ");"
+        "new vis.Network(document.getElementById('net'),{nodes,edges},{"
+        "layout:{hierarchical:{direction:'UD',sortMethod:'directed',"
+        "levelSeparation:95,nodeSpacing:150}},"
+        "physics:false,interaction:{hover:true,dragNodes:false,zoomView:true},"
+        "nodes:{shape:'dot',size:16}});"
+        "</script></body></html>"
+    )
+    srcdoc = _html.escape(doc, quote=True)
+    return (
+        f'<iframe srcdoc="{srcdoc}" '
+        'style="width:100%;height:520px;border:0;border-radius:12px;'
+        'background:#11151a;"></iframe>'
+    )
+
+
+_EMPTY_TREE = (
+    "<div style='height:520px;display:flex;align-items:center;"
+    "justify-content:center;background:#11151a;border-radius:12px;"
+    "color:#6b7680;font-family:sans-serif;'>Plante a árvore para começar.</div>"
+)
+
+
+# ------------------------------------------------------------------ rendering
+def _render(orch: Orchestrator, active_id: str):
+    """Compute every panel + tree output for a given active node (7 outputs)."""
+    tree = orch.tree
+    node = tree.nodes[active_id]
+
+    html = _render_tree_html(orch.graph(), active_id)
+
+    # dropdown: depth · occupation · dominant_feeling (read from node, not graph)
+    choices = [
+        (f"{n.depth} · {n.facts.occupation} · {n.tone.dominant_feeling}", n.node_id)
+        for n in sorted(tree.nodes.values(), key=lambda x: (x.depth, x.node_id))
+    ]
+
+    summary = f"### {node.facts.constraints_text()}\n\n{node.summary}"
+    if node.voice_line:
+        summary += f"\n\n> *“{node.voice_line}”*"
+
+    forks = node.pending_forks
+    fa = (gr.update(value=forks[0], visible=True) if len(forks) > 0
+          else gr.update(visible=False))
+    fb = (gr.update(value=forks[1], visible=True) if len(forks) > 1
+          else gr.update(visible=False))
+
+    path = node.voice_audio_path
+    audio_val = path if (path and path.lower().endswith(_AUDIO_EXTS)) else None
+
+    branch = "```\n" + tree.branch_narrative(active_id) + "\n```"
+
+    return (
+        gr.update(value=html),
+        gr.update(choices=choices, value=active_id),
+        gr.update(value=summary),
+        gr.update(value=audio_val),
+        fa,
+        fb,
+        gr.update(value=branch),
+    )
+
+
+_BLANK = (gr.update(),) * 7
+
+
+# -------------------------------------------------------------------- handlers
+def plant(seed: str, base_age):
+    orch = _new_orchestrator()
+    root = orch.seed((seed or "").strip() or _DEFAULT_SEED, base_age=int(base_age or 24))
+    return (orch, root.node_id, *_render(orch, root.node_id))
+
+
+def select_node(orch, selected_id):
+    if orch is None or not selected_id:
+        return (selected_id, *_BLANK)
+    return (selected_id, *_render(orch, selected_id))
+
+
+def choose(orch, active_id, i: int):
+    if orch is None or not active_id:
+        return (orch, active_id, *_BLANK)
+    node = orch.tree.nodes.get(active_id)
+    if node is None or i >= len(node.pending_forks):
+        return (orch, active_id, *_BLANK)
+    child = orch.choose_fork(active_id, i)
+    return (orch, child.node_id, *_render(orch, child.node_id))
+
+
+def show_final(orch):
+    if orch is None:
+        return gr.update(value="*Plante a árvore primeiro.*")
+    return gr.update(value=orch.final_map_summary())
+
+
+# ------------------------------------------------------------------ blocks/app
+def build_demo() -> gr.Blocks:
+    with gr.Blocks(title="The Echo") as demo:
+        gr.Markdown("# The Echo\n*the lives you didn't live*")
+        orch_state = gr.State()
+        active_state = gr.State()
+
+        with gr.Row():
+            with gr.Column(scale=3):
+                tree_html = gr.HTML(_EMPTY_TREE)
+            with gr.Column(scale=2):
+                seed_in = gr.Textbox(label="A bifurcação", value=_DEFAULT_SEED,
+                                     lines=2)
+                age_in = gr.Number(label="Idade base", value=24, precision=0)
+                plant_btn = gr.Button("Plantar a árvore", variant="primary")
+                node_dd = gr.Dropdown(label="Você está aqui", choices=[],
+                                      interactive=True)
+                summary_md = gr.Markdown()
+                audio = gr.Audio(label="A voz deste eco", interactive=False)
+                with gr.Row():
+                    fork_a_btn = gr.Button("…", visible=False)
+                    fork_b_btn = gr.Button("…", visible=False)
+                branch_md = gr.Markdown()
+
+        with gr.Accordion("O mapa final", open=False):
+            final_btn = gr.Button("Ver o mapa final")
+            final_md = gr.Markdown()
+
+        common = [tree_html, node_dd, summary_md, audio,
+                  fork_a_btn, fork_b_btn, branch_md]
+
+        plant_btn.click(plant, [seed_in, age_in],
+                        [orch_state, active_state, *common])
+        node_dd.change(select_node, [orch_state, node_dd],
+                       [active_state, *common])
+        fork_a_btn.click(lambda o, a: choose(o, a, 0),
+                         [orch_state, active_state],
+                         [orch_state, active_state, *common])
+        fork_b_btn.click(lambda o, a: choose(o, a, 1),
+                         [orch_state, active_state],
+                         [orch_state, active_state, *common])
+        final_btn.click(show_final, [orch_state], [final_md])
+
+    return demo
+
+
+def main() -> None:
+    build_demo().launch(theme=gr.themes.Base())
+
+
+if __name__ == "__main__":
+    main()

echo/core/__init__.py

@@ -0,0 +1,9 @@
+"""Core: world state, tree, and the agentic orchestrator.
+
+Note: world_state and tree are safe leaf modules. Orchestrator pulls in agents
+and tools, so it is NOT imported at package load to avoid a circular import
+(tools.voice -> core.world_state). Import it explicitly:
+    from echo.core.orchestrator import Orchestrator
+"""
+from .world_state import WorldState, LifeFacts, EmotionalTone, root_state
+from .tree import LifeTree

echo/core/orchestrator.py

@@ -0,0 +1,145 @@
+"""
+echo/core/orchestrator.py
+-------------------------
+The conductor. Wires Curator + Screenwriter + Verifier + tools into the loop
+that grows the tree of alternate lives.
+
+Branch-growth loop (one user choice -> one new node):
+    1. Curator reads parent + branch history (+ research grounding) -> child
+    2. Verifier audits child vs branch -> regenerate up to N times if needed
+    3. Voice tool speaks the child's line
+    4. Screenwriter plans the child's next two forks
+    5. node added to the tree
+
+The orchestrator is UI-agnostic: the Gradio app calls seed() once, then
+choose_fork() each time the user clicks a branch. Everything it returns is
+plain data the front-end renders.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Optional
+
+from .world_state import WorldState, root_state
+from .tree import LifeTree
+from ..agents.curator import Curator
+from ..agents.screenwriter import Screenwriter
+from ..agents.verifier import Verifier
+from ..tools.research import ResearchTool
+from ..tools.voice import VoiceTool
+from ..llm.client import LLMClient
+
+
+@dataclass
+class GrowthStats:
+    """Telemetry — powers the Tiny Titan experiment (regeneration rate)."""
+    nodes_grown: int = 0
+    regenerations: int = 0
+
+    @property
+    def regen_rate(self) -> float:
+        denom = self.nodes_grown + self.regenerations
+        return self.regenerations / denom if denom else 0.0
+
+
+class Orchestrator:
+    def __init__(self, llm: LLMClient, research: ResearchTool, voice: VoiceTool,
+                 out_dir: str = "echo_out", max_regen: int = 2,
+                 base_year: int = 2025):
+        self.curator = Curator(llm)
+        self.screenwriter = Screenwriter(llm)
+        self.verifier = Verifier(llm)
+        self.research = research
+        self.voice = voice
+        self.out_dir = out_dir
+        self.max_regen = max_regen
+        self.base_year = base_year
+        self.tree: Optional[LifeTree] = None
+        self.stats = GrowthStats()
+
+    # ------------------------------------------------------------------ seed
+    def seed(self, seed_choice: str, base_age: int = 30) -> WorldState:
+        """Plant the tree: create the root life and its first two forks."""
+        self.tree = LifeTree(seed_choice=seed_choice)
+        root = root_state(seed_choice, base_age)
+
+        # The root itself is curated from the seed (depth 0, 0 years elapsed).
+        grounding = self.research.ground(root.facts.location, self.base_year)
+        curated = self.curator.grow(
+            parent=root,
+            branch_narrative=f"Origin: {seed_choice}",
+            chosen_fork=seed_choice,
+            years=0,
+            grounding=grounding,
+        )
+        curated.parent_id = None
+        curated.depth = 0
+        curated.divergence = seed_choice
+        self._voice(curated)
+        curated.pending_forks = self.screenwriter.plan(
+            curated, self.tree.branch_narrative(curated.node_id)
+            if curated.node_id in self.tree.nodes else f"Origin: {seed_choice}"
+        )
+        self.tree.add(curated)
+        # plan forks again now that it's in the tree (branch narrative valid)
+        curated.pending_forks = self.screenwriter.plan(
+            curated, self.tree.branch_narrative(curated.node_id))
+        self.stats.nodes_grown += 1
+        return curated
+
+    # ----------------------------------------------------------- grow branch
+    def choose_fork(self, parent_id: str, fork_index: int,
+                    years: int = 5) -> WorldState:
+        """User picks one of a node's pending forks -> grow the child node."""
+        assert self.tree is not None, "call seed() first"
+        parent = self.tree.nodes[parent_id]
+        fork = parent.pending_forks[fork_index]
+        narrative = self.tree.branch_narrative(parent_id)
+
+        child = self._grow_verified(parent, narrative, fork, years)
+        self._voice(child)
+        child.pending_forks = self.screenwriter.plan(
+            child, self.tree.branch_narrative(parent_id) + f"\n-> {fork}")
+        self.tree.add(child)
+        self.stats.nodes_grown += 1
+        return child
+
+    # ----------------------------------------------------- internal helpers
+    def _grow_verified(self, parent: WorldState, narrative: str,
+                       fork: str, years: int) -> WorldState:
+        """Curator + Verifier loop with bounded regeneration."""
+        location_year = self.base_year + (parent.depth + 1) * years
+        grounding = self.research.ground(parent.facts.location, location_year)
+
+        child = self.curator.grow(parent, narrative, fork, years, grounding)
+        for _ in range(self.max_regen):
+            verdict = self.verifier.check(child, parent, narrative)
+            if verdict.consistent:
+                break
+            self.stats.regenerations += 1
+            # regenerate with the contradiction noted in the grounding hint
+            child = self.curator.grow(
+                parent, narrative, fork, years,
+                grounding=(grounding or "") +
+                f"\nFIX: previous attempt was inconsistent ({verdict.reason}).")
+        return child
+
+    def _voice(self, state: WorldState) -> None:
+        if state.voice_line:
+            state.voice_audio_path = self.voice.speak(state, self.out_dir)
+
+    # ----------------------------------------------------------------- views
+    def graph(self) -> dict:
+        return self.tree.to_graph() if self.tree else {"nodes": [], "edges": []}
+
+    def final_map_summary(self) -> str:
+        """The closing artifact: a gentle celebration of the lives explored."""
+        if not self.tree:
+            return ""
+        n = self.tree.size
+        flourishing = sum(1 for x in self.tree.nodes.values()
+                          if x.tone.is_flourishing)
+        return (f"You explored {n} lives that all lived inside one choice. "
+                f"{flourishing} of them were flourishing. "
+                f"None of them are more real than the one you're in.")

echo/core/tree.py

@@ -0,0 +1,86 @@
+"""
+echo/core/tree.py
+-----------------
+The branching tree of alternate lives. Holds every WorldState node and the
+parent/child links the UI renders (gold for flourishing, dark for struggling).
+
+Pure data structure + traversal helpers. The orchestrator mutates it; the
+Gradio front-end reads it to draw the D3/vis-network graph.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Optional
+
+from .world_state import WorldState
+
+
+@dataclass
+class LifeTree:
+    seed_choice: str
+    nodes: dict[str, WorldState] = field(default_factory=dict)
+    root_id: Optional[str] = None
+
+    # ---------------------------------------------------------------- build
+    def add(self, state: WorldState) -> None:
+        self.nodes[state.node_id] = state
+        if state.parent_id is None:
+            self.root_id = state.node_id
+
+    def children(self, node_id: str) -> list[WorldState]:
+        return [n for n in self.nodes.values() if n.parent_id == node_id]
+
+    def path_to_root(self, node_id: str) -> list[WorldState]:
+        """Ancestor chain from root -> node (inclusive). The branch's history."""
+        chain: list[WorldState] = []
+        cur = self.nodes.get(node_id)
+        while cur is not None:
+            chain.append(cur)
+            cur = self.nodes.get(cur.parent_id) if cur.parent_id else None
+        return list(reversed(chain))
+
+    def branch_narrative(self, node_id: str) -> str:
+        """Human-readable history of a branch, fed to the Curator as context."""
+        chain = self.path_to_root(node_id)
+        lines = []
+        for n in chain:
+            if n.depth == 0:
+                lines.append(f"Origin: {n.divergence}")
+            else:
+                lines.append(
+                    f"+{n.years_elapsed}y -> {n.divergence} "
+                    f"(now: {n.facts.constraints_text()})"
+                )
+        return "\n".join(lines)
+
+    # --------------------------------------------------------------- export
+    def to_graph(self) -> dict:
+        """Serialize to nodes/edges for the front-end visualization."""
+        graph_nodes = []
+        graph_edges = []
+        for n in self.nodes.values():
+            graph_nodes.append({
+                "id": n.node_id,
+                "label": n.facts.occupation or "…",
+                "summary": n.summary,
+                "valence": n.tone.valence,
+                "flourishing": n.tone.is_flourishing,
+                "depth": n.depth,
+                "has_voice": n.voice_audio_path is not None,
+            })
+            if n.parent_id:
+                graph_edges.append({
+                    "from": n.parent_id, "to": n.node_id,
+                    "label": n.divergence[:40],
+                })
+        return {"nodes": graph_nodes, "edges": graph_edges,
+                "root": self.root_id, "seed": self.seed_choice}
+
+    @property
+    def size(self) -> int:
+        return len(self.nodes)
+
+    @property
+    def max_depth(self) -> int:
+        return max((n.depth for n in self.nodes.values()), default=0)

echo/core/world_state.py

@@ -0,0 +1,103 @@
+"""
+echo/core/world_state.py
+------------------------
+The persistent, structured memory of a single alternate life (one node in the
+tree). This is what makes "the same you" recognizable across branches: every
+new branch is generated as a *causal consequence* of its parent's WorldState,
+not invented from scratch.
+
+Pure data. No LLM, no I/O. The Curator agent reads a parent WorldState and
+writes a child; the Verifier checks a child against its parent using these
+fields.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field, asdict
+from typing import Optional
+import uuid
+
+
+@dataclass
+class LifeFacts:
+    """The concrete, checkable facts about this version of the person."""
+    age: int
+    location: str                      # city / country right now
+    occupation: str
+    relationships: list[str] = field(default_factory=list)  # e.g. "married to Sofia"
+    dependents: list[str] = field(default_factory=list)     # e.g. "daughter, 4"
+    scars: list[str] = field(default_factory=list)          # losses / regrets carried
+    triumphs: list[str] = field(default_factory=list)       # what went right
+    possessions: list[str] = field(default_factory=list)    # grounding mundane detail
+
+    def constraints_text(self) -> str:
+        """A compact statement of facts the next branch must NOT contradict."""
+        parts = [f"age {self.age}", f"in {self.location}", f"works as {self.occupation}"]
+        if self.relationships:
+            parts.append("relationships: " + "; ".join(self.relationships))
+        if self.dependents:
+            parts.append("dependents: " + "; ".join(self.dependents))
+        if self.scars:
+            parts.append("carries: " + "; ".join(self.scars))
+        return " | ".join(parts)
+
+
+@dataclass
+class EmotionalTone:
+    """Where this life sits emotionally — drives the gold/dark visual + voice."""
+    valence: float          # -1.0 (devastated) .. +1.0 (thriving)
+    dominant_feeling: str    # e.g. "restless pride", "quiet grief"
+    voice_hint: str = ""     # guidance for TTS (pace, warmth, weariness)
+
+    @property
+    def is_flourishing(self) -> bool:
+        return self.valence >= 0.25
+
+    @property
+    def is_struggling(self) -> bool:
+        return self.valence <= -0.25
+
+
+@dataclass
+class WorldState:
+    """One node: a complete snapshot of an alternate life."""
+    node_id: str
+    parent_id: Optional[str]
+    depth: int
+    # the choice that CREATED this branch (what diverged from the parent)
+    divergence: str
+    # how many years passed since the parent node
+    years_elapsed: int
+    facts: LifeFacts
+    tone: EmotionalTone
+    # a short second-person summary the UI shows ("You are 34, in Lisbon...")
+    summary: str = ""
+    # the spoken message this echo leaves (filled by the voice tool)
+    voice_line: str = ""
+    voice_audio_path: Optional[str] = None
+    # the two planned next forks (filled by the Screenwriter)
+    pending_forks: list[str] = field(default_factory=list)
+
+    def to_dict(self) -> dict:
+        return asdict(self)
+
+    @staticmethod
+    def new_id() -> str:
+        return uuid.uuid4().hex[:8]
+
+
+def root_state(seed_choice: str, base_age: int = 30) -> WorldState:
+    """
+    Create the minimal root before the Curator fills it. The Curator will
+    overwrite facts/tone; this just establishes the tree's origin.
+    """
+    return WorldState(
+        node_id=WorldState.new_id(),
+        parent_id=None,
+        depth=0,
+        divergence=seed_choice,
+        years_elapsed=0,
+        facts=LifeFacts(age=base_age, location="unknown",
+                        occupation="unknown"),
+        tone=EmotionalTone(valence=0.0, dominant_feeling="uncertain"),
+    )

echo/llm/__init__.py

@@ -0,0 +1,2 @@
+"""LLM clients: deterministic mock + local HF model."""
+from .client import LLMClient, MockLLM, LocalLLM, LLMConfig

echo/llm/client.py

@@ -0,0 +1,171 @@
+"""
+echo/llm/client.py
+------------------
+A thin LLM interface with two implementations:
+
+* MockLLM   — deterministic, dependency-free. Lets the WHOLE agentic pipeline
+              run and be tested without a GPU. It returns plausible structured
+              JSON so the orchestrator, agents, tools, and tree all exercise
+              their real code paths.
+* LocalLLM  — wraps a HuggingFace causal model (Qwen2.5-3B/14B etc.). Lazy
+              imports torch/transformers so importing this module is cheap.
+
+Every agent talks to an LLMClient, never to transformers directly, so swapping
+the 14B vs the ≤4B model (the Tiny Titan experiment) is a one-line change.
+"""
+
+from __future__ import annotations
+
+import json
+import hashlib
+import random
+from abc import ABC, abstractmethod
+from dataclasses import dataclass
+
+
+@dataclass
+class LLMConfig:
+    model_name: str = "Qwen/Qwen2.5-3B-Instruct"
+    max_new_tokens: int = 512
+    temperature: float = 0.9
+    device: str = "cuda"
+    dtype: str = "bfloat16"
+
+
+class LLMClient(ABC):
+    @abstractmethod
+    def complete(self, system: str, user: str, json_mode: bool = False) -> str:
+        ...
+
+    def complete_json(self, system: str, user: str) -> dict:
+        """Complete and parse JSON, tolerant of fences / preamble."""
+        raw = self.complete(system, user, json_mode=True)
+        return _safe_json(raw)
+
+
+def _safe_json(text: str) -> dict:
+    try:
+        start = text.index("{")
+        end = text.rindex("}") + 1
+        return json.loads(text[start:end])
+    except (ValueError, json.JSONDecodeError):
+        return {}
+
+
+# --------------------------------------------------------------------- mock
+class MockLLM(LLMClient):
+    """
+    Deterministic stand-in. Produces structured life-fragments seeded by the
+    prompt hash, so the same branch always yields the same result (good for
+    tests) while different branches diverge.
+    """
+
+    _CITIES = ["Lisbon", "Tokyo", "Berlin", "São Paulo", "Reykjavik",
+               "Montreal", "Nairobi", "Hanoi"]
+    _JOBS = ["marine biologist", "bakery owner", "session guitarist",
+             "ER nurse", "patent lawyer", "documentary editor",
+             "high-school teacher", "startup founder"]
+    _FEELINGS = ["restless pride", "quiet grief", "stubborn hope",
+                 "weary contentment", "sharp loneliness", "fierce joy"]
+    _SCARS = ["a friendship that never healed", "the move that cost you a parent",
+              "a business that folded", "a love you let leave"]
+    _TRIUMPHS = ["a book finally finished", "a child who adores you",
+                 "a city that became home", "a fear you outgrew"]
+
+    def __init__(self, seed: int = 0):
+        self.seed = seed
+
+    def _rng(self, *parts: str) -> random.Random:
+        h = hashlib.sha256(("|".join(parts) + str(self.seed)).encode()).hexdigest()
+        return random.Random(int(h[:8], 16))
+
+    def complete(self, system: str, user: str, json_mode: bool = False) -> str:
+        r = self._rng(system[:40], user)
+        role = _detect_role(system)
+
+        if role == "curator":
+            payload = {
+                "age": r.randint(28, 52),
+                "location": r.choice(self._CITIES),
+                "occupation": r.choice(self._JOBS),
+                "relationships": [r.choice(["married", "newly single",
+                                            "in a long-distance love"])],
+                "dependents": r.choice([[], ["a daughter, 6"], ["a son, 11"]]),
+                "scars": [r.choice(self._SCARS)],
+                "triumphs": [r.choice(self._TRIUMPHS)],
+                "possessions": [r.choice(["a secondhand piano", "a dog named Argo",
+                                          "a balcony of herbs"])],
+                "valence": round(r.uniform(-0.8, 0.8), 2),
+                "dominant_feeling": r.choice(self._FEELINGS),
+                "voice_hint": r.choice(["slow and warm", "clipped, tired",
+                                        "bright, breathless"]),
+                "summary": "You wake in a life that turned on a single choice.",
+                "voice_line": "I still think about the version of us that stayed.",
+            }
+            return json.dumps(payload)
+
+        if role == "screenwriter":
+            forks = [
+                r.choice(["take the offer abroad", "stay for someone sick",
+                          "sell everything and travel", "say yes to the proposal"]),
+                r.choice(["walk away from it all", "bet the savings on a dream",
+                          "reconcile with an old enemy", "have the child"]),
+            ]
+            return json.dumps({"forks": forks})
+
+        if role == "verifier":
+            # mock: pass most of the time, occasionally flag
+            ok = r.random() > 0.15
+            return json.dumps({"consistent": ok,
+                               "reason": "" if ok else "age contradicts parent"})
+
+        return json.dumps({"text": "…"})
+
+
+def _detect_role(system: str) -> str:
+    s = system.lower()
+    if "curator" in s:
+        return "curator"
+    if "screenwriter" in s or "fork" in s:
+        return "screenwriter"
+    if "verifier" in s or "consisten" in s:
+        return "verifier"
+    return "generic"
+
+
+# -------------------------------------------------------------------- local
+class LocalLLM(LLMClient):
+    """Real model. Heavy deps imported lazily in .load()."""
+
+    def __init__(self, cfg: LLMConfig):
+        self.cfg = cfg
+        self.model = None
+        self.tokenizer = None
+
+    def load(self) -> None:
+        import torch
+        from transformers import AutoModelForCausalLM, AutoTokenizer
+        self.tokenizer = AutoTokenizer.from_pretrained(self.cfg.model_name)
+        self.model = AutoModelForCausalLM.from_pretrained(
+            self.cfg.model_name,
+            dtype=getattr(torch, self.cfg.dtype),
+            device_map=self.cfg.device,
+        )
+
+    def complete(self, system: str, user: str, json_mode: bool = False) -> str:
+        import torch
+        msgs = [{"role": "system", "content": system},
+                {"role": "user", "content": user}]
+        inputs = self.tokenizer.apply_chat_template(
+            msgs, add_generation_prompt=True, return_tensors="pt",
+            return_dict=True,
+        ).to(self.cfg.device)
+        prompt_len = inputs["input_ids"].shape[1]
+        with torch.no_grad():
+            out = self.model.generate(
+                **inputs, max_new_tokens=self.cfg.max_new_tokens,
+                do_sample=True, temperature=self.cfg.temperature,
+                pad_token_id=self.tokenizer.eos_token_id,
+            )
+        return self.tokenizer.decode(out[0, prompt_len:],
+                                     skip_special_tokens=True)

echo/requirements.txt

@@ -0,0 +1,10 @@
+# The core agentic pipeline + smoke_test run with ZERO of these (MockLLM +
+# mock tools). Install these only to plug in a real model / TTS / search.
+torch>=2.1
+transformers>=4.44
+accelerate>=0.30
+# Voice (pick one):
+# piper-tts
+# TTS            # coqui
+# Front-end:
+gradio>=4.0

echo/smoke_test.py

@@ -0,0 +1,76 @@
+"""
+echo/smoke_test.py
+------------------
+Runs the FULL agentic pipeline with MockLLM + mock tools — no GPU, no ML deps.
+Proves Curator/Screenwriter/Verifier/orchestrator/tree/tools all interoperate.
+
+Run:  python -m echo.smoke_test
+"""
+
+from __future__ import annotations
+
+from .llm.client import MockLLM
+from .tools.research import MockResearch
+from .tools.voice import MockVoice
+from .core.orchestrator import Orchestrator
+
+
+def main():
+    print("=" * 60)
+    print("The Echo — agentic pipeline smoke test (no ML deps)")
+    print("=" * 60)
+
+    llm = MockLLM(seed=7)
+    orch = Orchestrator(llm, MockResearch(), MockVoice(), out_dir="/tmp/echo_out")
+
+    # 1. seed the tree
+    seed = "I left Brazil to study abroad instead of staying"
+    root = orch.seed(seed, base_age=24)
+    print(f"\n[1] Seed: {seed!r}")
+    print(f"    Root life: {root.facts.constraints_text()}")
+    print(f"    Voice line: {root.voice_line!r}")
+    print(f"    Audio: {root.voice_audio_path}")
+    print(f"    Planned forks: {root.pending_forks}")
+
+    # 2. explore several branches (simulate the user navigating the tree)
+    print("\n[2] Exploring branches...")
+    cur = root
+    for step in range(4):
+        if not cur.pending_forks:
+            break
+        child = orch.choose_fork(cur.node_id, fork_index=step % 2, years=5)
+        print(f"    depth {child.depth}: chose {child.divergence!r}")
+        print(f"      -> {child.facts.constraints_text()}")
+        print(f"      tone: {child.tone.dominant_feeling} "
+              f"(valence {child.tone.valence}, "
+              f"{'gold' if child.tone.is_flourishing else 'dark'})")
+        cur = child
+
+    # 3. branch into a second direction from root
+    print("\n[3] Branching the OTHER way from root...")
+    other = orch.choose_fork(root.node_id, fork_index=1, years=8)
+    print(f"    depth {other.depth}: {other.divergence!r}")
+    print(f"      -> {other.facts.constraints_text()}")
+
+    # 4. tree + telemetry
+    g = orch.graph()
+    print(f"\n[4] Tree: {len(g['nodes'])} nodes, {len(g['edges'])} edges, "
+          f"max depth {orch.tree.max_depth}")
+    print(f"    Regeneration rate: {orch.stats.regen_rate:.0%} "
+          f"({orch.stats.regenerations} regens / "
+          f"{orch.stats.nodes_grown} grown)")
+
+    # 5. closing artifact
+    print(f"\n[5] Final map:\n    {orch.final_map_summary()}")
+
+    # 6. verify graph serialization (what Gradio will consume)
+    assert all("valence" in n for n in g["nodes"]), "graph nodes well-formed"
+    print(f"\n[6] Graph serialization OK — ready for the front-end.")
+
+    print("\n" + "=" * 60)
+    print("ALL STAGES PASSED ✓  (agentic loop verified)")
+    print("=" * 60)
+
+
+if __name__ == "__main__":
+    main()

echo/tools/__init__.py

@@ -0,0 +1,3 @@
+"""Tools: world-grounding research and voice synthesis."""
+from .research import ResearchTool, MockResearch, WebResearch
+from .voice import VoiceTool, MockVoice, PiperVoice

echo/tools/research.py

@@ -0,0 +1,60 @@
+"""
+echo/tools/research.py
+----------------------
+The world-grounding tool. Given a location + era, it returns real-world detail
+(cost of living, cultural moment, climate, notable events) that the Curator
+weaves in so an alternate life feels *anchored* rather than hallucinated. This
+grounding is the moment a judge thinks "wait, how does it know that?"
+
+ResearchTool is an interface with:
+* MockResearch — deterministic offline facts (for GPU-free testing),
+* WebResearch  — wraps a real search call (web_search / an API) at deploy time.
+"""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+
+
+class ResearchTool(ABC):
+    @abstractmethod
+    def ground(self, location: str, year: int, theme: str = "") -> str:
+        """Return a short bundle of grounding facts for location/year."""
+        ...
+
+
+class MockResearch(ResearchTool):
+    """Offline, deterministic grounding. Enough to exercise the pipeline."""
+
+    _NOTES = {
+        "Lisbon": "steep tiled streets, cheap pastéis, a tech-expat wave, the 28 tram",
+        "Tokyo": "rail punctual to the second, conbini at every corner, quiet density",
+        "Berlin": "late winters, techno after-hours, a city still half rebuilt",
+        "São Paulo": "endless gray sprawl, helicopters over traffic, rain that floods",
+        "Reykjavik": "winter dark by 3pm, geothermal pools, wool against the wind",
+        "Montreal": "bilingual signs, brutal Februaries, bagels better than New York",
+        "Nairobi": "matatus in bright livery, high-altitude light, a startup hum",
+        "Hanoi": "scooters like a river, broth at dawn, humidity that never lifts",
+    }
+
+    def ground(self, location: str, year: int, theme: str = "") -> str:
+        note = self._NOTES.get(location, "a place with its own particular light")
+        return f"{location} (~{year}): {note}."
+
+
+class WebResearch(ResearchTool):
+    """
+    Deploy-time grounding via a real search function injected at construction.
+    `search_fn(query) -> str` keeps this decoupled from any specific API and
+    lets the Gradio app pass in web_search or a cached corpus.
+    """
+
+    def __init__(self, search_fn):
+        self.search_fn = search_fn
+
+    def ground(self, location: str, year: int, theme: str = "") -> str:
+        q = f"{location} {year} daily life cost of living culture {theme}".strip()
+        try:
+            return str(self.search_fn(q))[:600]
+        except Exception:
+            return f"{location} (~{year})."

echo/tools/voice.py

@@ -0,0 +1,71 @@
+"""
+echo/tools/voice.py
+-------------------
+The voice tool gives each echo a spoken line — the same "you" at different ages
+and emotional registers. Hearing an alternate self speak is the visceral beat
+that text can't reach.
+
+VoiceTool interface:
+* MockVoice  — writes a tiny placeholder file path, no audio deps (testing).
+* PiperVoice — wraps a local TTS (Piper/Coqui) at deploy time, with the
+               WorldState's voice_hint shaping pace/warmth, and an optional
+               pitch shift so each branch's voice differs subtly.
+"""
+
+from __future__ import annotations
+
+import os
+from abc import ABC, abstractmethod
+
+from ..core.world_state import WorldState  # module import (not the core package) avoids a cycle
+
+
+class VoiceTool(ABC):
+    @abstractmethod
+    def speak(self, state: WorldState, out_dir: str) -> str:
+        """Synthesize state.voice_line; return the audio file path."""
+        ...
+
+
+class MockVoice(VoiceTool):
+    """Writes a placeholder .txt 'audio' marker so the pipeline runs offline."""
+
+    def speak(self, state: WorldState, out_dir: str) -> str:
+        os.makedirs(out_dir, exist_ok=True)
+        path = os.path.join(out_dir, f"voice_{state.node_id}.txt")
+        with open(path, "w") as f:
+            f.write(f"[VOICE hint={state.tone.voice_hint!r}] {state.voice_line}")
+        return path
+
+
+class PiperVoice(VoiceTool):
+    """
+    Deploy-time TTS. Lazy-imports the synth backend. A small pitch offset keyed
+    to the branch makes parallel selves sound like the same person tuned
+    differently (older/wearier/brighter).
+    """
+
+    def __init__(self, model_path: str, base_pitch: float = 1.0):
+        self.model_path = model_path
+        self.base_pitch = base_pitch
+
+    def speak(self, state: WorldState, out_dir: str) -> str:
+        os.makedirs(out_dir, exist_ok=True)
+        path = os.path.join(out_dir, f"voice_{state.node_id}.wav")
+        # pitch nudged by emotional valence: down when struggling, up when light
+        pitch = self.base_pitch + 0.04 * state.tone.valence
+        self._synthesize(state.voice_line, path, pitch, state.tone.voice_hint)
+        return path
+
+    def _synthesize(self, text: str, path: str, pitch: float, hint: str) -> None:
+        # Lazy import keeps the package importable without TTS installed.
+        try:
+            from piper import PiperVoice as _Piper  # type: ignore
+        except Exception:
+            # graceful fallback: write a marker instead of crashing the demo
+            with open(path + ".txt", "w") as f:
+                f.write(f"[TTS pitch={pitch:.2f} hint={hint!r}] {text}")
+            return
+        voice = _Piper.load(self.model_path)
+        with open(path, "wb") as f:
+            voice.synthesize(text, f, length_scale=1.0, sentence_silence=0.3)