Thousand Token Wood: emergent small-model economy for Build Small Hackathon

.gitignore

@@ -0,0 +1,7 @@
+__pycache__/
+*.pyc
+.pytest_cache/
+.ruff_cache/
+.venv/
+*.egg-info/
+.DS_Store

DEPLOY.md

@@ -0,0 +1,53 @@
+# Deploying Thousand Token Wood (Lester's steps)
+
+The repo is deploy-ready. These steps need your Hugging Face + Modal accounts, so
+they're yours to run. Claude can help debug build logs after.
+
+## 0. Make sure the model endpoint is live
+```bash
+python -m modal deploy serve.py   # deploys the ttw-serve app (Qwen2.5-3B on vLLM)
+```
+Confirm it shows in https://modal.com/apps (app name `ttw-serve`).
+
+## 1. Create the Space
+Create a **Gradio** Space under the hackathon org:
+`https://huggingface.co/new-space` -> Owner = **build-small-hackathon**, SDK = Gradio.
+(Name it e.g. `thousand-token-wood`.)
+
+## 2. Give the Space Modal credentials (so the app can reach the endpoint)
+The Gradio app calls the Modal endpoint via the Modal client, which authenticates
+from env vars. In the Space: **Settings -> Variables and secrets -> New secret**, add:
+- `MODAL_TOKEN_ID`  = your Modal token id (from `~/.modal.toml`, or modal.com Settings -> API Tokens)
+- `MODAL_TOKEN_SECRET` = your Modal token secret
+
+(Do NOT set `TTW_DUMMY`; leaving it unset runs the real model.)
+
+## 3. Push the code to the Space
+```bash
+git init
+git remote add space https://huggingface.co/spaces/build-small-hackathon/thousand-token-wood
+git add app.py serve.py requirements.txt README.md ttw/ tests/ DEPLOY.md tasks/
+git commit -m "Thousand Token Wood: emergent small-model economy"
+git push space main
+```
+(Use an HF write token if prompted for a password.)
+
+## 4. Verify
+- The Space builds (watch the log), then loads.
+- Press **Step** a few times: trades appear, prices move, creatures' thoughts show.
+- If the page fails to load, the usual cause is missing/incorrect Modal secrets
+  (the app builds the Modal handle on load) -- recheck step 2.
+
+## 5. Submit (by June 15)
+- Record the demo video (suggested arc: Step to a calm market, then **Tempt Fate**
+  into "The Run on Oona's Hoard" and watch honey crash as the owl liquidates).
+- Write the Field Notes blog post (bonus badge).
+- Social post with the Space link.
+- Submit Space link + video + post on the hackathon page.
+
+## Bonus badges this already targets
+- 📡 Sharing is Caring: the reasoning traces are shown and shareable.
+- 📓 Field Notes: write-up.
+- 🐜 Tiny Titan: 3B model (≤4B).
+- 🤖 Best Agent: multi-agent economy.
+- 🟢 Modal Awards: served on Modal.

README.md

@@ -0,0 +1,56 @@
+---
+title: Thousand Token Wood
+emoji: 🍄
+colorFrom: green
+colorTo: yellow
+sdk: gradio
+sdk_version: 6.16.0
+app_file: app.py
+pinned: false
+license: mit
+---
+
+# 🍄 Thousand Token Wood
+
+A tiny **emergent economy** for the [Build Small Hackathon](https://huggingface.co/build-small-hackathon).
+Five woodland creatures, each driven by a small (**≤4B**) model, trade goods for
+pebbles, gossip, hoard, and panic. You poke the wood, and bubbles, crashes, and a
+widening wealth gap emerge on their own.
+
+## Why "small" is load-bearing
+A living economy needs *many* agents thinking *many* times. Frontier models are
+too slow and costly for that. A 3B model makes a real-time multi-agent simulation
+possible, and that is the whole point. The agents run on **Qwen2.5-3B-Instruct**,
+served with vLLM on **Modal**; this Gradio app is just the window onto the wood.
+
+## What you can do
+- **Step / Auto-run** the simulation and watch the market move.
+- **Tempt Fate**: draw a *Wood Legend*, a famous market mania reskinned as woodland
+  folklore (Tulip Mania, the South Sea Bubble, the 1929 bank runs, the 2020
+  toilet-paper scramble, the Hunt silver corner, the Dust Bowl). Each carries its
+  real-world inspiration, the history hiding under the fur.
+- **Plant a rumor**, cause a **drought**, or trigger a **gold rush**, and watch the
+  creatures react: prices swing, the wealth gap (Gini) widens, and the woodcutter
+  who controls the firewood gets rich while the panicky hoarder goes broke.
+- **Read their minds**: every creature's private reasoning for the turn is shown,
+  and shared as open agent traces.
+
+## How it works
+- `ttw/` — the engine: a deterministic double-auction market (`market.py`), the
+  turn loop with diet variety, spoilage, and a winter fuel crisis (`sim.py`), the
+  small-model agent policy (`agents.py`), player shocks (`shocks.py`), and the
+  Wood Legends deck (`events.py`).
+- `serve.py` — the vLLM model endpoint on Modal.
+- `app.py` — this Gradio app.
+
+## Run it yourself
+```bash
+pip install -r requirements.txt
+# No GPU, dummy agents (for trying the UI):
+TTW_DUMMY=1 python app.py
+# Real small model: deploy the endpoint first, then run the app.
+python -m modal deploy serve.py
+python app.py
+```
+
+Built for the Build Small Hackathon, 2026. Small models, big adventures.

app.py

@@ -0,0 +1,146 @@
+"""Thousand Token Wood -- a tiny emergent economy of small-model agents.
+
+Gradio app for the Build Small Hackathon. Five woodland creatures, each driven
+by a <=4B model (Qwen2.5-3B) served on Modal, trade goods for pebbles, gossip,
+and react to "Wood Legends" (famous market manias reskinned). You poke the
+economy and watch bubbles, crashes, and a widening wealth gap emerge.
+
+Run locally without a GPU:   TTW_DUMMY=1 python app.py
+Run against the real model:  python -m modal deploy serve.py  &&  python app.py
+"""
+
+from __future__ import annotations
+
+import os
+
+import gradio as gr
+
+from ttw.game import Game
+from ttw.world import GOODS
+
+AUTO_SECONDS = 3.0
+
+
+def make_policy():
+    """Real small-model policy by default; a no-GPU dummy when TTW_DUMMY=1."""
+    if os.environ.get("TTW_DUMMY") == "1":
+        from ttw.dummy import make_random_policy
+
+        return make_random_policy(seed=7)
+    from ttw.agents import make_llm_policy
+    from ttw.llm import ModalLLM
+
+    return make_llm_policy(ModalLLM(), temperature=0.7)
+
+
+def new_game() -> Game:
+    return Game(make_policy(), deck_seed=7)
+
+
+def _views(game: Game):
+    return (
+        game.town_frame(),
+        game.price_frame(),
+        game.gini_frame(),
+        game.ticker_markdown(),
+        game.traces_markdown(),
+    )
+
+
+def init():
+    game = new_game()
+    return (game, *_views(game))
+
+
+def do_step(game: Game):
+    if game is not None:
+        game.step()
+    return (game, *_views(game))
+
+
+def do_tempt(game: Game):
+    if game is not None:
+        game.tempt_fate()
+    return (game, *_views(game))
+
+
+def do_gold_rush(game: Game):
+    if game is not None:
+        game.shock("gold_rush", amount=30)
+    return (game, *_views(game))
+
+
+def do_drought(game: Game, good: str):
+    if game is not None:
+        game.shock("drought", good=good, severity=0.2)
+    return (game, *_views(game))
+
+
+def do_rumor(game: Game, message: str):
+    if game is not None and message.strip():
+        game.shock("rumor", message=message.strip())
+    return (game, *_views(game), "")
+
+
+def do_reset():
+    return init()
+
+
+with gr.Blocks(title="Thousand Token Wood") as demo:
+    gr.Markdown(
+        "# Thousand Token Wood\n"
+        "A tiny emergent economy. Five woodland creatures, each a small (<=4B) model, "
+        "trade, gossip, and panic. Poke the wood and watch bubbles, crashes, and a "
+        "widening wealth gap emerge. **Press Step to begin.**"
+    )
+
+    game_state = gr.State(None)
+
+    with gr.Row():
+        with gr.Column(scale=2):
+            gr.Markdown("### The town square")
+            town = gr.Dataframe(interactive=False, wrap=True)
+            with gr.Accordion("What the creatures are thinking", open=True):
+                traces = gr.Markdown()
+        with gr.Column(scale=3):
+            gr.Markdown("### Prices")
+            price_plot = gr.LinePlot(x="turn", y="price", color="good", height=240)
+            gr.Markdown("### Wealth gap (Gini)")
+            gini_plot = gr.LinePlot(x="turn", y="gini", height=160, y_lim=[0, 1])
+
+    with gr.Row():
+        step_btn = gr.Button("Step", variant="primary")
+        auto = gr.Checkbox(label=f"Auto-run (every {AUTO_SECONDS:.0f}s)", value=False)
+        tempt_btn = gr.Button("Tempt Fate (draw a Wood Legend)")
+        reset_btn = gr.Button("Reset the wood")
+
+    with gr.Row():
+        gold_btn = gr.Button("Gold rush")
+        drought_good = gr.Dropdown(GOODS, value="berries", label="Drought on")
+        drought_btn = gr.Button("Cause drought")
+        rumor_box = gr.Textbox(label="Plant a rumor", placeholder="the mushrooms are cursed this year...", scale=2)
+        rumor_btn = gr.Button("Spread it")
+
+    gr.Markdown("### The wood's news")
+    ticker = gr.Markdown()
+
+    timer = gr.Timer(AUTO_SECONDS, active=False)
+
+    outputs = [game_state, town, price_plot, gini_plot, ticker, traces]
+
+    demo.load(init, outputs=outputs)
+    step_btn.click(do_step, game_state, outputs)
+    timer.tick(do_step, game_state, outputs)
+    # Re-assert AUTO_SECONDS so toggling doesn't reset to Gradio's default interval.
+    auto.change(lambda a: gr.Timer(AUTO_SECONDS, active=a), auto, timer)
+    tempt_btn.click(do_tempt, game_state, outputs)
+    gold_btn.click(do_gold_rush, game_state, outputs)
+    drought_btn.click(do_drought, [game_state, drought_good], outputs)
+    # do_rumor returns one extra value (the trailing "") to clear the textbox, so
+    # its outputs are `outputs + [rumor_box]`. Keep these aligned if _views changes.
+    rumor_btn.click(do_rumor, [game_state, rumor_box], outputs + [rumor_box])
+    reset_btn.click(do_reset, outputs=outputs)
+
+
+if __name__ == "__main__":
+    demo.launch(theme=gr.themes.Soft())

modal_smoke_test.py

@@ -0,0 +1,61 @@
+"""Modal GPU smoke test for Thousand Token Wood.
+
+Proves the serving path works end to end before the hack weekend:
+  - a GPU container spins up on Modal
+  - a small model (<=32B) loads
+  - it returns one in-character generation
+
+Run:  python -m modal run modal_smoke_test.py
+"""
+
+import modal
+
+MODEL = "Qwen/Qwen2.5-7B-Instruct"  # ~15GB in bf16, fits on a single L4 (24GB)
+
+app = modal.App("ttw-smoke-test")
+
+image = (
+    modal.Image.debian_slim(python_version="3.12")
+    .pip_install("transformers==4.46.0", "torch==2.5.1", "accelerate==1.1.1")
+)
+
+
+@app.function(gpu="L4", image=image, timeout=900)
+def generate() -> str:
+    import torch
+    from transformers import AutoModelForCausalLM, AutoTokenizer
+
+    tok = AutoTokenizer.from_pretrained(MODEL)
+    model = AutoModelForCausalLM.from_pretrained(
+        MODEL, torch_dtype=torch.bfloat16, device_map="cuda"
+    )
+
+    messages = [
+        {
+            "role": "system",
+            "content": "You are Fenn, a sly fox trader in Thousand Token Wood.",
+        },
+        {
+            "role": "user",
+            "content": (
+                "The price of acorns just crashed after a rumor that the harvest "
+                "was poisoned. In one sentence, decide whether you buy or sell, "
+                "and why."
+            ),
+        },
+    ]
+    text = tok.apply_chat_template(
+        messages, tokenize=False, add_generation_prompt=True
+    )
+    inputs = tok(text, return_tensors="pt").to("cuda")
+    out = model.generate(**inputs, max_new_tokens=80, do_sample=False)
+    return tok.decode(
+        out[0][inputs.input_ids.shape[1]:], skip_special_tokens=True
+    ).strip()
+
+
+@app.local_entrypoint()
+def main():
+    print("\n=== Fenn the fox says ===")
+    print(generate.remote())
+    print("=========================\n")

requirements.txt

@@ -0,0 +1,5 @@
+# Hugging Face Space (frontend only). The heavy model runs on Modal, so the
+# Space needs just the Gradio UI, the Modal client, and pandas for the charts.
+gradio==6.16.0
+modal==1.4.3
+pandas==2.3.3

scripts/run_llm.py

@@ -0,0 +1,80 @@
+"""Run the wood on the real small model via the deployed Modal endpoint.
+
+Doubles as the 3B reliability gate: it reports how often the model emits a
+parseable JSON object and at least one valid offer. If 3B holds up, we keep
+Tiny Titan eligibility; if not, fall back to 7B (set TTW_MODEL and redeploy).
+
+Run (after `python -m modal deploy serve.py`):
+    python scripts/run_llm.py
+"""
+
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parents[1]))
+
+from ttw.actions import parse_actions
+from ttw.agents import make_llm_policy
+from ttw.events import EventDeck
+from ttw.llm import ModalLLM
+from ttw.market import gini
+from ttw.sim import step
+from ttw.world import seed_world
+
+
+def main(turns: int = 15) -> None:
+    world = seed_world()
+    client = ModalLLM()
+    policy = make_llm_policy(client, temperature=0.7)
+    deck = EventDeck(seed=7)
+
+    parsed_ok = 0
+    json_ok = 0
+    total = 0
+
+    for _ in range(turns):
+        # Fate draws a Wood Legend (a reskinned market mania) every 5 turns.
+        if world.turn in (4, 9, 13):
+            legend = deck.draw(world)
+            print(f"\n*** WOOD LEGEND: {legend.title} ***")
+            print(f"    {legend.flavor}  (inspired by: {legend.inspired_by})")
+
+        events = step(world, policy)
+        raw = policy.state["raw"]
+
+        # Reliability accounting for this turn.
+        for name, text in raw.items():
+            total += 1
+            offers, _ = parse_actions(name, text)
+            from ttw.actions import _extract_json
+
+            if _extract_json(text) is not None:
+                json_ok += 1
+            if offers:
+                parsed_ok += 1
+
+        trades = [e for e in events if e["type"] == "trade"]
+        gossip = [e for e in events if e["type"] == "gossip"]
+        prices = " ".join(f"{g}={p:.0f}" for g, p in world.last_price.items())
+        nets = [c.net_worth(world.last_price) for c in world.alive()]
+        print(f"\n=== turn {world.turn} | {len(trades)} trades | gini {gini(nets):.2f} | {prices}")
+        for t in trades:
+            print(f"   {t['buyer']} bought {t['qty']} {t['good']} from {t['seller']} @ {t['price']}")
+        for g in gossip:
+            print(f"   [rumor] {g['creature']}: {g['message']}")
+
+    # One sample reasoning trace, to eyeball quality.
+    sample_name = next(iter(policy.state["raw"]))
+    print(f"\n--- sample reasoning trace ({sample_name}, last turn) ---")
+    print(policy.state["raw"][sample_name].strip()[:500])
+
+    print("\n=== RELIABILITY ===")
+    print(f"valid JSON object:      {json_ok}/{total} ({100*json_ok/total:.0f}%)")
+    print(f"yielded >=1 valid offer: {parsed_ok}/{total} ({100*parsed_ok/total:.0f}%)")
+    print("\nFinal standings:")
+    for c in sorted(world.alive(), key=lambda x: -x.net_worth(world.last_price)):
+        print(f"  {c.name:<9} pebbles={c.pebbles:>4} wellbeing={c.wellbeing} net={c.net_worth(world.last_price):.0f}")
+
+
+if __name__ == "__main__":
+    main()

scripts/run_random.py

@@ -0,0 +1,36 @@
+"""Watch the wood run under the dummy random policy. Sanity/feel check, no LLM.
+
+Run:  python scripts/run_random.py
+"""
+
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parents[1]))
+
+from ttw.dummy import make_random_policy
+from ttw.market import gini
+from ttw.sim import step
+from ttw.world import seed_world
+
+
+def main(turns: int = 12) -> None:
+    world = seed_world()
+    policy = make_random_policy(seed=7)
+
+    for _ in range(turns):
+        events = step(world, policy)
+        trades = [e for e in events if e["type"] == "trade"]
+        prices = " ".join(f"{g}={p:.0f}" for g, p in world.last_price.items())
+        nets = [c.net_worth(world.last_price) for c in world.alive()]
+        print(f"turn {world.turn:>2} | {len(trades)} trades | gini {gini(nets):.2f} | {prices}")
+        for t in trades:
+            print(f"           {t['buyer']:<9} bought {t['qty']} {t['good']} from {t['seller']:<9} @ {t['price']}")
+
+    print("\nFinal standings:")
+    for c in sorted(world.alive(), key=lambda x: -x.net_worth(world.last_price)):
+        print(f"  {c.name:<9} pebbles={c.pebbles:>4} wellbeing={c.wellbeing} net={c.net_worth(world.last_price):.0f}")
+
+
+if __name__ == "__main__":
+    main()

serve.py

@@ -0,0 +1,86 @@
+"""Modal vLLM serving layer for Thousand Token Wood.
+
+Serves a small chat model (default Qwen2.5-3B-Instruct, <=4B for Tiny Titan
+eligibility) behind a batched `chat_batch` method, so all creatures decide in
+one GPU call per turn. The model is cached in a Modal Volume so cold starts
+don't re-download it.
+
+Deploy:  python -m modal deploy serve.py
+Smoke:   python -m modal run serve.py
+"""
+
+import os
+
+import modal
+
+MODEL = os.environ.get("TTW_MODEL", "Qwen/Qwen2.5-3B-Instruct")
+MODEL_REVISION = os.environ.get("TTW_MODEL_REVISION", "main")
+
+app = modal.App("ttw-serve")
+
+image = (
+    modal.Image.debian_slim(python_version="3.12")
+    .pip_install(
+        "vllm==0.6.6",
+        "huggingface_hub[hf_transfer]==0.26.2",
+    )
+    .env({"HF_HUB_ENABLE_HF_TRANSFER": "1", "VLLM_DO_NOT_TRACK": "1"})
+)
+
+# Persist the HF cache across cold starts so we download the model once.
+hf_cache = modal.Volume.from_name("ttw-hf-cache", create_if_missing=True)
+CACHE_DIR = "/root/.cache/huggingface"
+
+
+@app.cls(
+    gpu="L4",
+    image=image,
+    volumes={CACHE_DIR: hf_cache},
+    scaledown_window=300,  # keep warm 5 min after last call (good for demos)
+    timeout=600,
+)
+class Engine:
+    @modal.enter()
+    def load(self):
+        from vllm import LLM, SamplingParams
+
+        self.SamplingParams = SamplingParams
+        self.llm = LLM(
+            model=MODEL,
+            revision=MODEL_REVISION,
+            dtype="bfloat16",
+            max_model_len=4096,
+            gpu_memory_utilization=0.90,
+            enforce_eager=True,  # faster cold start; we don't need CUDA graphs here
+        )
+
+    @modal.method()
+    def chat_batch(
+        self,
+        conversations: list[list[dict]],
+        max_tokens: int = 256,
+        temperature: float = 0.7,
+    ) -> list[str]:
+        """Run a batch of chat conversations. Returns one completion per input."""
+        params = self.SamplingParams(
+            temperature=temperature, top_p=0.9, max_tokens=max_tokens
+        )
+        outputs = self.llm.chat(conversations, params)
+        return [o.outputs[0].text for o in outputs]
+
+
+@app.local_entrypoint()
+def main():
+    """Quick smoke test of the batched endpoint with two creature prompts."""
+    convos = [
+        [
+            {"role": "system", "content": "You are Fenn, a sly fox speculator."},
+            {"role": "user", "content": "Acorns crashed on a rumor. Buy or sell? One sentence."},
+        ],
+        [
+            {"role": "system", "content": "You are Bramble, an anxious hoarder squirrel."},
+            {"role": "user", "content": "Winter is coming. What do you stockpile? One sentence."},
+        ],
+    ]
+    for text in Engine().chat_batch.remote(convos, max_tokens=60, temperature=0.7):
+        print("-", text.strip())

tasks/todo.md

@@ -0,0 +1,165 @@
+# Thousand Token Wood — Build Plan
+
+Build Small Hackathon (Gradio + Hugging Face). Track: An Adventure in Thousand Token Wood.
+Hack window June 5-15 2026. Build effort: both weekends full (June 6-8, 13-15). Weekday prep floor untouched.
+
+## Concept
+A tiny emergent economy. 4-6 woodland creatures, each a small-model agent (<=32B), trade goods,
+set prices, gossip, hoard, and panic. The player pokes the economy (shocks, rumors, taxes) and
+watches bubbles, crashes, and a widening wealth gap emerge. Nobody scripts the drama; the agents do it.
+
+## Architecture
+- **Model**: Qwen2.5-7B-Instruct (decide 7B vs 3B after smoke test; 7B for tool-call reliability).
+- **Serving**: Modal GPU-backed endpoint (vLLM for throughput across many agent calls). Targets the
+  separate $20K Modal prize category.
+- **Frontend**: Gradio app hosted as an HF Space under the build-small-hackathon org, on cheap CPU,
+  calling the Modal endpoint.
+- **Why small is load-bearing**: a living economy needs many agents x many turns; frontier models are
+  too expensive/slow for that. Small local models make the simulation feasible. That is the thesis.
+
+## Acceptance criteria (definition of done)
+- [ ] Public HF Space under the org, runs without crashing.
+- [ ] >=4 creature-agents trade autonomously over >=20 turns.
+- [ ] Player can trigger >=2 shock types (e.g. drought, rumor) and the economy visibly reacts.
+- [ ] UI shows: town square, narrated event ticker, price + wealth(Gini) charts, clickable per-agent
+      reasoning trace.
+- [ ] Seeded reproducible "demo run" that reliably produces a fun arc (bubble or panic).
+- [ ] Demo video recorded + social post written + submitted by June 15.
+- [ ] Bonus badges: Sharing is Caring (published agent traces) + Field Notes (blog post).
+
+## Milestones
+
+### Pre-weekend (this week) — de-risk
+- [x] Claim Modal ($250) + HF ($20) credits.
+- [x] Install modal + gradio, authenticate Modal CLI.
+- [x] GPU smoke test: small model loads + generates one in-character line on Modal. PASS (Qwen2.5-7B
+      on L4; Fenn the fox produced a coherent in-character buy-the-dip decision). Cold start ~3-4 min
+      (build 80s + model download 76s + load 38s) -> use vLLM + keep-warm for the live demo.
+- [x] Sign off on this plan (go given 2026-06-05, hack window open).
+
+### Weekend 1 (June 6-8) — the engine
+- [x] World model: goods, currency (pebbles), inventories, needs, wealth. (ttw/world.py)
+- [x] Market engine: offer book, double-auction matching, price updates, consumption — deterministic,
+      tested with dummy random agents first (no LLM). (ttw/market.py, ttw/sim.py, ttw/dummy.py)
+      Reviewer-loop: 2 blocking bugs found + fixed (matching retirement logic; Infinity/NaN crash),
+      re-reviewed APPROVED. 9 tests pass. Random sim runs 12 turns, valid, emergent (Pip squeezed).
+- [x] Action schema (offers + gossip) + JSON parse-and-repair loop so a small model can't break the
+      sim. (ttw/actions.py)
+- [x] vLLM serving layer on Modal (serve.py, app "ttw-serve" deployed; L4, model cache volume,
+      keep-warm 300s). vLLM 0.6.6 loads cleanly with transformers 4.50.3 (resolver pick) -- no conflict.
+- [x] Wire real small-model agent emitting valid actions (ttw/agents.py drop-in Policy; ttw/llm.py
+      client). Batches all creatures into ONE GPU call/turn, memoized by turn; keeps raw text for traces.
+- [x] Scale to 5 agents on the real model (scripts/run_llm.py). RELIABILITY: 3B = 100% valid JSON,
+      97% valid offer over 30 calls. MODEL LOCKED: Qwen2.5-3B (Tiny Titan eligible).
+
+### economic-pressure tuning -- ITERATION 1 DONE (big progress)
+Added scarcity mechanics: diet variety (MAX_FOOD_PER_GOOD), spoilage (SPOIL_RATE), rising winter fuel
+need (fuel_need), production drought multipliers, and player shocks (ttw/shocks.py: drought, rumor,
+gold_rush, harvest). Strengthened agent prompt. 14 tests pass.
+
+15-turn LLM run (model 3B, reliability 100%/100% over 75 calls) RESULTS:
+- WORKS: sustained trade across all turns; planted rumor PROPAGATED organically (creatures repeated +
+  embellished it); firewood panic on turn 11 (price 5->7); Gini climbed 0.18->0.41; Pip (woodcutter)
+  ended richest. The "plant rumor -> panic -> price spike -> winner" demo arc emerged unscripted.
+- BROKEN, fix next:
+  - [ ] TOO LETHAL: all 5 creatures ended wellbeing=0 (starved/froze). Scarcity outpaces trade speed.
+        Soften: lower food_need (3->2) and/or raise MAX_FOOD_PER_GOOD, slow FUEL_RAMP_EVERY, maybe
+        a starting buffer. Target: most survive a 20-turn run, 1-2 may collapse for drama.
+  - [ ] STICKY PRICES: reference prices barely move on the chart because the prompt shows agents the
+        exact reference price and they quote it. Stop spoon-feeding exact prices (show a band, or last
+        trade only) so supply/demand moves prices visibly for the chart.
+  - [ ] last_price reflects only the final trade of a turn; consider volume-weighted or high/low capture
+        for the price chart.
+
+### economic-pressure tuning -- ITERATION 2 (softened scarcity) -- DID NOT FIX
+Lowered food_need 3->2, FUEL_RAMP 5->8, SPOIL 0.25->0.20, added starting buffers. Result: trade got
+QUIETER and all 5 still ended wellbeing=0. Root causes found (deeper than balance numbers):
+- Wellbeing is a one-way ratchet: any food OR fuel shortfall subtracts, recovery is only +1/turn and
+  only when perfectly provisioned -> chronic small shortfalls grind everyone to 0. It's a death clock,
+  not a mood.
+- 3B trades suboptimally: agents buy their OWN product (Mossback produces acorns yet bid to BUY acorns)
+  and don't reliably buy what they lack. Valid JSON, weak economic judgment (small-model limitation).
+- The rumor is so salient it crowds out survival trades (turns 7-15 mostly gossip, little trading).
+
+### DESIGN FORK (needs Lester's call): survival game vs economic-drama sandbox
+The delightful, working parts are the ECONOMIC drama (rumor spread, firewood panic, Gini divergence,
+Pip getting rich). The survival/death layer fights it. PROPOSED: reframe as a sandbox --
+- [ ] Make wellbeing a real-time MOOD = f(current food+fuel provisioning), mean-reverting, floored so
+      nobody death-spirals. Stakes live in pebbles/prices/status, not starvation.
+- [ ] Prompt fix: "you PRODUCE {x}; never buy {x}; buy the OTHER foods you are low on." Add a 1-shot
+      example of a good move. Consider 7B if 3B judgment stays weak (would cost Tiny Titan eligibility).
+- [ ] Optionally keep mild stakes: only a genuinely broke/empty creature visibly suffers (drama), not all.
+
+### economic-pressure tuning -- ITERATION 3 (sandbox redesign) -- SUCCESS
+Reframed wellbeing as a mean-reverting MOOD (_update_mood, range [4,10], no death spiral) + prompt fix
+("you produce X, never buy X; buy what you lack" + 1-shot example + computed lacking list). 15 tests pass.
+15-turn LLM run (3B, reliability 100%/100%):
+- Nobody dies (wellbeing 6-7). Trade robust (4-9/turn, never silent). Self-buying bug GONE (Mossback
+  sells acorns, buys what it lacks). Roles emerged: Pip (firewood) richest net 387; Bramble (hoarder)
+  broke net 25. Gini 0.14->0.38. Rumor propagates. This is the demo-worthy economy.
+
+### LAST ECONOMY GAP: price dynamics -- SOLVED + reviewer-APPROVED
+drift_prices (ttw/market.py) nudges reference price by RESIDUAL (post-match) supply/demand imbalance.
+Live 15-turn run: prices now tell stories -- honey CRASHED 10->3 (Oona liquidated her hoard during the
+"Run on Oona's Hoard" legend), mushrooms 5->2 (Fenn dumped), firewood BOOMED 4->7 (winter scarcity).
+Wood Legends fired and integrated narratively (the bank-run legend literally caused Oona to dump honey
+-> honey price crash). Reliability 100%/100%. Gini 0.13->0.32. Nobody died (wellbeing 4-9). Pip richest.
+THE ECONOMY IS DEMO-COMPLETE.
+- Minor cosmetic backlog: rumor field drifts into verbose self-narration instead of punchy gossip;
+  constrain gossip in the prompt later (not blocking).
+
+### Wood Legends event deck (ttw/events.py) -- BUILT, unit-tested (Lester's idea 06-05)
+Famous market manias/panics reskinned as random woodland chapters, composed from shocks.py. 6 events
+(Tulip/Acorn Mania, South Sea/Hollow Log Co, 1929 run/Oona's Hoard, 2020 TP/Firewood Panic, Hunt
+silver/Honey Corner, Dust Bowl/Long Frost). Each has real `inspired_by` for a UI reveal + Field Notes
++ allocator-credibility tie-in. EventDeck draws w/o repeat until exhausted. 17 tests pass.
+- [ ] Wire EventDeck into the sim/run loop (fire a legend every N turns or on a player "Tempt Fate"
+      button) and validate live on 3B. Not yet LLM-tested.
+- Tone guardrail set in code: economic history only, no real tragedies/living people.
+
+### Weekend 2 -- Gradio UI -- BUILT + reviewer-APPROVED (2026-06-05)
+- [x] ttw/narrate.py (event -> ticker prose), ttw/game.py (Game wrapper: history, step/shock/tempt_fate,
+      pandas frames for charts/town, markdown for ticker/traces), app.py (Gradio Blocks).
+- [x] UI: town square (Dataframe), price LinePlot + Gini LinePlot, news ticker, reasoning-traces
+      accordion, controls (Step, Auto-run via gr.Timer, Tempt Fate, Gold rush, Drought, Plant rumor, Reset).
+- [x] TTW_DUMMY=1 = no-GPU dummy-policy mode for local dev; default = ModalLLM live.
+- [x] 25 tests pass (18 engine + 7 game). App builds, callbacks run, server HTTP 200. Reviewer APPROVED
+      (fixed gr.Timer interval on toggle; verified make_llm_policy signature for live path).
+- Gradio 6 notes: theme -> launch(), no overlay_point on LinePlot.
+
+### REMAINING to submit (by Jun 15)
+- [ ] Deploy as HF Space under build-small-hackathon org (Gradio on CPU calling Modal endpoint).
+      Needs: requirements.txt, README.md w/ Space metadata, modal token as a Space secret, git push.
+      Verify live: does the Space reach the deployed ttw-serve Modal app? (auth across HF<->Modal.)
+- [ ] Visual QA in browser (charts render, traces readable, buttons wired) -- Lester's eyes.
+- [ ] Optional polish: tighten gossip prompt; Off-Brand (gr.Server custom UI) for Bonus Quest stack.
+- [ ] Lester's hands: demo video (honey-crash legend chain = money shot), Field Notes blog, social post, SUBMIT.
+
+### Known minor items (not blocking)
+- _extract_json brace scanner doesn't skip braces inside JSON string literals. Future hardening.
+- 3B occasionally rambles/repeats (Bramble "bits of fabric and bits of fabric"). Cosmetic; cap tokens.
+- _extract_json brace scanner doesn't skip braces inside JSON string literals (e.g. gossip with "}").
+  Future hardening; harmless today.
+
+### Weekend 2 (June 13-15) — make it sing
+- [ ] Gradio UI: town square, event ticker, price/Gini charts, per-agent reasoning expander.
+- [ ] Player controls: shock buttons (drought, frost, gold rush), rumor text input, step/auto-run.
+- [ ] Personas + per-agent memory (short-term trades + long-term grudges/relationships).
+- [ ] Narrator layer: structured events -> charming prose.
+- [ ] Seed + tune a reproducible demo run with a clean dramatic arc.
+- [ ] Deploy Space, confirm public URL works.
+- [ ] Record demo video, write Field Notes post, publish traces, write social post, SUBMIT.
+
+## Stretch (only if ahead)
+- [ ] Off the Grid badge (fully local llama.cpp fallback path).
+- [ ] Small-vs-bigger-model behavior comparison for the blog post.
+- [ ] More creatures / more goods / seasons.
+
+## Risks
+- Modal cold-start latency on the demo — mitigate with keep-warm container during recording.
+- Small-model invalid actions — the parse-and-repair loop is the critical reliability primitive.
+- Scope creep into "real economics" — keep it a toy; drama > accuracy.
+- ZeroGPU/queue not used; serving is on Modal credits ($250 budget, watch burn).
+
+## Review
+(to be filled at the end)

tests/test_game.py

@@ -0,0 +1,71 @@
+"""Headless tests for the Game wrapper, using the dummy policy (no GPU/Gradio).
+
+Run:  python -m pytest tests/ -q
+"""
+
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parents[1]))
+
+from ttw.dummy import make_random_policy
+from ttw.game import Game
+
+
+def _game():
+    return Game(make_random_policy(seed=3), deck_seed=1)
+
+
+def test_baseline_recorded_before_any_step():
+    g = _game()
+    assert not g.price_frame().empty  # turn 0 prices recorded
+    assert g.gini_frame().iloc[0]["turn"] == 0
+
+
+def test_step_advances_and_grows_history():
+    g = _game()
+    rows_before = len(g.price_frame())
+    g.step()
+    assert g.world.turn == 1
+    assert len(g.price_frame()) > rows_before
+    assert g.gini_frame().iloc[-1]["turn"] == 1
+
+
+def test_price_frame_shape_is_long_per_good():
+    g = _game()
+    g.step()
+    pf = g.price_frame()
+    assert set(pf.columns) == {"turn", "good", "price"}
+    # one row per good per recorded turn (turn 0 baseline + turn 1)
+    assert (pf["turn"] == 1).sum() == 5
+
+
+def test_town_frame_lists_all_creatures_sorted_by_wealth():
+    g = _game()
+    g.step()
+    tf = g.town_frame()
+    assert len(tf) == 5
+    nets = list(tf["net worth"])
+    assert nets == sorted(nets, reverse=True)  # richest first
+
+
+def test_tempt_fate_draws_legend_and_tickers():
+    g = _game()
+    title = g.tempt_fate()
+    assert isinstance(title, str) and title
+    assert any("inspired by" in line for line in g.ticker)
+
+
+def test_shock_gold_rush_echoes_to_ticker():
+    g = _game()
+    before = sum(c.pebbles for c in g.world.alive())
+    g.shock("gold_rush", amount=10)
+    assert sum(c.pebbles for c in g.world.alive()) == before + 10 * 5
+    assert any("windfall" in line.lower() for line in g.ticker)
+
+
+def test_traces_markdown_handles_dummy_policy_gracefully():
+    """Dummy policy has no raw thoughts; traces view must not crash."""
+    g = _game()
+    g.step()
+    assert isinstance(g.traces_markdown(), str)  # no exception, returns a string

tests/test_market.py

@@ -0,0 +1,236 @@
+"""Invariant tests for the deterministic engine. No GPU, no network.
+
+Run:  python -m pytest tests/ -q   (from the project root)
+"""
+
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parents[1]))
+
+from ttw import shocks
+from ttw.actions import Offer, parse_actions
+from ttw.dummy import make_random_policy
+from ttw.market import clear_market, drift_prices, gini
+from ttw.sim import _burn_fuel, _eat, _spoil, _update_mood, step
+from ttw.world import SPOIL_RATE, fuel_need, seed_world
+
+
+def _total_pebbles(world):
+    return sum(c.pebbles for c in world.alive())
+
+
+def test_trade_conserves_pebbles_and_is_nonnegative():
+    """A round of trading moves pebbles around but never creates/destroys them,
+    and no creature ends with negative pebbles or inventory."""
+    world = seed_world()
+    before = _total_pebbles(world)
+    # Force a crossing pair: Fenn buys acorns high, Mossback sells low.
+    offers = [
+        Offer("Fenn", "buy", "acorns", 8, 5),
+        Offer("Mossback", "sell", "acorns", 4, 5),
+    ]
+    events = clear_market(world, offers)
+    assert events, "a crossing buy/sell should produce at least one trade"
+    assert _total_pebbles(world) == before
+    for c in world.alive():
+        assert c.pebbles >= 0
+        assert all(q >= 0 for q in c.inventory.values())
+
+
+def test_no_trade_when_not_crossing():
+    world = seed_world()
+    offers = [
+        Offer("Fenn", "buy", "honey", 3, 2),
+        Offer("Oona", "sell", "honey", 10, 2),
+    ]
+    assert clear_market(world, offers) == []
+
+
+def test_cannot_oversell_inventory():
+    """Seller offering more than it holds only trades what it actually has."""
+    world = seed_world()
+    world.creatures["Oona"].inventory["honey"] = 2
+    offers = [
+        Offer("Fenn", "buy", "honey", 12, 10),
+        Offer("Oona", "sell", "honey", 6, 10),
+    ]
+    clear_market(world, offers)
+    assert world.creatures["Oona"].inventory["honey"] == 0
+    assert world.creatures["Fenn"].inventory["honey"] == 3  # started with 1, bought 2
+
+
+def test_full_sim_runs_and_stays_valid():
+    """20 turns of the random policy: economy runs, invariants hold throughout."""
+    world = seed_world()
+    policy = make_random_policy(seed=42)
+    pebbles_start = _total_pebbles(world)
+    for _ in range(20):
+        step(world, policy)
+        for c in world.alive():
+            assert c.pebbles >= 0, f"{c.name} went bankrupt below zero"
+            assert all(q >= 0 for q in c.inventory.values())
+    # Trading is pebble-conserving; production/consumption don't touch pebbles,
+    # so the total purse of the wood is invariant across the whole run.
+    assert _total_pebbles(world) == pebbles_start
+    assert world.turn == 20
+
+
+def test_drift_prices_moves_with_pressure_and_spares_untouched_goods():
+    world = seed_world()
+    honey0 = world.last_price["honey"]
+    drift_prices(world, [Offer("Fenn", "buy", "honey", 9, 10)])  # all demand
+    assert world.last_price["honey"] > honey0  # price rises
+
+    acorns0 = world.last_price["acorns"]
+    drift_prices(world, [Offer("Mossback", "sell", "acorns", 4, 10)])  # all supply
+    assert world.last_price["acorns"] < acorns0  # price falls
+
+    mush0 = world.last_price["mushrooms"]
+    drift_prices(world, [Offer("Fenn", "buy", "honey", 9, 1)])  # no mushroom offers
+    assert world.last_price["mushrooms"] == mush0  # untouched good unchanged
+
+
+def test_gini_bounds():
+    assert gini([10, 10, 10, 10]) == 0.0
+    assert gini([]) == 0.0
+    assert gini([0, 0, 100]) > 0.5  # very unequal
+
+
+def test_parse_actions_tolerates_junk():
+    """The parse-and-repair layer salvages valid offers and drops the rest."""
+    text = (
+        "Sure! Here's my move:\n```json\n"
+        '{"thought":"buy the dip","offers":['
+        '{"side":"buy","good":"acorns","price":7,"qty":3},'
+        '{"side":"sell","good":"glass","price":5,"qty":1},'  # invalid good -> dropped
+        '{"side":"buy","good":"honey","price":-2,"qty":4}],'  # bad price -> dropped
+        '"gossip":"the mushrooms are cursed"}\n```'
+    )
+    offers, gossip = parse_actions("Fenn", text)
+    assert len(offers) == 1
+    assert offers[0].good == "acorns" and offers[0].price == 7 and offers[0].qty == 3
+    assert gossip and "mushrooms" in gossip[0].message
+
+
+def test_parse_actions_handles_garbage():
+    offers, gossip = parse_actions("Pip", "I refuse to answer in JSON, sorry.")
+    assert offers == [] and gossip == []
+
+
+def test_parse_actions_rejects_non_finite_without_crashing():
+    """json.loads accepts Infinity/NaN; the parser must drop them, not raise."""
+    text = '{"offers":[{"side":"buy","good":"acorns","price":Infinity,"qty":1},'
+    text += '{"side":"sell","good":"berries","price":5,"qty":NaN}]}'
+    offers, gossip = parse_actions("Fenn", text)  # must not raise
+    assert offers == []
+
+
+def test_affordability_blocked_buyer_does_not_hang_or_misfill():
+    """A broke buyer crossing a seller it can't pay yields no trade and no hang."""
+    world = seed_world()
+    world.creatures["Pip"].pebbles = 3  # too poor to pay the clearing price
+    honey_before = world.creatures["Oona"].inventory["honey"]
+    offers = [
+        Offer("Pip", "buy", "honey", 10, 5),
+        Offer("Oona", "sell", "honey", 8, 5),
+    ]
+    events = clear_market(world, offers)  # must terminate
+    assert events == []
+    assert world.creatures["Pip"].pebbles == 3  # untouched
+    assert world.creatures["Oona"].inventory["honey"] == honey_before  # unsold
+
+
+def test_diet_variety_punishes_monoculture():
+    """Holding only one food cannot satisfy a multi-food meal -> hunger shortfall."""
+    world = seed_world()
+    c = world.creatures["Mossback"]
+    c.inventory = {"acorns": 99, "berries": 0, "mushrooms": 0, "honey": 0, "firewood": 9}
+    c.food_need = 3
+    c.wellbeing = 10
+    ev = _eat(c, turn=1)
+    assert ev["type"] == "hunger" and ev["shortfall"] == 2  # ate 1 acorn, missed 2
+    assert c.inventory["acorns"] == 98  # only one unit counted toward the meal
+
+
+def test_fuel_burn_consumes_firewood_and_reports_cold_when_short():
+    world = seed_world()
+    c = world.creatures["Oona"]
+    c.inventory["firewood"] = 0
+    ev = _burn_fuel(c, turn=1)
+    assert ev["type"] == "cold" and ev["shortfall"] == fuel_need(1)
+    # _burn_fuel no longer touches wellbeing; mood is updated separately.
+
+
+def test_mood_mean_reverts_and_never_dies():
+    """Wellbeing drifts toward a comfort target, recovers, and floors above zero."""
+    world = seed_world()
+    c = world.creatures["Pip"]
+    # Sustained double shortfall pulls mood DOWN toward target 4, never to 0.
+    c.wellbeing = 10
+    for _ in range(20):
+        _update_mood(c, food_short=1, fuel_short=1)
+    assert c.wellbeing == 4  # floor for a fully-short creature, not death
+    # Once provisioned, it recovers back to 10.
+    for _ in range(20):
+        _update_mood(c, food_short=0, fuel_short=0)
+    assert c.wellbeing == 10
+
+
+def test_spoilage_floors_and_spares_firewood():
+    world = seed_world()
+    c = world.creatures["Bramble"]
+    c.inventory = {"acorns": 10, "berries": 2, "mushrooms": 0, "honey": 0, "firewood": 10}
+    lost = _spoil(c)
+    assert lost["acorns"] == int(10 * SPOIL_RATE)  # spoils at any rate >=0.1
+    assert "berries" not in lost  # floor(2*rate)=0 for rate<=0.49, no loss
+    assert c.inventory["firewood"] == 10  # fuel never rots
+
+
+def test_drought_cuts_production():
+    """A drought shock reduces a good's production on subsequent turns."""
+    world = seed_world()
+    shocks.drought(world, "acorns", severity=0.0)  # total crop failure
+    before = world.creatures["Mossback"].inventory["acorns"]
+    # Freeze decisions to no-ops so we isolate production.
+    step(world, lambda w, n: ([], []))
+    after = world.creatures["Mossback"].inventory["acorns"]
+    # Mossback produced 0 acorns this turn; only spoilage/eating reduced stock.
+    assert after <= before
+
+
+def test_gold_rush_conserves_nothing_but_is_bounded():
+    world = seed_world()
+    total_before = sum(c.pebbles for c in world.alive())
+    shocks.gold_rush(world, amount=40)
+    total_after = sum(c.pebbles for c in world.alive())
+    assert total_after == total_before + 40 * len(world.alive())
+
+
+def test_event_deck_applies_effects_and_no_repeats_until_exhausted():
+    """Drawing a Wood Legend perturbs the world, logs it, and cycles all events
+    before any repeats."""
+    from ttw.events import EVENTS, EventDeck
+
+    world = seed_world()
+    deck = EventDeck(seed=1)
+    drawn = [deck.draw(world).key for _ in range(len(EVENTS))]
+    assert set(drawn) == {e.key for e in EVENTS}  # every legend told exactly once
+    assert len(set(drawn)) == len(EVENTS)  # no repeats within one cycle
+    # Each draw left an event record with a real-world attribution for the reveal.
+    event_logs = [e for e in world.log if e["type"] == "event"]
+    assert len(event_logs) == len(EVENTS)
+    assert all(e["inspired_by"] for e in event_logs)
+
+
+def test_acorn_mania_injects_pebbles_and_a_rumor():
+    from ttw.events import EventDeck
+    from ttw.events import EVENTS
+
+    world = seed_world()
+    mania = next(e for e in EVENTS if e.key == "acorn_mania")
+    deck = EventDeck(seed=0, events=[mania])
+    before = sum(c.pebbles for c in world.alive())
+    deck.draw(world)
+    assert sum(c.pebbles for c in world.alive()) > before  # gold rush fired
+    assert any("acorn" in r.lower() for r in world.rumors)  # rumor planted

ttw/__init__.py

@@ -0,0 +1 @@
+"""Thousand Token Wood — a tiny emergent economy of small-model agents."""

ttw/actions.py

@@ -0,0 +1,145 @@
+"""The action schema every agent (dummy or small-model) speaks.
+
+This is the contract between the agents and the world. The small model will
+emit JSON matching these shapes; `parse_actions` is the parse-and-repair layer
+that keeps a 7B (or 3B) model from ever breaking the simulation. Invalid or
+malformed actions are dropped, never crash.
+"""
+
+from __future__ import annotations
+
+import json
+import math
+import re
+from dataclasses import dataclass
+
+from .world import GOODS
+
+VALID_SIDES = {"buy", "sell"}
+
+# Sanity caps so a single hallucinated number can't distort the whole economy.
+MAX_OFFER_QTY = 50
+MAX_OFFER_PRICE = 999
+MAX_GOSSIP_CHARS = 200
+
+
+@dataclass
+class Offer:
+    """A single market intent: I will buy/sell `qty` of `good` at `price` each."""
+
+    creature: str
+    side: str  # "buy" | "sell"
+    good: str
+    price: int  # pebbles per unit (integer)
+    qty: int
+
+
+@dataclass
+class Gossip:
+    """A creature broadcasts a rumor into the wood."""
+
+    creature: str
+    message: str
+
+
+def _coerce_offer(creature: str, raw: dict) -> Offer | None:
+    """Validate one offer dict, returning None if it cannot be salvaged."""
+    try:
+        side = str(raw.get("side", "")).lower().strip()
+        good = str(raw.get("good", "")).lower().strip()
+        price_f = float(raw.get("price"))
+        qty_f = float(raw.get("qty"))
+    except (TypeError, ValueError):
+        return None
+    # json.loads accepts Infinity/NaN; reject non-finite before int() can raise
+    # OverflowError. The whole point of this layer is to never crash.
+    if not (math.isfinite(price_f) and math.isfinite(qty_f)):
+        return None
+    price = int(round(price_f))
+    qty = int(round(qty_f))
+    if side not in VALID_SIDES or good not in GOODS:
+        return None
+    if price <= 0 or qty <= 0:
+        return None
+    # Cap absurd quantities/prices so one hallucination can't nuke the economy.
+    qty = min(qty, MAX_OFFER_QTY)
+    price = min(price, MAX_OFFER_PRICE)
+    return Offer(creature=creature, side=side, good=good, price=price, qty=qty)
+
+
+def parse_actions(creature: str, text: str) -> tuple[list[Offer], list[Gossip]]:
+    """Extract offers and gossip from a model's raw text output.
+
+    Tolerant by design: finds the first JSON object/array in the text, ignores
+    junk, and silently drops anything malformed. Returns (offers, gossip).
+    """
+    offers: list[Offer] = []
+    gossip: list[Gossip] = []
+
+    payload = _extract_json(text)
+    if payload is None:
+        return offers, gossip
+
+    raw_offers = payload.get("offers", []) if isinstance(payload, dict) else []
+    if isinstance(raw_offers, dict):  # model emitted a single offer, not a list
+        raw_offers = [raw_offers]
+    for raw in raw_offers if isinstance(raw_offers, list) else []:
+        if isinstance(raw, dict):
+            offer = _coerce_offer(creature, raw)
+            if offer is not None:
+                offers.append(offer)
+
+    if isinstance(payload, dict):
+        msg = payload.get("gossip")
+        if isinstance(msg, str) and msg.strip():
+            gossip.append(Gossip(creature=creature, message=msg.strip()[:MAX_GOSSIP_CHARS]))
+
+    return offers, gossip
+
+
+def _extract_json(text: str) -> dict | None:
+    """Find and parse the first balanced JSON object in `text`. None on failure.
+
+    Code fences are stripped first, then a single brace-depth scan finds the
+    first balanced object. One scanner handles both fenced and bare output, so
+    nested objects (multi-offer responses) parse correctly in either case.
+    """
+    # Drop ```json ... ``` fences without trying to capture the body via regex
+    # (a non-greedy capture mis-handles nested braces); let the depth scan do it.
+    text = re.sub(r"```(?:json)?", "", text)
+
+    start = text.find("{")
+    if start == -1:
+        return None
+    depth = 0
+    candidate: str | None = None
+    for i in range(start, len(text)):
+        if text[i] == "{":
+            depth += 1
+        elif text[i] == "}":
+            depth -= 1
+            if depth == 0:
+                candidate = text[start : i + 1]
+                break
+    if candidate is None:
+        return None
+    try:
+        parsed = json.loads(candidate)
+        return parsed if isinstance(parsed, dict) else None
+    except json.JSONDecodeError:
+        return None
+
+
+# The instruction block we will hand the small model, kept next to the schema
+# it describes so they never drift apart.
+ACTION_SCHEMA_PROMPT = """\
+Respond with ONLY a JSON object, no prose, in this exact shape:
+{
+  "thought": "one short sentence of your private reasoning",
+  "offers": [
+    {"side": "buy" or "sell", "good": "<one of: acorns, berries, mushrooms, honey, firewood>",
+     "price": <whole number of pebbles per unit>, "qty": <whole number of units>}
+  ],
+  "gossip": "<optional: a short rumor to spread, or empty string>"
+}
+You may post zero, one, or several offers. Only sell what you own; only buy what you can afford."""

ttw/agents.py

@@ -0,0 +1,79 @@
+"""The small-model agent policy.
+
+`make_llm_policy` returns a per-creature Policy (the same signature the engine's
+`step` already expects), so it drops straight into the existing tick loop. But
+it decides the whole cast in ONE batched GPU call per turn, memoized by turn
+number, and keeps each creature's raw reasoning text for trace inspection
+(the Sharing-is-Caring badge and the UI's clickable monologue).
+"""
+
+from __future__ import annotations
+
+from .actions import ACTION_SCHEMA_PROMPT, Gossip, Offer, parse_actions
+from .world import FOOD_GOODS, GOODS, Creature, WorldState, fuel_need
+
+
+def build_messages(world: WorldState, creature: Creature) -> list[dict]:
+    """Construct the chat prompt that lets one creature decide this turn."""
+    prices = ", ".join(f"{g} {world.last_price[g]:.0f}p" for g in GOODS)
+    inv = ", ".join(f"{g}:{creature.inventory.get(g, 0)}" for g in GOODS)
+    rumors = "; ".join(world.rumors[-3:]) or "none"
+    foods = ", ".join(FOOD_GOODS)
+    fuel = fuel_need(world.turn + 1)  # what they'll have to burn after this turn
+
+    system = (
+        f"You are {creature.name}, {creature.persona}. You live in Thousand Token "
+        f"Wood, where creatures trade goods for pebbles. You produce {creature.produces}. "
+        f"Stay in character and trade to serve your own interests."
+    )
+    lacking = [
+        g for g in FOOD_GOODS if g != creature.produces and creature.inventory.get(g, 0) < 2
+    ]
+    lacking_str = ", ".join(lacking) if lacking else "none"
+    user = (
+        f"Turn {world.turn}.\n"
+        f"Market prices (pebbles per unit): {prices}.\n"
+        f"Your purse: {creature.pebbles} pebbles. Your stores: {inv}.\n"
+        f"You PRODUCE {creature.produces}, so you have plenty of it: SELL your surplus "
+        f"{creature.produces}, never buy it.\n"
+        f"To eat well you need {creature.food_need} DIFFERENT foods each turn ({foods}). "
+        f"You are currently low on: {lacking_str}. BUY the foods you lack.\n"
+        f"You must also burn {fuel} firewood each turn to stay warm; firewood grows "
+        f"scarce as winter deepens.\n"
+        f"Perishable food rots if hoarded, so sell surplus before it spoils.\n"
+        f"Recent rumors in the wood: {rumors}.\n\n"
+        + ACTION_SCHEMA_PROMPT
+        + '\n\nExample (a honey-maker low on acorns and firewood): '
+        '{"thought":"sell my honey, buy what I lack","offers":['
+        '{"side":"sell","good":"honey","price":9,"qty":3},'
+        '{"side":"buy","good":"acorns","price":4,"qty":2},'
+        '{"side":"buy","good":"firewood","price":6,"qty":2}],"gossip":""}'
+    )
+    return [
+        {"role": "system", "content": system},
+        {"role": "user", "content": user},
+    ]
+
+
+def make_llm_policy(client, temperature: float = 0.7, max_tokens: int = 256):
+    """Build a Policy backed by `client.chat_batch`.
+
+    The cache holds one turn's batched decisions. The first creature queried in a
+    turn triggers the batch for everyone; the rest read from cache. `last_raw`
+    and `last_messages` are exposed for trace export and debugging.
+    """
+    state = {"turn": -1, "decisions": {}, "raw": {}, "messages": {}}
+
+    def policy(world: WorldState, name: str) -> tuple[list[Offer], list[Gossip]]:
+        if state["turn"] != world.turn:
+            names = [c.name for c in world.alive()]
+            convos = [build_messages(world, world.creatures[n]) for n in names]
+            raw = client.chat_batch(convos, max_tokens=max_tokens, temperature=temperature)
+            state["turn"] = world.turn
+            state["raw"] = dict(zip(names, raw))
+            state["messages"] = dict(zip(names, convos))
+            state["decisions"] = {n: parse_actions(n, r) for n, r in zip(names, raw)}
+        return state["decisions"].get(name, ([], []))
+
+    policy.state = state  # type: ignore[attr-defined]  # for trace inspection
+    return policy

ttw/dummy.py

@@ -0,0 +1,42 @@
+"""A no-LLM policy for testing the engine.
+
+Each creature sells some surplus of the good it produces (near the reference
+price) and bids for a bit of food it is short on. Deterministic given a seeded
+RNG, so tests are reproducible. This stands in for the small-model policy and
+lets us validate the market in isolation.
+"""
+
+from __future__ import annotations
+
+import random
+
+from .actions import Gossip, Offer
+from .world import FOOD_GOODS, WorldState
+
+
+def make_random_policy(seed: int = 0):
+    rng = random.Random(seed)
+
+    def policy(world: WorldState, name: str) -> tuple[list[Offer], list[Gossip]]:
+        c = world.creatures[name]
+        offers: list[Offer] = []
+        ref = world.last_price
+
+        # Sell surplus of own product, slightly under/over the reference price.
+        own = c.produces
+        surplus = max(0, c.inventory.get(own, 0) - 2)
+        if surplus > 0:
+            ask = max(1, int(round(ref[own] * rng.uniform(0.9, 1.15))))
+            offers.append(Offer(name, "sell", own, ask, rng.randint(1, surplus)))
+
+        # Buy a food it is low on (not its own product), if it can afford some.
+        wants = [g for g in FOOD_GOODS if g != own and c.inventory.get(g, 0) < 3]
+        if wants and c.pebbles > 0:
+            good = rng.choice(wants)
+            bid = max(1, int(round(ref[good] * rng.uniform(0.95, 1.2))))
+            max_qty = max(1, c.pebbles // max(bid, 1))
+            offers.append(Offer(name, "buy", good, bid, rng.randint(1, min(4, max_qty))))
+
+        return offers, []
+
+    return policy

ttw/events.py

@@ -0,0 +1,110 @@
+"""Wood Legends: famous market manias and panics, reskinned as woodland chapters.
+
+Each event is a whimsical retelling of a real episode from economic history,
+composed from the shock primitives in shocks.py. A randomized deck draws them as
+"chapters" so every playthrough tells a different (but historically-rooted)
+story. The `inspired_by` field is real and surfaced by the UI as a reveal -- the
+delight comes from recognizing the history under the fur.
+
+Tone guardrail: famous *economic* dramas only (bubbles, runs, corners, famines),
+told gently. No real tragedies or living people.
+"""
+
+from __future__ import annotations
+
+import random
+from dataclasses import dataclass
+from typing import Callable
+
+from . import shocks
+from .world import WorldState
+
+
+@dataclass
+class WoodEvent:
+    key: str
+    title: str  # the woodland legend's name
+    flavor: str  # in-tone narration shown to the player
+    inspired_by: str  # the real episode (revealed by the UI / Field Notes)
+    apply: Callable[[WorldState, random.Random], None]
+
+
+def _acorn_mania(world: WorldState, rng: random.Random) -> None:
+    shocks.gold_rush(world, amount=30)  # easy pebbles light the fuse
+    shocks.plant_rumor(world, "a single acorn will soon buy a whole burrow -- buy now or miss out forever!")
+
+
+def _hollow_log_company(world: WorldState, rng: random.Random) -> None:
+    shocks.gold_rush(world, amount=25)
+    shocks.plant_rumor(world, "the Hollow Log Trading Company promises tenfold pebbles to every backer!")
+
+
+def _run_on_oonas_hoard(world: WorldState, rng: random.Random) -> None:
+    shocks.plant_rumor(world, "whispers say Oona's great pebble-hoard is empty; pull your pebbles while you can!")
+
+
+def _firewood_hoarding_panic(world: WorldState, rng: random.Random) -> None:
+    shocks.drought(world, "firewood", severity=0.3)
+    shocks.plant_rumor(world, "stock up on firewood NOW -- there will be none left by the frost!")
+
+
+def _honey_corner(world: WorldState, rng: random.Random) -> None:
+    shocks.bountiful_harvest(world, "honey", qty=0)  # no windfall; just the tale
+    shocks.plant_rumor(world, "a sly buyer is quietly cornering every drop of honey in the wood.")
+
+
+def _long_frost(world: WorldState, rng: random.Random) -> None:
+    crop = rng.choice(["acorns", "berries", "mushrooms"])
+    shocks.drought(world, crop, severity=0.2)
+    shocks.plant_rumor(world, f"a long frost has gripped the {crop} groves; the harvest will be meager.")
+
+
+EVENTS: list[WoodEvent] = [
+    WoodEvent("acorn_mania", "The Great Acorn Mania",
+              "A fever sweeps the wood: everyone must own acorns at any price.",
+              "Tulip Mania, Netherlands 1637", _acorn_mania),
+    WoodEvent("hollow_log_company", "The Hollow Log Trading Company",
+              "A dazzling venture promises riches to all who buy in.",
+              "The South Sea Bubble, England 1720", _hollow_log_company),
+    WoodEvent("run_on_hoard", "The Run on Oona's Hoard",
+              "Fear spreads that the old owl's vault has run dry, and the wood rushes to withdraw.",
+              "The bank runs of 1929-1933", _run_on_oonas_hoard),
+    WoodEvent("firewood_panic", "The Firewood Hoarding Panic",
+              "A scramble for firewood empties every woodpile overnight.",
+              "The 2020 toilet-paper shortage", _firewood_hoarding_panic),
+    WoodEvent("honey_corner", "The Honey Corner",
+              "One cunning creature schemes to buy up all the honey and name its price.",
+              "The Hunt brothers' silver corner, 1980", _honey_corner),
+    WoodEvent("long_frost", "The Long Frost",
+              "A bitter frost settles over the groves and the harvest withers.",
+              "The Dust Bowl famine, 1930s USA", _long_frost),
+]
+
+
+class EventDeck:
+    """Draws Wood Legends at random without repeating until the deck is exhausted."""
+
+    def __init__(self, seed: int = 0, events: list[WoodEvent] | None = None):
+        self.rng = random.Random(seed)
+        self._all = list(events if events is not None else EVENTS)
+        assert self._all, "EventDeck needs at least one event"
+        self._pool = list(self._all)
+
+    def draw(self, world: WorldState) -> WoodEvent:
+        """Pick an unused event, apply its effects to the world, log it, return it."""
+        if not self._pool:  # reshuffle once every legend has been told
+            self._pool = list(self._all)
+        event = self.rng.choice(self._pool)
+        self._pool.remove(event)
+        event.apply(world, self.rng)
+        world.log.append(
+            {
+                "type": "event",
+                "turn": world.turn,
+                "key": event.key,
+                "title": event.title,
+                "flavor": event.flavor,
+                "inspired_by": event.inspired_by,
+            }
+        )
+        return event

ttw/game.py

@@ -0,0 +1,113 @@
+"""Game: the stateful session the Gradio UI drives.
+
+Wraps the world, the agent policy, and the Wood Legends deck, and records the
+time-series the charts need. Pure Python with no Gradio import, so it can be
+unit-tested headlessly (and run with the dummy policy, no GPU). The UI calls
+step / shocks / tempt_fate and then reads the *_frame / *_markdown accessors.
+"""
+
+from __future__ import annotations
+
+import pandas as pd
+
+from . import narrate, shocks
+from .actions import _extract_json
+from .events import EventDeck
+from .market import gini
+from .sim import step
+from .world import GOODS, seed_world
+
+
+class Game:
+    def __init__(self, policy, deck_seed: int = 0):
+        self.policy = policy
+        self.deck = EventDeck(seed=deck_seed)
+        self.world = seed_world()
+        self.price_hist: list[dict] = []
+        self.gini_hist: list[dict] = []
+        self.ticker: list[str] = []
+        self.thoughts: dict[str, str] = {}
+        self._record()  # baseline at turn 0
+
+    # --- mutation -----------------------------------------------------------
+    def step(self) -> None:
+        events = step(self.world, self.policy)
+        self._extract_thoughts()
+        self.ticker.extend(narrate.ticker_lines(events, limit=50))
+        self.ticker = self.ticker[-200:]
+        self._record()
+
+    def tempt_fate(self) -> str:
+        """Draw a Wood Legend; its effects land on the NEXT step. Returns its title."""
+        legend = self.deck.draw(self.world)
+        self.ticker.append(
+            f"✨ {legend.title}: {legend.flavor} (inspired by {legend.inspired_by})"
+        )
+        return legend.title
+
+    def shock(self, kind: str, **kw) -> None:
+        """Fire a player shock and echo it to the ticker."""
+        fn = {
+            "drought": shocks.drought,
+            "gold_rush": shocks.gold_rush,
+            "rumor": shocks.plant_rumor,
+            "harvest": shocks.bountiful_harvest,
+        }.get(kind)
+        if fn is None:
+            raise ValueError(f"unknown shock kind: {kind!r}")
+        event = fn(self.world, **kw)
+        line = narrate.narrate(event)
+        if line:
+            self.ticker.append(line)
+
+    # --- recording ----------------------------------------------------------
+    def _record(self) -> None:
+        t = self.world.turn
+        for good in GOODS:
+            self.price_hist.append({"turn": t, "good": good, "price": self.world.last_price[good]})
+        nets = [c.net_worth(self.world.last_price) for c in self.world.alive()]
+        self.gini_hist.append({"turn": t, "gini": round(gini(nets), 3)})
+
+    def _extract_thoughts(self) -> None:
+        # Duck-typed contract: an LLM policy may expose `.state["raw"]` mapping
+        # creature name -> raw model text, from which we pull the "thought" field.
+        # The dummy policy has no such attribute, so traces stay empty (no crash).
+        state = getattr(self.policy, "state", None)
+        if not state or "raw" not in state:
+            return
+        for name, raw in state["raw"].items():
+            parsed = _extract_json(raw) or {}
+            thought = parsed.get("thought")
+            if isinstance(thought, str) and thought.strip():
+                self.thoughts[name] = thought.strip()
+
+    # --- views for the UI ---------------------------------------------------
+    def price_frame(self) -> pd.DataFrame:
+        return pd.DataFrame(self.price_hist, columns=["turn", "good", "price"])
+
+    def gini_frame(self) -> pd.DataFrame:
+        return pd.DataFrame(self.gini_hist, columns=["turn", "gini"])
+
+    def town_frame(self) -> pd.DataFrame:
+        rows = []
+        for c in sorted(self.world.alive(), key=lambda x: -x.net_worth(self.world.last_price)):
+            rows.append(
+                {
+                    "creature": c.name,
+                    "makes": c.produces,
+                    "pebbles": c.pebbles,
+                    "mood": narrate.mood_word(c.wellbeing),
+                    "net worth": round(c.net_worth(self.world.last_price)),
+                }
+            )
+        return pd.DataFrame(rows, columns=["creature", "makes", "pebbles", "mood", "net worth"])
+
+    def traces_markdown(self) -> str:
+        if not self.thoughts:
+            return "_Run a turn to hear what the creatures are thinking._"
+        return "\n\n".join(f"**{name}:** {thought}" for name, thought in self.thoughts.items())
+
+    def ticker_markdown(self, limit: int = 14) -> str:
+        if not self.ticker:
+            return "_The wood is quiet. Press Step to begin._"
+        return "\n\n".join(f"- {line}" for line in self.ticker[-limit:][::-1])

ttw/llm.py

@@ -0,0 +1,28 @@
+"""Client handles for the small model.
+
+ModalLLM calls the deployed `ttw-serve` vLLM endpoint (used by both the local
+driver and the Gradio Space). The interface is a single `chat_batch` so callers
+never care where inference runs.
+"""
+
+from __future__ import annotations
+
+
+class ModalLLM:
+    """Thin handle to the deployed Modal Engine.chat_batch method."""
+
+    def __init__(self, app_name: str = "ttw-serve", cls_name: str = "Engine"):
+        import modal
+
+        engine_cls = modal.Cls.from_name(app_name, cls_name)
+        self._engine = engine_cls()
+
+    def chat_batch(
+        self,
+        conversations: list[list[dict]],
+        max_tokens: int = 256,
+        temperature: float = 0.7,
+    ) -> list[str]:
+        return self._engine.chat_batch.remote(
+            conversations, max_tokens=max_tokens, temperature=temperature
+        )

ttw/market.py

@@ -0,0 +1,156 @@
+"""The market engine: a per-turn double auction. No LLM, fully deterministic.
+
+Given a list of Offers, match crossing buy/sell intents good-by-good, execute
+trades with integer pebble accounting, and update the reference price. Honors
+the hard constraints (you cannot sell what you do not hold, cannot buy what you
+cannot afford), so the simulation can never reach an invalid state regardless
+of what the agents propose.
+"""
+
+from __future__ import annotations
+
+from collections import defaultdict
+
+from .actions import Offer
+from .world import WorldState
+
+# Price dynamics: how hard supply/demand imbalance pushes the reference price,
+# and the band it lives in. PRICE_DRIFT_K=0.12 means a fully one-sided book
+# (all buys, no sells) moves a price ~12% that turn -> trends/bubbles compound.
+PRICE_DRIFT_K = 0.12
+MIN_PRICE = 1.0
+MAX_PRICE = 99.0
+
+
+def clear_market(world: WorldState, offers: list[Offer]) -> list[dict]:
+    """Match offers and mutate `world` in place. Returns structured trade events.
+
+    Matching rule per good: highest buy meets lowest sell; they trade while the
+    buy price covers the sell price. Execution price is the midpoint (rounded),
+    a simple fair split of the spread. Partial fills are allowed.
+    """
+    events: list[dict] = []
+
+    for good in _goods_in(offers):
+        buys = sorted(
+            (o for o in offers if o.good == good and o.side == "buy"),
+            key=lambda o: (-o.price, o.creature),
+        )
+        sells = sorted(
+            (o for o in offers if o.good == good and o.side == "sell"),
+            key=lambda o: (o.price, o.creature),
+        )
+
+        bi = si = 0
+        while bi < len(buys) and si < len(sells):
+            buy, sell = buys[bi], sells[si]
+            if buy.creature == sell.creature:  # don't trade with yourself
+                si += 1
+                continue
+            if buy.price < sell.price:  # no longer crossing; market clears
+                break
+
+            buyer = world.creatures[buy.creature]
+            seller = world.creatures[sell.creature]
+            price = (buy.price + sell.price) // 2
+
+            # Quantity is bounded by both sides' remaining intent, the seller's
+            # actual stock, and what the buyer can actually pay for.
+            affordable = buyer.pebbles // price if price > 0 else 0
+            qty = min(buy.qty, sell.qty, seller.inventory.get(good, 0), affordable)
+
+            if qty <= 0:
+                # Retire every side whose constraint is actually binding. A
+                # buyer who cannot afford one unit at this clearing price cannot
+                # afford a higher one (sells ascend), so retiring the buyer is
+                # safe. A seller out of stock or out of intent is retired as a
+                # seller. Both can bind at once; advancing both is still correct
+                # and guarantees forward progress without relying on sort luck.
+                advanced = False
+                if seller.inventory.get(good, 0) <= 0 or sell.qty <= 0:
+                    si += 1
+                    advanced = True
+                if buy.qty <= 0 or affordable <= 0:
+                    bi += 1
+                    advanced = True
+                if not advanced:  # defensive: should be unreachable, never spin
+                    bi += 1
+                continue
+
+            cost = price * qty
+            buyer.pebbles -= cost
+            seller.pebbles += cost
+            seller.inventory[good] = seller.inventory.get(good, 0) - qty
+            buyer.inventory[good] = buyer.inventory.get(good, 0) + qty
+            world.last_price[good] = float(price)
+
+            events.append(
+                {
+                    "type": "trade",
+                    "turn": world.turn,
+                    "good": good,
+                    "buyer": buyer.name,
+                    "seller": seller.name,
+                    "price": price,
+                    "qty": qty,
+                }
+            )
+
+            buy.qty -= qty
+            sell.qty -= qty
+            if buy.qty == 0:
+                bi += 1
+            if sell.qty == 0:
+                si += 1
+
+    world.log.extend(events)
+    return events
+
+
+def _goods_in(offers: list[Offer]) -> list[str]:
+    """Distinct goods present in the offer set, in stable order."""
+    seen: list[str] = []
+    for o in offers:
+        if o.good not in seen:
+            seen.append(o.good)
+    return seen
+
+
+def drift_prices(world: WorldState, offers: list[Offer]) -> None:
+    """Nudge each good's reference price toward its RESIDUAL supply/demand pressure.
+
+    Call this AFTER clear_market, which decrements offer quantities in place as it
+    fills them. So the imbalance measured here is the *unfilled* intent left over:
+    a good whose book crossed evenly leaves ~0 residual and barely moves, while a
+    panic (demand far above available supply) leaves heavy unfilled buys and the
+    price climbs. Pressure is normalized to [-1, 1] (all-residual-buys -> up by
+    PRICE_DRIFT_K, all-residual-sells -> down). Goods with no leftover intent are
+    untouched. Clamped to [MIN_PRICE, MAX_PRICE]. This is exactly the dynamic we
+    want: prices trend during scarcity/gluts, stay calm in balanced trade.
+    """
+    demand: dict[str, int] = defaultdict(int)
+    supply: dict[str, int] = defaultdict(int)
+    for o in offers:
+        (demand if o.side == "buy" else supply)[o.good] += o.qty
+
+    for good, price in world.last_price.items():
+        d, s = demand.get(good, 0), supply.get(good, 0)
+        if d + s == 0:
+            continue
+        pressure = (d - s) / (d + s)
+        new_price = price * (1 + PRICE_DRIFT_K * pressure)
+        world.last_price[good] = round(min(MAX_PRICE, max(MIN_PRICE, new_price)), 1)
+
+
+def gini(values: list[float]) -> float:
+    """Gini coefficient of a list of net worths. 0 = equal, ->1 = unequal.
+
+    Used for the wealth-inequality chart. Returns 0.0 for trivial inputs.
+    """
+    xs = sorted(max(v, 0.0) for v in values)
+    n = len(xs)
+    total = sum(xs)
+    if n == 0 or total == 0:
+        return 0.0
+    cumulative = sum((i + 1) * x for i, x in enumerate(xs))
+    return (2 * cumulative) / (n * total) - (n + 1) / n

ttw/narrate.py

@@ -0,0 +1,66 @@
+"""Turn structured event dicts into charming, in-tone ticker lines.
+
+Pure formatting: takes the event records produced by sim.step / shocks / the
+event deck and returns short strings for the UI ticker. No state, no LLM.
+"""
+
+from __future__ import annotations
+
+# wellbeing -> mood word. Ranges are inclusive-low, exclusive-high; together they
+# cover the full reachable wellbeing domain [4, 10] with no gaps:
+# 9-10 content, 7-8 alright, 5-6 uneasy, 0-4 miserable.
+_MOODS = {
+    range(9, 11): "content",
+    range(7, 9): "alright",
+    range(5, 7): "uneasy",
+    range(0, 5): "miserable",
+}
+
+
+def mood_word(wellbeing: int) -> str:
+    for span, word in _MOODS.items():
+        if wellbeing in span:
+            return word
+    return "uneasy"
+
+
+def narrate(event: dict) -> str | None:
+    """One ticker line for an event, or None for events we don't surface."""
+    kind = event["type"]
+    if kind == "trade":
+        return (
+            f"{event['buyer']} bought {event['qty']} {event['good']} "
+            f"from {event['seller']} at {event['price']}p."
+        )
+    if kind == "gossip":
+        return f"{event['creature']} whispers: “{event['message']}”"
+    if kind == "event":  # a Wood Legend
+        return f"✨ {event['title']}: {event['flavor']} (inspired by {event['inspired_by']})"
+    if kind == "shock":
+        return _narrate_shock(event)
+    if kind == "hunger":
+        return f"{event['creature']} went hungry (short {event['shortfall']} food)."
+    if kind == "cold":
+        return f"{event['creature']} shivered (short {event['shortfall']} firewood)."
+    return None  # ate / warm / spoil / etc. are too noisy for the ticker
+
+
+def _narrate_shock(event: dict) -> str | None:
+    kind = event.get("kind")
+    if kind == "drought":
+        return f"A drought grips the {event['good']} groves."
+    if kind == "lift_drought":
+        return f"The {event['good']} groves recover."
+    if kind == "rumor":
+        return f"A rumor spreads: “{event['message']}”"
+    if kind == "gold_rush":
+        return f"A pebble windfall! Every creature finds {event['amount']} pebbles."
+    if kind == "harvest":
+        return f"A bountiful harvest of {event['good']}!"
+    return None
+
+
+def ticker_lines(events: list[dict], limit: int = 12) -> list[str]:
+    """Most-recent-first narrated lines for a batch of events."""
+    lines = [s for e in events if (s := narrate(e)) is not None]
+    return lines[-limit:]

ttw/shocks.py

@@ -0,0 +1,53 @@
+"""Player-triggered shocks: the levers that turn a quiet market into a story.
+
+Each shock mutates the world directly and appends a log event the narrator/UI
+can surface. Kept pure and side-effect-local so the Gradio buttons (later) are
+one-liners.
+"""
+
+from __future__ import annotations
+
+from .world import FOOD_GOODS, WorldState
+
+
+def drought(world: WorldState, good: str, severity: float = 0.4) -> dict:
+    """Cut a good's production to `severity` of normal (0.4 = 60% loss) until lifted."""
+    if good in world.production_mult:
+        world.production_mult[good] = severity
+    event = {"type": "shock", "turn": world.turn, "kind": "drought", "good": good, "severity": severity}
+    world.log.append(event)
+    return event
+
+
+def lift_drought(world: WorldState, good: str) -> dict:
+    world.production_mult[good] = 1.0
+    event = {"type": "shock", "turn": world.turn, "kind": "lift_drought", "good": good}
+    world.log.append(event)
+    return event
+
+
+def plant_rumor(world: WorldState, message: str) -> dict:
+    """Inject a rumor every creature will see next turn. The player's mischief."""
+    world.rumors.append(message.strip()[:200])
+    event = {"type": "shock", "turn": world.turn, "kind": "rumor", "message": message.strip()[:200]}
+    world.log.append(event)
+    return event
+
+
+def gold_rush(world: WorldState, amount: int = 40) -> dict:
+    """Shower pebbles on the whole wood -> a burst of demand and inflation."""
+    for c in world.alive():
+        c.pebbles += amount
+    event = {"type": "shock", "turn": world.turn, "kind": "gold_rush", "amount": amount}
+    world.log.append(event)
+    return event
+
+
+def bountiful_harvest(world: WorldState, good: str, qty: int = 8) -> dict:
+    """Dump a windfall of one food onto every creature -> a price collapse."""
+    target = good if good in FOOD_GOODS else FOOD_GOODS[0]
+    for c in world.alive():
+        c.inventory[target] = c.inventory.get(target, 0) + qty
+    event = {"type": "shock", "turn": world.turn, "kind": "harvest", "good": target, "qty": qty}
+    world.log.append(event)
+    return event

ttw/sim.py

@@ -0,0 +1,138 @@
+"""The tick loop: production, agent decisions, market clearing, eat/burn/spoil.
+
+`step` is agnostic to *how* agents decide. It takes a `policy` callable that,
+given the world and a creature, returns that creature's (offers, gossip). A
+dummy random policy proves the engine; the small-model policy drops in with the
+same signature.
+
+Turn order: produce -> decide -> trade -> eat (varied diet) -> burn firewood ->
+spoilage. Eat/burn/spoil run after trade so a creature can trade its way out of
+a shortfall within the same turn.
+"""
+
+from __future__ import annotations
+
+import math
+from typing import Callable
+
+from .actions import Gossip, Offer
+from .market import clear_market, drift_prices
+from .world import (
+    FOOD_GOODS,
+    FUEL_GOOD,
+    MAX_FOOD_PER_GOOD,
+    SPOIL_RATE,
+    WorldState,
+    fuel_need,
+)
+
+Policy = Callable[[WorldState, str], "tuple[list[Offer], list[Gossip]]"]
+
+
+def step(world: WorldState, policy: Policy) -> list[dict]:
+    """Advance the wood by one turn. Returns the turn's event log."""
+    world.turn += 1
+    events: list[dict] = []
+
+    # 1. Production, scaled by any active supply shock (drought -> mult < 1).
+    for c in world.alive():
+        mult = world.production_mult.get(c.produces, 1.0)
+        made = int(round(c.production_rate * mult))
+        c.inventory[c.produces] = c.inventory.get(c.produces, 0) + made
+
+    # 2. Decisions: gather everyone's offers and gossip for this turn.
+    all_offers: list[Offer] = []
+    for c in world.alive():
+        offers, gossip = policy(world, c.name)
+        all_offers.extend(offers)
+        for g in gossip:
+            world.rumors.append(g.message)
+            events.append({"type": "gossip", "turn": world.turn, "creature": c.name, "message": g.message})
+
+    # 3. Market clears, then the reference price drifts with supply/demand pressure
+    #    so prices actually trend (bubbles, crashes) instead of staying frozen.
+    #    clear_market consumes all_offers' quantities in place, so drift_prices
+    #    sees only the RESIDUAL unfilled intent (the real scarcity signal).
+    events.extend(clear_market(world, all_offers))
+    drift_prices(world, all_offers)
+
+    # 4. Eat a varied diet, then burn firewood for warmth. Wellbeing is a
+    #    real-time MOOD (mean-reverting, floored) reflecting this turn's comfort,
+    #    not a death counter -- a well-fed, warm creature brightens; a short one
+    #    sours, but nobody starves to zero.
+    for c in world.alive():
+        eat_ev = _eat(c, world.turn)
+        burn_ev = _burn_fuel(c, world.turn)
+        _update_mood(c, eat_ev.get("shortfall", 0), burn_ev.get("shortfall", 0))
+        events.append(eat_ev)
+        events.append(burn_ev)
+
+    # 5. Spoilage: perishable food rots (firewood, being fuel, does not).
+    for c in world.alive():
+        spoiled = _spoil(c)
+        if spoiled:
+            events.append({"type": "spoil", "turn": world.turn, "creature": c.name, "lost": spoiled})
+
+    world.rumors = world.rumors[-8:]
+    world.log.extend(e for e in events if e["type"] in ("gossip", "hunger", "cold", "spoil"))
+    return events
+
+
+def _eat(creature, turn: int) -> dict:
+    """Eat `food_need` units, at most MAX_FOOD_PER_GOOD of any one food -> needs variety.
+
+    Consumes inventory and reports any shortfall. Does NOT touch wellbeing;
+    mood is updated once per turn by _update_mood.
+    """
+    need = creature.food_need
+    eaten: dict[str, int] = {}
+    for good in FOOD_GOODS:
+        if need <= 0:
+            break
+        take = min(creature.inventory.get(good, 0), MAX_FOOD_PER_GOOD, need)
+        if take > 0:
+            creature.inventory[good] -= take
+            eaten[good] = take
+            need -= take
+    if need > 0:
+        return {"type": "hunger", "turn": turn, "creature": creature.name, "shortfall": need}
+    return {"type": "ate", "turn": turn, "creature": creature.name, "eaten": eaten}
+
+
+def _burn_fuel(creature, turn: int) -> dict:
+    """Burn the turn's firewood need, reporting any shortfall. Does not touch mood."""
+    need = fuel_need(turn)
+    have = creature.inventory.get(FUEL_GOOD, 0)
+    burned = min(have, need)
+    creature.inventory[FUEL_GOOD] = have - burned
+    short = need - burned
+    if short > 0:
+        return {"type": "cold", "turn": turn, "creature": creature.name, "shortfall": short}
+    return {"type": "warm", "turn": turn, "creature": creature.name, "burned": burned}
+
+
+def _update_mood(creature, food_short: int, fuel_short: int) -> None:
+    """Drift wellbeing one step toward a comfort target set by this turn's provisioning.
+
+    A creature that ate well and stayed warm trends to 10; each kind of shortfall
+    lowers the target by 3 (floor 4). Because it mean-reverts one step per turn,
+    wellbeing is a mood that recovers, never a death spiral. Range stays [4, 10].
+    """
+    penalty = (1 if food_short > 0 else 0) + (1 if fuel_short > 0 else 0)
+    target = 10 - 3 * penalty
+    if creature.wellbeing < target:
+        creature.wellbeing = min(target, creature.wellbeing + 1)
+    elif creature.wellbeing > target:
+        creature.wellbeing = max(target, creature.wellbeing - 1)
+
+
+def _spoil(creature) -> dict[str, int]:
+    """Rot a fraction of each perishable food held. Returns {good: units_lost}."""
+    lost: dict[str, int] = {}
+    for good in FOOD_GOODS:
+        have = creature.inventory.get(good, 0)
+        rot = math.floor(have * SPOIL_RATE)
+        if rot > 0:
+            creature.inventory[good] = have - rot
+            lost[good] = rot
+    return lost

ttw/world.py

@@ -0,0 +1,132 @@
+"""World state: goods, creatures, and the shape of the wood.
+
+Pure data + construction + the economy's tuning constants (its source of truth).
+No market logic, no LLM. Pebbles are the integer currency; goods are integer
+quantities, so conservation invariants are easy to assert in tests.
+
+The economy is built around engineered scarcity so trade never dries up:
+  - DIET VARIETY: you can eat only MAX_FOOD_PER_GOOD of any single food toward a
+    meal, so surviving means acquiring foods you do not grow yourself.
+  - SPOILAGE: perishable foods rot each turn, punishing hoarding and forcing
+    surplus to be sold while it is still worth something.
+  - WINTER FUEL: every creature must burn firewood each turn and the need rises,
+    but only one creature makes firewood -> a deepening fuel crisis.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+GOODS: list[str] = ["acorns", "berries", "mushrooms", "honey", "firewood"]
+FOOD_GOODS: list[str] = ["acorns", "berries", "mushrooms", "honey"]
+FUEL_GOOD: str = "firewood"
+
+# --- Economy tuning (the numbers that shape behavior; change them here only) ---
+# Calibrated so the wood pressures trade hard but is survivable: in a 20-turn
+# run most creatures should live, with 1-2 collapses for drama, not a total
+# die-off. Iteration 1 (need=3, ramp=5, spoil=0.25) killed everyone.
+SPOIL_RATE = 0.20  # fraction of each perishable food lost to rot per turn (floored)
+MAX_FOOD_PER_GOOD = 1  # diet variety: units of one food that count toward a meal
+FUEL_NEED_BASE = 1  # firewood every creature burns per turn at the start
+FUEL_RAMP_EVERY = 8  # +1 to the per-turn firewood need every N turns (winter deepens)
+
+
+def fuel_need(turn: int) -> int:
+    """How much firewood each creature must burn on a given turn (rises with winter)."""
+    return FUEL_NEED_BASE + turn // FUEL_RAMP_EVERY
+
+
+@dataclass
+class Creature:
+    """One woodland agent: an identity, a purse, a larder, and a job."""
+
+    name: str
+    persona: str  # short personality, used to prompt the small model
+    pebbles: int  # currency on hand
+    inventory: dict[str, int]  # good -> quantity held
+    produces: str  # the one good this creature makes each turn
+    production_rate: int  # units produced per turn
+    food_need: int  # food units it must eat per turn (across varied foods)
+    wellbeing: int = 10  # flavor/health; drops when it cannot eat or stay warm
+    memory: list[str] = field(default_factory=list)  # recent events, grudges
+
+    def net_worth(self, prices: dict[str, float]) -> float:
+        """Pebbles plus inventory marked at current prices. For the wealth chart."""
+        goods_value = sum(qty * prices.get(g, 0.0) for g, qty in self.inventory.items())
+        return self.pebbles + goods_value
+
+
+@dataclass
+class WorldState:
+    """Everything that changes turn to turn."""
+
+    turn: int
+    creatures: dict[str, Creature]
+    last_price: dict[str, float]  # last traded price per good (moving reference)
+    production_mult: dict[str, float] = field(default_factory=dict)  # 1.0; <1 in a drought
+    rumors: list[str] = field(default_factory=list)  # active rumors agents can hear
+    log: list[dict] = field(default_factory=list)  # structured event records
+
+    def alive(self) -> list[Creature]:
+        return list(self.creatures.values())
+
+
+def seed_world() -> WorldState:
+    """The starting cast of Thousand Token Wood.
+
+    Each creature grows one good and is therefore short on everything else it
+    must eat, plus the firewood everyone needs. Inventories are lean so trade
+    starts on turn one. Pip alone makes firewood, which winter slowly makes scarce.
+    """
+    creatures = {
+        "Mossback": Creature(
+            name="Mossback",
+            persona="a slow, steady tortoise farmer who grows acorns and distrusts hype",
+            pebbles=40,
+            inventory={"acorns": 6, "berries": 2, "mushrooms": 2, "honey": 0, "firewood": 4},
+            produces="acorns",
+            production_rate=4,
+            food_need=2,
+        ),
+        "Bramble": Creature(
+            name="Bramble",
+            persona="an anxious squirrel hoarder obsessed with stockpiling for winter",
+            pebbles=55,
+            inventory={"acorns": 2, "berries": 6, "mushrooms": 2, "honey": 0, "firewood": 4},
+            produces="berries",
+            production_rate=4,
+            food_need=2,
+        ),
+        "Fenn": Creature(
+            name="Fenn",
+            persona="a sly fox speculator who buys fear, sells greed, and spreads rumors",
+            pebbles=85,
+            inventory={"acorns": 2, "berries": 2, "mushrooms": 6, "honey": 1, "firewood": 3},
+            produces="mushrooms",
+            production_rate=4,
+            food_need=2,
+        ),
+        "Oona": Creature(
+            name="Oona",
+            persona="a cautious owl who lends pebbles and prizes a fat reserve over risk",
+            pebbles=120,
+            inventory={"acorns": 1, "berries": 1, "mushrooms": 2, "honey": 6, "firewood": 4},
+            produces="honey",
+            production_rate=3,
+            food_need=2,
+        ),
+        "Pip": Creature(
+            name="Pip",
+            persona="a jittery mouse who copies the crowd, panics easily, and chops the wood's firewood",
+            pebbles=50,
+            inventory={"acorns": 2, "berries": 2, "mushrooms": 1, "honey": 1, "firewood": 8},
+            produces="firewood",
+            production_rate=6,
+            food_need=2,
+        ),
+    }
+    last_price = {"acorns": 4.0, "berries": 5.0, "mushrooms": 6.0, "honey": 9.0, "firewood": 5.0}
+    production_mult = {g: 1.0 for g in GOODS}
+    return WorldState(
+        turn=0, creatures=creatures, last_price=last_price, production_mult=production_mult
+    )