docs: Field Notes dev-log (earns the 📓 badge)

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

FIELD_NOTES.md

@@ -0,0 +1,179 @@
+# Field Notes — Building *Hollow*
+
+> 🍄 **Build Small Hackathon** · Track: *An Adventure in Thousand Token Wood*
+> A horror NPC that asks for your memories, then claims them as its own.
+> Live: https://huggingface.co/spaces/build-small-hackathon/hollow
+
+These are the field notes — the honest dev log. What I set out to build, the
+decisions that mattered, and the bugs that taught me something. Written so the
+next person doesn't have to relearn them the hard way.
+
+---
+
+## The idea
+
+A lost child stands at the edge of the wood. It has no memories of its own, so
+it asks for yours. You give it one — a fear, a person, a place — and it keeps it
+in a "treasure". Turns later it does the unsettling thing: it recites your memory
+back **in the first person**, as if it had always been its own. That moment — the
+**recall** — is the whole pitch. Everything else exists to earn it and to give it
+weight.
+
+How you *treat* the child while you feed it branches three endings:
+
+- **Redemption** — sustained warmth gives it back its own buried past; it
+  confesses what it is, returns your memories, and leaves in peace.
+- **Visitor Loop** — fed plenty but treated like a diary, it stays a predator,
+  consumes you, and the last line of the game is *you* speaking its opening line.
+- **Wound Loop** — sustained cruelty; it has been quietly keeping every cruel
+  thing you said, and recites them back, un-redacted.
+
+The horror isn't a jump-scare. It's that the thing in the fog becomes more *you*
+the more of yourself you hand over.
+
+---
+
+## Constraints shaped everything
+
+The hackathon's spirit is *small*: a model ≤32B, runnable by anyone. That single
+constraint drove most of the architecture.
+
+- **Model: `Qwen/Qwen3-8B`.** Transformers + ZeroGPU on the Space, the same model
+  via Ollama locally. One code path, switched on `bool(os.environ.get("SPACE_ID"))`.
+- **No cloud APIs, no fine-tuning, no vector DB, no LangGraph.** The "memory" is a
+  plain dict in Gradio's `gr.State`; extraction is one deterministic JSON call per
+  turn parsed with Pydantic.
+- **Pure CSS, no JavaScript.** Gradio Blocks for the whole UI. This turned out to
+  be the most interesting constraint of all (see the heartbeat story below).
+
+### Why not a bigger model (Gemma 4 12B)?
+
+I seriously considered jumping to a 12B model for more "presence". I didn't, and
+I'm glad. A 12B in 4-bit doesn't comfortably fit the 8 GB of local VRAM I was
+testing on, the tooling was a week old, and every extra billion params is slower
+inference — which on ZeroGPU means *less* of the judges' daily quota per playthrough.
+Worst of all, swapping the model meant re-tuning the brittle parts (the JSON
+extraction, the recall thresholds) for zero narrative upside. Qwen3-8B already
+nailed the in-character voice. The lesson: **the model was never the bottleneck —
+the prompt design and the state machine were.**
+
+---
+
+## The parts that fought back
+
+### 1. A single `+` froze the entire game
+
+Each turn, a second model call extracts a small JSON: `affinity_delta`,
+`new_memories`, `tone_delta`, `cruel_quote`. Early on, the bond meter simply
+*never moved* on positive turns. The model was emitting `"affinity_delta": +2` —
+a leading `+`, which is **invalid JSON**. Every positive turn silently fell back
+to delta 0, so the bond froze and nothing was ever captured.
+
+Fix: a sanitizer that strips leading `+` before parsing, an explicit "never write
+a leading + sign" instruction in the prompt, *and* dual worked examples (one
+positive, one negative) so the model has a positive anchor. All three together —
+removing any one re-introduced the bug intermittently.
+
+### 2. Hollow started reciting its own words
+
+The recall is the star, and it nearly ate itself. On a recall turn, Hollow retells
+your memory in the first person. The extraction step would then grab *that line*
+as a brand-new "memory", store it, and recall it again next time — a feedback loop
+where the child slowly converged on repeating one self-referential sentence forever.
+
+Fix, in two layers: the extraction prompt is told to take memories **only** from
+what the visitor said, never from Hollow's reply; and `apply_update` drops any
+candidate memory whose token overlap with Hollow's own reply is >60%. Plus a
+`repetition_penalty` on the reply generation (only the reply — extraction stays
+deterministic at temperature 0). Belt and suspenders, and both earn their keep.
+
+### 3. ZeroGPU does not like threads
+
+The obvious way to keep the UI responsive during generation is a worker thread.
+On ZeroGPU this quietly breaks: `@spaces.GPU` needs the main request context, and
+a thread pool severs it. So the "Hollow is thinking…" animation had to be
+something that needs no thread at all — which is why the typing dots are pure CSS.
+Related: do all the GPU work (reply + extraction) inside a **single** `@spaces.GPU`
+acquisition per turn, or you pay the cold-start twice.
+
+### 4. A heartbeat that loops, with no JavaScript
+
+For the endings I wanted a heartbeat pounding under the child's final monologue,
+then a climax sound — a scream, a sigh, a flatline. But Gradio **replaces the DOM
+on every component update**, so an `<audio autoplay>` *restarts* on every streamed
+step. That's actually the trick behind the one-shot scare flashes — but it's death
+for a continuous heartbeat.
+
+The way out: Gradio **does not re-send a component whose value is byte-identical**
+to the previous frame. So during the finale's "build" phase the entity panel emits
+the exact same HTML — including a single `<audio loop>` heartbeat — across many
+streamed steps. Gradio sees no change, never remounts it, and the heartbeat plays
+unbroken. The instant the climax changes the HTML, the heartbeat element vanishes
+and the climax sound takes its place. A continuous looping bed, zero JavaScript,
+falling straight out of how the framework already works.
+
+### 5. Making the final image land without a "pop"
+
+Each ending's portrait convulses through faces and settles on a final one. The
+first cut had a visible *pop*: the convulsion would end on the blurred smudge, then
+the final face would snap in a frame later. Fixing it meant adding a "settle-face"
+layer that fades the final image in over the last 40% of the convulsion and holds
+it (CSS `animation-fill-mode: forwards`). The settle render is then the *same frame*
+already on screen — seamless. The climax sound is moved onto that settle so it lands
+exactly when the face does, not a beat early.
+
+### 6. The CSS harness lies
+
+More than once I "verified" CSS in a static test harness and shipped something
+broken, because the harness lacks Gradio's real cascade. The only reliable check is
+to launch the actual app, screenshot it headless, and look. `prefers-reduced-motion`
+bit me too: disabling *opacity* animations there once silently killed the terror
+flash, because the flash *is* an opacity animation. Now reduced-motion only stops
+ambient drift, never the scares.
+
+### 7. You can't commit a `.wav` to a Space
+
+Hugging Face rejects raw binary audio. So nothing is committed — every sound
+(heartbeat, sigh, flatline, the scream sting, the music-box chimes) is **synthesized
+in NumPy at import time** and base64-inlined into the HTML. The whole soundscape is
+a few hundred lines of `sin`, envelopes, and `tanh` soft-clipping. Same rule would
+apply to any new binary that isn't an image.
+
+---
+
+## Tuning the pacing against the real model
+
+Thresholds for the endings (how warm is "warm enough"?) can't be guessed — the
+model's behavior is the ground truth. So I wrote a small simulator that drives
+scripted visitors (a warm one, a transactional one, a cruel one) through the *real*
+Ollama model and reports per-turn affinity, tone, and captures. That's how the gates
+got set: warm play climbs tone to ~27, transactional play stalls near ~13, so the
+redemption/loop split sits cleanly at 20. The cruel ending fires around message 6,
+warm redemption around 10, the visitor loop around 12. None of those numbers are
+invented — they're measured.
+
+---
+
+## What I'd tell myself on day one
+
+- **The constraint is the design.** "≤32B, no JS, no binaries" sounds limiting and
+  was actually generative — the heartbeat trick only exists *because* of the no-JS
+  rule.
+- **Determinism where it counts.** The reply can be warm and surprising; the
+  extraction must be boring and exact. Splitting temperature by purpose fixed a
+  whole class of flakiness.
+- **Verify against the thing that runs**, not the thing that's convenient to test.
+- **Small, scripted, no-GPU finales** mean the emotional climax is rock-solid and
+  costs nothing — the model does the improv, the script does the payoff.
+
+---
+
+## Badges pursued
+
+- 🔌 **Off-the-Grid** — runs entirely on a local/open model (Qwen3-8B), no external APIs.
+- 🎨 **Off-Brand** — bespoke grayscale Fear-&-Hunger-style portraits and a fully
+  custom horror UI; nothing looks like a default Gradio app.
+- 📓 **Field Notes** — this document.
+
+Thanks for reading. If you play it: be kind to the thing in the fog. Or don't.
+It remembers either way.