ARCHITECTURE.md

# GODSEED — Architecture Contract (v1, June 12 2026)

> **This file is the single source of truth for the parallel build.** Every builder agent reads this
> FIRST and writes ONLY the files it owns (see File Ownership). Interface drift gets fixed by the
> integrator — but don't create drift: when in doubt, follow the schemas here exactly.

## One-liner

Type a wish → a tiny Nemotron god *plans aloud* and terraforms ONE persistent WebGL planet shared by
every visitor. Tagline: **"Nine billion parameters. One shared world."**
Track: 🍄 Thousand Token Wood. Hackathon: Build Small (Gradio + HF). Deadline June 15.

Awards targeted: NVIDIA team-judged RTX 5080 (Nemotron load-bearing), Best Agent (visible
plan-act-observe + published traces), Bonus Quest (6/6 badges), Modal slot (LoRA), TTW podium,
Community Choice (shared world farms likes), Judges' Wildcard.

## Non-negotiable design rules

1. **The "her" pattern** (org-celebrated judge taste): the deterministic engine owns ALL world
   state and facts. The LLM only interprets the wish, narrates, and picks tool calls from a small
   DSL. The LLM never computes geometry, never owns state.
2. **One wish at a time.** A single serialized queue. Visitors see their queue position. Latency is
   reframed as liturgical pacing ("the god grants one wish at a time").
3. **The landing page must be gorgeous with ZERO GPU.** The planet renders client-side from the
   world-state JSON. Live inference is the second act. Judges often evaluate while GPUs sleep.
4. **Determinism end-to-end.** Every feature carries a seed; the renderer is a pure function of the
   ordered feature list. This makes the Genesis Log replay (see below) free.
5. **Moderation before execution.** One swastika-shaped forest during judging week ends every award.
6. **Models ≤32B total params** (hard hackathon rule). Only ONE model in the app.
7. **NAMING:** the wish archive page is called **"Genesis Log"** — NOT "Book of Wishes". A rival
   space (aether-garden) shipped a "Book of Ages" on June 11; avoid any perceived imitation. Also
   avoid the words "remember/remembers" in copy — that's their tagline. Our frame: *creation*, not
   memory. The god *makes*; it does not reminisce.

## Repo layout & FILE OWNERSHIP (critical — do not touch files you don't own)

```
godseed/
  ARCHITECTURE.md        (this file — read-only for everyone)
  app.py                 ← AGENT B (server)
  requirements.txt       ← AGENT B
  README.md              ← AGENT B (HF Space card w/ full YAML tags)
  Dockerfile.fallback    ← AGENT B (in case sdk:gradio health-check fails)
  server/                ← AGENT B  (sse.py, persistence.py, schemas.py, ratelimit.py)
  engine/                ← AGENT A  (world.py, tools.py, queue_worker.py, moderation.py, summary.py, genesis.py)
  mind/                  ← AGENT C  (planner.py, backends.py, prompts.py, grammar.gbnf, mock_scripts.py)
  web/                   ← AGENT D  (index.html, style.css, main.js, book.html, planet/*.js, lib/ vendored three.js, mock/)
  tests/                 ← test_engine.py (A), test_api.py (B), test_mind.py (C)
  tools/                 ← AGENT D  (shot.mjs — headless screenshot harness, adapted from glassblower)
  traces/                (runtime output — wishes.jsonl; gitkeep only)
```

Reference code to LIFT (read these, reuse patterns):
- `/Users/andrescarreon/Documents/dev/buildsmall/glassblower/app.py` — FastAPI + mount_gradio_app +
  StaticFiles + SSE with `X-Accel-Buffering: no` header. Proven pattern.
- `/Users/andrescarreon/Documents/dev/buildsmall/glassblower/web/main.js` + `web/lib/` — Three.js
  setup, vendored libs, postprocessing/bloom wiring.
- `/Users/andrescarreon/Documents/dev/buildsmall/glassblower/tools/shot.mjs`, `shot-live.mjs` —
  headless Playwright screenshot harness.
- Glassblower renderer learnings (hard-won): **low transmission + strong emissive** for visible
  glowing material (full glass transmission reads as invisible); **selective bloom threshold ≈0.66**;
  **decouple sim from rAF** with fixed-step `seek()`/`tick()` (headless Chromium throttles rAF).

## World model

The world is an **append-only ordered list of Features**. World-at-epoch-N = features[0..N). The
renderer derives ALL geometry deterministically from this list. Sky/weather are last-write-wins
(but still stored as features so replay works).

### Feature (canonical JSON)

```json
{"id": "f_000017", "wish_id": "w_000005", "tool": "spawn_flora",
 "args": {"lat": 12.0, "lon": 40.0, "radius_deg": 8, "kind": "glowgrass", "density": 0.7, "hue": 160},
 "seed": 1830293847, "t": 1718200000.0}
```

`seed` is assigned by the engine: `seed = crc32(f"{wish_id}:{call_index}") & 0x7fffffff`. The JS
renderer uses the same seed with mulberry32 for all scatter/noise decisions of that feature.

### Tool DSL — 11 tools (GBNF-friendly: flat args, numbers + enums + short strings)

> The base table below is the original 9; the City Update added `spawn_life` and the Town Mode
> update added `build_district` + `place_road` (full specs in those sections). The live surface is
> **11 tools** — see `engine/tools.py` (`TOOL_NAMES`) for the source of truth.

| tool | args (ranges clamped by engine) |
|---|---|
| `raise_terrain` | `lat` −85..85, `lon` −180..180, `radius_deg` 2..45, `height` 0.01..0.12 (planet radii), `roughness` 0..1 |
| `lower_terrain` | `lat`, `lon`, `radius_deg` 2..45, `depth` 0.01..0.10, `roughness` 0..1 |
| `spawn_flora` | `lat`, `lon`, `radius_deg` 1..30, `kind` ∈ trees\|glowgrass\|mushrooms\|vines\|flowers\|reeds, `density` 0..1, `hue` 0..360 |
| `place_structure` | `lat`, `lon`, `kind` ∈ lighthouse\|monolith\|shrine\|village\|beacon\|arch\|tower\|warehouse\|cafe, `scale` 0.5..2.0, `hue` 0..360 |
| `place_water` | `kind` ∈ stream\|pool, `path` [[lat,lon] ×1..5] (stream: 2..5 waypoints, becomes glowing spline on the surface — NOT carved; pool: path[0] center), `radius_deg` 1..10 (pool only), `hue` 160..260 |
| `set_weather` | `kind` ∈ clear\|rain\|snow\|embers\|mist\|storm, `intensity` 0..1 |
| `set_sky` | `palette` ∈ dawn\|dusk\|night\|aurora\|ember\|void\|gold, `star_density` 0..1, `moons` 0..3 |
| `inscribe_wish` | `text` ≤90 chars (the wish, possibly poeticized), `style` ∈ orbit\|stone |
| `spawn_life` | `lat`, `lon`, `radius_deg` 1..20, `kind` ∈ carts\|birds\|fireflies, `count` 1..12 (integer), `hue` 0..360 |

Engine **clamps** out-of-range numbers (doesn't reject) and rejects only unknown tools/enums with a
terse observation string the model can react to.

### Genesis state (epoch 0 — MUST match between engine and renderer mock)

```json
[
 {"id":"f_000000","wish_id":"genesis","tool":"set_sky","args":{"palette":"void","star_density":0.9,"moons":1},"seed":7,"t":0},
 {"id":"f_000001","wish_id":"genesis","tool":"raise_terrain","args":{"lat":12,"lon":40,"radius_deg":28,"height":0.05,"roughness":0.7},"seed":11,"t":0},
 {"id":"f_000002","wish_id":"genesis","tool":"place_structure","args":{"lat":14,"lon":38,"kind":"monolith","scale":1.4,"hue":270},"seed":13,"t":0},
 {"id":"f_000003","wish_id":"genesis","tool":"inscribe_wish","args":{"text":"speak, and it will be made","style":"orbit"},"seed":17,"t":0}
]
```

A barren obsidian world, one monolith, an orbiting invitation. Gorgeous and zero-GPU by design.

## Agent protocol (the Mind)

Real plan-act-observe loop (Best Agent evidence), GBNF/JSON-constrained:

1. **Reading** (free-text generation, streamed token-by-token, ≤80 tokens): the god interprets the
   wish aloud — mood, intent, plan sketch. This is the "plans aloud" wow moment.
2. **Turn loop** (grammar-constrained JSON, max 7 turns). Each turn the model emits exactly one of:
   - `{"thought": "≤160 chars", "call": {"tool": "...", "args": {...}}}`
   - `{"thought": "≤160 chars", "done": true, "epitaph": "≤120 chars"}`
   After each call the engine returns a terse observation (`"ok: mountains risen at (12,40)"` /
   `"rejected: unknown kind 'cactus'"`) which is appended to the context before the next turn.

Planner interface (AGENT C implements; AGENT A's queue worker drives it):

```python
class Planner:
    async def grant(self, wish: str, world_summary: str,
                    act: Callable[[dict], Awaitable[str]],   # executes a tool call, returns observation
                    emit: Callable[[dict], Awaitable[None]]  # streams SSE events (thought_token, etc.)
                    ) -> WishTrace
```

Backends behind `GODSEED_BACKEND` env (mind/backends.py):
- `mock` — deterministic keyword→plan scripts with seeded variety + artificial token delays. Local
  dev + headless demos. Must exercise every tool.
- `llamacpp` — llama-cpp-python, **NVIDIA Nemotron-3-Nano-4B GGUF Q4_K_M** (~2.5GB, fits free 16GB
  CPU tier), native GBNF grammar. This is the v0 SHIP backend (earns Off the Grid + Llama Champion
  badges; real model, no GPU bill). Model path via `GODSEED_GGUF` env; download in code from HF hub
  if missing.
- `zerogpu` — transformers + `@spaces.GPU`, **NVIDIA Nemotron-Nano-9B-v2** (the LIVE backend;
  in-tree nemotron_h class, trust_remote_code=False, kernel-free native Mamba-2 path). Constrained
  decoding via prompt + JSON validation + 1 retry (no GBNF in transformers; keep a strict parser).
  NOTE (June 12): the Nemotron-3 4B/30B repos hard-require remote code + mamba-ssm kernels, which
  cannot import on the ZeroGPU image — they are NOT usable on this backend.

Moderation (engine/moderation.py, AGENT A): layered — (1) charset/length limits (≤140 chars,
printable); (2) wordlist/regex for slurs, sexual content, hate symbols; (3) LLM yes/no judgment via
the same backend (grammar-constrained `{"allowed": bool, "category": "..."}`), **default-deny on
uncertainty or parse failure**. Rejections are poetic but final ("The god declines this wish.").

## Queue

`engine/queue_worker.py` (AGENT A): single global asyncio worker. `submit(text, client_id) →
(wish_id, position)`. Caps: 1 pending wish per client, 3/hour per client (B's ratelimit.py supplies
client_id from cookie+IP hash), queue max 50 ("the god is overwhelmed; return at dusk"). Worker:
pop → moderate → planner.grant() → persist trace → emit `wish_granted`.

## SSE protocol (server/sse.py — single `/api/stream` broadcast to all clients)

```
{type:"hello", world_version, epoch}
{type:"queue", length, current: {wish_id, text_preview} | null}
{type:"wish_started", wish_id, text}
{type:"thought_token", wish_id, text}            ← streamed reading + turn thoughts
{type:"tool_call", wish_id, call_index, tool, args}
{type:"world_delta", feature: {…Feature…}}        ← renderer applies live
{type:"wish_granted", wish_id, epitaph, epoch}
{type:"wish_rejected", wish_id, reason}
{type:"heartbeat"}                                ← every 15s
```

Set `X-Accel-Buffering: no` on the SSE response (proven necessary on Spaces — see glassblower).

## HTTP API (app.py, AGENT B)

```
GET  /api/state        → {world: {version, epoch, features:[...]}, queue: {...}, wishes_recent:[...]}
POST /api/wish {text}  → {wish_id, position}  (400 w/ poetic reason if moderation fast-path rejects)
GET  /api/stream       → SSE
GET  /api/wishes       → [{wish_id, text, epitaph, epoch, ts}]      (Genesis Log index)
GET  /api/wishes/{id}  → full WishTrace (for deterministic replay)
GET  /            → web/index.html   (StaticFiles)
GET  /book        → web/book.html
/panel            → minimal gr.Blocks mounted via mount_gradio_app (satisfies "Gradio app" rule:
                    altar console — submit a wish, view raw world JSON, link to traces dataset)
```

`app.py` must work under plain `python app.py` (uvicorn.run, port = `$PORT` or 7860) — HF sdk:gradio
runs the script directly. ZeroGPU REQUIRES sdk:gradio, so make this work; Dockerfile.fallback is
break-glass only.

### WishTrace (persisted, one JSONL line per granted wish → traces/wishes.jsonl)

```json
{"wish_id":"w_000005","text":"...","submitted_at":0,"moderation":{"allowed":true,"category":null},
 "reading":"...","turns":[{"thought":"...","call":{...}|null,"observation":"..."}],
 "epitaph":"...","feature_ids":["f_000017"],"model":"...","backend":"llamacpp","ms_total":48211}
```

Persistence (server/persistence.py, AGENT B): rebuild world from JSONL on boot (genesis + every
trace's features). After each granted wish: append JSONL; push `traces/wishes.jsonl` to an HF
dataset repo (`HF_TOKEN` + `GODSEED_DATASET` envs; skip silently if unset — local dev). The dataset
IS the persistence across Space restarts (download on boot if local file missing) AND the Sharing
is Caring badge AND Best Agent evidence.

## Renderer (web/, AGENT D — the WOW is here; budget most effort)

Three.js (vendor from glassblower web/lib). Composition:
- **Planet**: icosphere (subdiv ~6), vertex displacement = sum of feature gaussians (raise/lower)
  modulated by seeded noise × roughness. On `world_delta`, lerp the displacement in over ~2s
  (terrain visibly *rises*). Obsidian-dark base material, biome tinting near flora.
- **Flora**: InstancedMesh per kind, emissive, seeded scatter within radius_deg, scale-in animation
  staggered by seeded delay. Glowgrass = shader points; trees/mushrooms = low-poly kit.
- **Water**: TubeGeometry along great-circle spline through waypoints, emissive glow (low
  transmission + emissive — glass learnings), gentle flow shader. Pools = glowing discs w/ ripple.
- **Structures**: small low-poly procedural kit (lighthouse with rotating beam, monolith, shrine,
  village cluster w/ lit windows, beacon, arch), emissive accents.
- **Weather**: GPU particles (rain streaks / snow / embers / mist planes / storm = rain+flashes).
- **Sky**: palette-driven gradient + stars (Points, density param) + 0..3 moons + aurora bands
  (palette `aurora`). Background environment affects planet lighting tint.
- **Inscriptions**: `orbit` = glowing text ring slowly orbiting (canvas texture on curved plane);
  `stone` = text plaque at lat/lon.
- **Bloom**: UnrealBloomPass, selective, threshold ≈0.66. Cap pixelRatio ≤2. Must hold ~60fps on a
  laptop, degrade gracefully on phones (reduce instances/subdiv).
- **The god's gaze**: on `tool_call`, camera eases to the target lat/lon, then resumes slow
  auto-orbit. This is the demo money-shot.
- **Sim/replay core**: fixed-step `tick()`/`seek(t)` decoupled from rAF (headless-safe, makes
  Genesis Log replay + demo capture free).

UI (index.html): full-bleed canvas. Wordmark "GODSEED" (letterspaced display serif — e.g. Cormorant
Garamond via Google Fonts), thin HUD: wish input ("make a wish"), queue chip ("3rd in line · the god
grants one wish at a time"), thought ticker (mono font, streaming), epoch counter ("Epoch 17 · 23
wishes granted"). Deep-space black, gold/violet accents. NO generic AI-gradient-purple-on-dark-card
look — aim for liturgical-modern, like a Kinfolk issue about a small god. Footer: "Genesis Log" link.

book.html (Genesis Log): list of granted wishes (epitaphs); click one → replay THAT wish: render
world at features[0..K), then animate wish K's deltas with its recorded thoughts replayed in the
ticker. Pure client-side from `/api/wishes/{id}`. Zero GPU. Shareable URL `#w_000005`.

`web/mock/` : a static mock world JSON (genesis + ~10 varied wishes exercising ALL 8 tools) + a
scripted SSE-like event feed (JS array) so the renderer is fully developable + screenshottable with
NO backend: `python3 -m http.server 8123 --directory web` + `?mock=1`.
**AGENT D self-verifies**: adapt glassblower `tools/shot.mjs`, screenshot at multiple sim times,
LOOK at the PNGs, iterate until genuinely beautiful. Don't ship the first thing that renders.

## Local dev

- Python 3.12 venv via uv (`uv venv -p 3.12 .venv && uv pip install -r requirements.txt`).
  System 3.14 is too new for the ML stack.
- `GODSEED_BACKEND=mock PORT=7891 .venv/bin/python app.py`
- requirements.txt: keep base CPU-light (fastapi, uvicorn, gradio, pydantic, huggingface_hub,
  llama-cpp-python). torch/transformers/spaces go in a clearly-marked ZeroGPU block (commented or
  extras) until the benchmark decision.

## City Update (v1.1 contract — June 12 PM)

Player-requested ("building games": cafeterias, big buildings, warehouses, cars).
Three additions, same diorama soul. Backwards compatible: old features render
unchanged; additions are additive enums + ONE new tool (copy that says "exactly
8 tools" must be updated to 9 everywhere: README, ARCHITECTURE intro, prompts).

1. **New structure kinds** (place_structure enum += `tower`, `warehouse`, `cafe`):
   - `tower` — tall slender multi-tier block, dense lit windows, slow-pulsing
     rooftop light. The "big building".
   - `warehouse` — long low gabled hall, one big glowing door, sparse windows.
   - `cafe` — small warm box: awning plane, spill of warm light on the ground,
     2-3 tiny table dots outside. Hue tints the glow.
   All three: low-poly procedural kit pieces matching existing style (emissive
   accents, seeded variation), instanced where possible.

2. **New tool #9 `spawn_life`** — moving inhabitants:
   `{lat, lon, radius_deg 1..20, kind: carts|birds|fireflies, count 1..12, hue 0..360}`
   - `carts` — tiny lantern-cart sprites that GLIDE along the nearest stream
     path within radius (fallback: a seeded loop around the anchor). Distant
     traffic at dusk. Speed slow, constant, sim-time driven.
   - `birds` — a small flock circuiting above the terrain at low altitude,
     seeded loop, slight bob.
   - `fireflies` — drifting glow points inside the radius, near the ground.
   Renderer: new `web/planet/life.js`, instanced, deterministic seeded paths
   driven by tick(simTime) (replay-safe, headless-safe). Engine: spec + clamps
   in tools.py; features append-only as usual. GBNF grammar + mock scripts +
   tool docs must all gain the tool (docs auto-render from as_dict ✓).

3. **Cinematic descent** ("visit it"):
   - `rig.descend(targetDir, {duration})` — swoop from orbit to ~1.06R above
     ground (clears terrain via the analytic height fn), slow 20-30° glide arc
     over the target with gentle look-ahead, then ease back to orbit. Fully
     sim-time deterministic.
   - Triggers: a "descend" link on the epitaph card after a wish is granted
     (targets the wish's last landed feature), and on Genesis Log replays after
     the final delta. ESC / click cancels. No free controls, no collision —
     it's camera liturgy, not an FPS.

Build ownership when this ships: (A) engine/tools.py + mind/grammar.gbnf +
mind/mock_scripts.py + tests; (B) web/planet/structures.js (new kinds only);
(C) web/planet/life.js + web/planet/camera.js + main.js/book.js descend hooks.
Copy updates (README 8→9 tools etc.) ride with (A).

## Town Mode (v1.2 contract — June 12 PM, "Town on the planet")

User feedback: a city wish produced one tower on the far side of a planet-sized sphere → reads empty.
The fix is a deliberate experience shift: the DEFAULT view is a town you build up close (SimCity feel);
the full planet becomes the dramatic zoom-out reveal. Append-only world preserved; genesis UNCHANGED
(the live shared world must keep rebuilding identically). All additive.

### The town anchor (engine + renderer compute IDENTICALLY)
`townCenter(world)` = the seeded-weighted centroid (unit-vector mean, renormalized) of all
`place_structure` + `build_district` feature directions, EXCLUDING genesis. Fallback when none exist:
the genesis monolith at lat 14, lon 38. Engine exposes it in the world summary; the renderer uses it
for the default camera. A town gets a deterministic name from `crc32(round(lat),round(lon))` → a small
curated name list (e.g. "Lowmere", "Ashford", "Tessen") so the summary + HUD can say "the town of X".

### Density comes from each tool call, not from many (the 9B reliably plans only ~2-3 calls)
New tools (now **11** — update every "9 tools" copy → 11; list build_district + place_road):
| tool | args |
|---|---|
| `build_district` | `lat`,`lon`,`radius_deg` 2..15, `density` 0..1, `hue` 0..360 — renderer places a SEEDED neighborhood: a cluster of small houses on a rough grid, footpath/road connectors between them, and 1 occasional civic building. ONE successful call = a visible block. This is the SimCity unlock. |
| `place_road` | `path` [[lat,lon] ×2..6] — a paved, faintly-lit road spline laid ON the surface; visually DISTINCT from `place_water` glowing streams (warm stone/amber, matte, dashed centerline feel — not emissive cyan). |

`place_structure.kind` enum += `bank`, `market`, `house` (single landmark homes/civic buildings; the
existing low-poly kit conventions). Full set: lighthouse|monolith|shrine|village|beacon|arch|tower|
warehouse|cafe|bank|market|house.

### Steering the god to GROW THE TOWN (mind/prompts.py + engine/summary.py)
- summary.py: name the town + its center + building count ("The town of Lowmere stands near (14,38):
  3 towers, a café, 12 houses."). When the wish asks for buildings/a city, the god should ADD to the
  existing town, not scatter — build near townCenter, connect with `place_road`, and reach for
  `build_district` for neighborhoods. Persona gains: "You are growing one town. New buildings rise
  beside the old ones, linked by roads — never alone in the wilderness."
- This is steering, not enforcement (keeps the "god decides" purity). The camera following density
  means even a stray build is visible; over wishes the town concentrates.

### Camera = two modes (web/planet/camera.js + main.js)
- **TOWN view (DEFAULT on load):** camera sits LOW and close, framing a ~28° cap around townCenter —
  buildings read large, like standing over a model town. This is what visitors see first now (not the
  full orbit).
- **WORLD view (the reveal):** a HUD control "behold the world ↕" eases out to the full-planet orbit
  (today's gorgeous wide shot) and back. The demo money-move: build the town, then pull back to show
  it's one patch on a shared planet.
- On each `world_delta`/grant, frame the new feature WITHIN the town zoom (don't fly to the far limb).
- The existing descent stays (epitaph card) — now it descends within the town.

### Tame the god-needle
The orbital "god instrument" needle currently dominates the frame (huge gold double-cone). In TOWN
view it must be small/high or hidden; show it prominently only during active granting (it "writes" the
wish) and in WORLD view. Scale it down ~60% at rest.

### Ownership for the Town Mode build
- ENGINE+MIND (A): engine/tools.py (build_district, place_road, +3 structure kinds), engine/summary.py
  (town name+center+counts), engine/world.py (_observation for new tools), mind/grammar.gbnf,
  mind/mock_scripts.py (town-growth scripts), mind/prompts.py (grow-the-town steering + 11-tool copy),
  tests; README/ARCHITECTURE 9→11 copy.
- RENDERER (B): web/planet/structures.js (bank/market/house kit), web/planet/district.js (NEW —
  seeded house+road neighborhood), web/planet/roads.js (NEW — paved road splines) OR fold roads into
  water.js styling, web/planet/world.js wiring, needle scale-down (find it — likely sky.js or scene.js).
- CAMERA+HUD (C): web/planet/camera.js (TOWN/WORLD modes + townCenter framing), web/main.js + book.js
  (default TOWN view, "behold the world" toggle, frame-within-town on delta), web/index.html +
  style.css (the toggle control). townCenter helper shared via web/planet/util.js.

## Deploy plan (not in this build phase — for context)

1. Personal benchmark Space first: llamacpp 4B on free CPU + (separately) ZeroGPU 30B-A3B; measure
   tok/s before committing the headline backend.
2. Org Space `build-small-hackathon/godseed`, sdk:gradio. README YAML: full track + sponsor + badge
   tags (copy exact tag strings from case0/her READMEs — AGENT B: fetch
   `https://huggingface.co/spaces/build-small-hackathon/case0/raw/main/README.md` and mirror tag style).
3. v0 ships TONIGHT (June 12) on llamacpp 4B. Social + like-farming starts immediately.