FIELD_NOTES.md

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