PAREIDOLIA v0 — everything secretly has a face

.gitattributes

@@ -33,3 +33,46 @@ saved_model/**/* filter=lfs diff=lfs merge=lfs -text
 *.zip filter=lfs diff=lfs merge=lfs -text
 *.zst filter=lfs diff=lfs merge=lfs -text
 *tfevents* filter=lfs diff=lfs merge=lfs -text
+mind/mock_assets/grudge.wav filter=lfs diff=lfs merge=lfs -text
+seeds/eval/armchair.jpg filter=lfs diff=lfs merge=lfs -text
+seeds/eval/coffee_mug.jpg filter=lfs diff=lfs merge=lfs -text
+seeds/eval/exercise_bike.jpg filter=lfs diff=lfs merge=lfs -text
+seeds/eval/fire_hydrant.jpg filter=lfs diff=lfs merge=lfs -text
+seeds/eval/garden_gnome.jpg filter=lfs diff=lfs merge=lfs -text
+seeds/eval/mailbox.jpg filter=lfs diff=lfs merge=lfs -text
+seeds/eval/park_bench.jpg filter=lfs diff=lfs merge=lfs -text
+seeds/eval/payphone.jpg filter=lfs diff=lfs merge=lfs -text
+seeds/eval/potted_plant.jpg filter=lfs diff=lfs merge=lfs -text
+seeds/eval/stand_mixer.jpg filter=lfs diff=lfs merge=lfs -text
+seeds/eval/stapler.jpg filter=lfs diff=lfs merge=lfs -text
+seeds/eval/traffic_cone.jpg filter=lfs diff=lfs merge=lfs -text
+seeds/records/seed_armchair.jpg filter=lfs diff=lfs merge=lfs -text
+seeds/records/seed_armchair.wav filter=lfs diff=lfs merge=lfs -text
+seeds/records/seed_coffee_mug.jpg filter=lfs diff=lfs merge=lfs -text
+seeds/records/seed_coffee_mug.wav filter=lfs diff=lfs merge=lfs -text
+seeds/records/seed_fire_hydrant.jpg filter=lfs diff=lfs merge=lfs -text
+seeds/records/seed_fire_hydrant.wav filter=lfs diff=lfs merge=lfs -text
+seeds/records/seed_garden_gnome.jpg filter=lfs diff=lfs merge=lfs -text
+seeds/records/seed_garden_gnome.wav filter=lfs diff=lfs merge=lfs -text
+seeds/records/seed_mailbox.jpg filter=lfs diff=lfs merge=lfs -text
+seeds/records/seed_mailbox.wav filter=lfs diff=lfs merge=lfs -text
+seeds/records/seed_park_bench.jpg filter=lfs diff=lfs merge=lfs -text
+seeds/records/seed_park_bench.wav filter=lfs diff=lfs merge=lfs -text
+seeds/records/seed_payphone.jpg filter=lfs diff=lfs merge=lfs -text
+seeds/records/seed_payphone.wav filter=lfs diff=lfs merge=lfs -text
+seeds/records/seed_potted_plant.jpg filter=lfs diff=lfs merge=lfs -text
+seeds/records/seed_potted_plant.wav filter=lfs diff=lfs merge=lfs -text
+seeds/records/seed_stand_mixer.jpg filter=lfs diff=lfs merge=lfs -text
+seeds/records/seed_stand_mixer.wav filter=lfs diff=lfs merge=lfs -text
+seeds/records/seed_stapler.jpg filter=lfs diff=lfs merge=lfs -text
+seeds/records/seed_stapler.wav filter=lfs diff=lfs merge=lfs -text
+seeds/records/seed_toaster.wav filter=lfs diff=lfs merge=lfs -text
+seeds/records/seed_traffic_cone.jpg filter=lfs diff=lfs merge=lfs -text
+seeds/records/seed_traffic_cone.wav filter=lfs diff=lfs merge=lfs -text
+web/mock/life-dev.wav filter=lfs diff=lfs merge=lfs -text
+web/mock/photos/m1.jpg filter=lfs diff=lfs merge=lfs -text
+web/mock/photos/m2.jpg filter=lfs diff=lfs merge=lfs -text
+web/mock/photos/m3.jpg filter=lfs diff=lfs merge=lfs -text
+web/mock/photos/m5.jpg filter=lfs diff=lfs merge=lfs -text
+web/mock/photos/m6.jpg filter=lfs diff=lfs merge=lfs -text
+web/mock/photos/m7.jpg filter=lfs diff=lfs merge=lfs -text

FIELD_NOTES.md

@@ -0,0 +1,150 @@
+# 👁️ PAREIDOLIA — Field Notes
+
+*Build log for the Build Small Hackathon (Thousand Token Wood). Started June 12, 2026.*
+
+## The idea, and why this shape
+
+Pareidolia is the thing your brain does when it finds a face in a power outlet, a
+church facade, the front of a Jeep. Everyone has it. No app celebrates it.
+
+So: point your camera at any object. A small vision model — **MiniCPM-V-4_5, 8.7B**
+— looks at the photo the way you do at clouds: it *names the features that were
+already there* ("the two bonnet bolts", "the front outlet cap") and decides what
+they are — eyes, a mouth. It reads the object's condition (rusted, pristine,
+dusty, abandoned) and writes it a soul to match. Then **VoxCPM2, 2.29B** gives it
+a voice — designed from a text description, no reference audio — and the object
+tells you, specifically, what it has been putting up with.
+
+A fire hydrant that has been on the same corner for forty years has *opinions*.
+
+## Small models used smartly (the part we care about)
+
+The org's favorite pattern — deterministic code owns the facts, the tiny model
+owns the taste — is load-bearing here, twice:
+
+1. **The VLM never emits final pixel coordinates.** No VLM is trained to locate
+   face-like features in faceless objects; raw-coordinate eye placement misfires,
+   and a misplaced eye reads as a broken sticker instead of a discovered soul.
+   So MiniCPM-V *names* existing visual features and gives coarse normalized
+   hints; classical OpenCV (Hough circles, blob centroids, corner anchors, a
+   pair-coherence rule) snaps them to the strongest real anchor nearby. Taste
+   from the model, facts from the code. The mist-emergence animation forgives
+   the remaining ±15%.
+2. **One generation, no second opinion round-trip.** The séance prompt asks for a
+   *critique-then-final* JSON in a single call — the model second-guesses its own
+   feature choices and line specificity inside one generation. Halves latency;
+   the séance theater carries the rest.
+
+And the writing is governed, not vibes: an 8–12 **grudge-archetype bank keyed to
+object condition** (the_veteran/rusted, the_martyr/worn, the_perfectionist/
+pristine, the_diva/loved…), an iron rule that every line must reference a
+*visible specific* of THIS photo, validators for the rules a regex can hold
+(length, banned openers), and a hard ship-gate: a human must actually laugh at
+≥6 of 12 eval objects, or the prompt iterates before anything else gets polished.
+
+## Architecture in one diagram
+
+```
+phone camera ──► client downscale (≤1024px JPEG)
+      │
+      ▼  browser calls the gradio endpoint itself (@gradio/client)
+@app.api("awaken")        ── one @spaces.GPU window, visitor's own quota ──┐
+      │   MiniCPM-V-4_5: gate → features (named, coarse) → persona → lines │
+      │   OpenCV: snap features to real anchors (deterministic)            │
+      │   VoxCPM2: voice-design TTS for the grudge line                    │
+      ◄────────────────────────────────────────────────────────────────────┘
+      ▼
+the LIFE engine (client SVG): mist → eyes of the photo's own palette →
+first blink → saccades, pupil-follow → mouth rides the wav's amplitude
+      ▼
+"add to the menagerie?" ──► persisted record + image + voice →
+shared wall every visitor sees, alive with ZERO GPU → HF dataset (public)
+```
+
+The Space *opens* on the Menagerie — every awakened object blinking and
+glancing around, overlays rendered client-side from persisted JSON — so the
+landing state is fully alive even when ZeroGPU is asleep or queued. Live
+awakening is the second act, billed to the visitor's own quota (the "her"
+browser-invocation idiom).
+
+Privacy/abuse, by construction: the same VLM call gates real human faces and
+NSFW before anything else runs (the refusal is poetic: *"It is already awake."*);
+nothing reaches the public wall except server-persisted, gate-checked records;
+no user identity is stored.
+
+## Build log
+
+### June 12 — recon, contract, fleet
+- 5-agent verification recon over the live field (370 spaces): the pareidolia
+  hook is unclaimed; the OpenBMB wood lane has real contenders now; model IDs
+  from earlier notes were wrong in both directions ("MiniCPM-V-4_6" ≠ 9B model —
+  it's a 1.3B edge model with an incompatible stack; VoxCPM2's killer feature,
+  text-only voice design, wasn't in any of our notes).
+- Wrote the binding `ARCHITECTURE.md` + `mind/WRITING.md` (the comedy bible)
+  BEFORE any code — six agents then built server/mind/cv/web in parallel against
+  the contract, on a mock backend, no GPU needed.
+- Bench Space (we tried to rent a paid L40S; the org has no pre-paid credits —
+  every paid tier 402'd — so the bench runs on the same ZeroGPU grant as prod,
+  which turned out to be the better experiment anyway: the timings are
+  *exactly* representative). The slice is generous: an RTX PRO 6000 Blackwell
+  MIG 2g.48gb, 50.9GB. Both models co-resident at 24GB.
+- **Warm numbers**: MiniCPM-V structured JSON ~9.8–15s GPU (image sliced ≤4,
+  600–700 new tokens, greedy); VoxCPM2 ~4s GPU for ~5s of 48kHz speech; one
+  full awakening ≈ **17–25s** visitor-facing. The séance theater has to carry
+  ~20s, and does.
+- **The writing eval is a gate, not a vibe**: 14 CC0 object photos through the
+  real pipeline, a harsh-editor laugh count, four prompt rounds. Round 1
+  collapsed to the_perfectionist on 8/14 objects and opened every line with a
+  count of years — exemplar-skeleton cloning under greedy decoding. The fixes
+  that worked were *rules about the world, not rules about jokes*: check for
+  rust before calling anything pristine; another of its kind in frame forces
+  the_rival; name the thing, not the feeling (banned vocabulary: purpose,
+  potential, neglect…). Best line the model wrote, unprompted, about a mug
+  with a violin-shaped handle: *"Why a violin? Why not a guitar?"*
+- **Grounding truth**: the VLM hallucinates coordinates ~40% of the time on
+  hard objects (it once placed "hinge screws" confidently in blank wall). The
+  deterministic snap layer + a render-side forgiveness clamp + curation gets
+  the genesis wall to ~10/12 plausible. We do not pretend otherwise — the
+  trace dataset shows every snap delta.
+
+### June 13 — <!-- TODO(fill): deploy, seeds, polish, social -->
+
+### June 14 — <!-- TODO(fill): demo video, org blog -->
+
+## Things that bit us (so they don't bite you)
+
+- **`voxcpm` pip backtracking is silent and brutal**: voxcpm 2.x requires
+  `gradio>=6,<7`. If anything in your stack pins gradio below 6, pip quietly
+  resolves voxcpm **1.5.0**, which has no VoxCPM2 dispatch — your "VoxCPM2"
+  Space then reads the persona prefix *aloud* at 16kHz. Pin `voxcpm>=2.0.3`.
+- **torchcodec is coupled to torch minor versions**: unpinned it resolves to
+  0.14, which demands torch≥2.11 and drags the whole stack against the Space
+  image's preinstalled torch 2.8.0. `torchcodec==0.7.*` + `torchaudio==2.8.*`.
+- **`TORCHDYNAMO_DISABLE=1` before any torch import** — VoxCPM's torch.compile
+  warmup dies on ZeroGPU ("Cannot construct ConstantVariable for
+  torch.device"). Or pass `optimize=False`; we do both.
+- **MiniCPM-V-4_5 lives on the transformers v4 line** (its remote code breaks
+  on v5), and transformers v4 needs huggingface-hub<1.0, which conflicts with
+  gradio 6.18's hub≥1.0 — `sdk_version: 6.16.0` is the keystone holding the
+  arch up. Also: `attn_implementation="sdpa"`, never eager; and pass
+  `enable_thinking=False` or a hybrid-thinking model will eat your token
+  budget thinking about a stapler.
+- **Load BOTH models at startup, never inside the GPU window.** ZeroGPU runs
+  your GPU function in a forked worker; lazy state does not persist. Our first
+  wiring lazy-loaded the 2.3B voice inside the visitor's window — that's a
+  Hub download on someone else's quota.
+- **Never trust a VLM with pixels.** Ask it to *name* features and give coarse
+  hints; let Hough circles and blob centroids do the placing. When we asked
+  for raw coordinates it gave both eyes the same point — on the object's hat.
+- **PIL decompression bombs are reachable before your GPU auth** — cap
+  declared dimensions before `.load()`, not just upload bytes.
+
+## Models
+
+| Role | Model | Params | Why |
+|---|---|---|---|
+| Eyes & soul | [openbmb/MiniCPM-V-4_5](https://huggingface.co/openbmb/MiniCPM-V-4_5) | 8.7B | the only small VLM whose feature-naming + condition-reading is good enough to be load-bearing |
+| Voice | [openbmb/VoxCPM2](https://huggingface.co/openbmb/VoxCPM2) | 2.29B | voice *design from a text description* — ten distinct characters, zero reference audio |
+
+≈ 11B total. Comfortably under the 32B cap, and every parameter is doing
+something you can see or hear.

README.md

@@ -1,13 +1,143 @@
 ---
-title: Pareidolia
-emoji: 🦀
-colorFrom: red
-colorTo: green
+title: PAREIDOLIA
+emoji: 👁️
+colorFrom: gray
+colorTo: indigo
 sdk: gradio
-sdk_version: 6.18.0
-python_version: '3.13'
+sdk_version: 6.16.0
 app_file: app.py
 pinned: false
+license: apache-2.0
+short_description: "point at anything. find the face that was always there."
+models:
+  - openbmb/MiniCPM-V-4_5
+  - openbmb/VoxCPM2
+datasets:
+  - AndresCarreon/pareidolia-menagerie
+tags:
+  - track:wood
+  - sponsor:openbmb
+  - achievement:offbrand
+  - achievement:sharing
+  - achievement:fieldnotes
+  - achievement:offgrid
+  - build-small-hackathon
+  - minicpm
+  - voxcpm
+  - camera
+  - multimodal
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# 👁️ PAREIDOLIA
+
+**Everything secretly has a face.**
+
+Point your camera at any object. A small **MiniCPM-V** spirit-medium studies the
+photo the way you study clouds — it finds the two bonnet bolts that were always
+eyes, the outlet cap that was always a mouth — and the face that was hiding in
+your fire hydrant opens its eyes, blinks at you, and tells you, in its own
+voice, exactly what it has been putting up with.
+
+> *"Forty years on this corner. Not one dog has shown me respect."*
+
+Every awakened object joins the **Menagerie** — one public wall, shared by every
+visitor, where all of them blink, glance around, and mutter.
+
+<!-- TODO(main, June 13): hero GIF here — cut on the first blink. -->
+
+## ✨ The moment that sells it
+
+You photograph your own coffee mug. Mist crosses the photo while the medium
+works — *"there is something here…"* — then it names what it found: *"the two
+painted notes… symmetric…"* Two eyes the exact color of the glaze fade onto the
+ceramic and **blink**. And then the mug speaks. It has noticed things about you.
+It has been keeping a list.
+
+No face is invented. The eyes land on features that are *really there* — that's
+the whole point, and the whole name.
+
+## 🧠 How it works — taste from the model, facts from the code
+
+A hard separation of church and state, twice over:
+
+```
+your photo (browser downscales; YOUR ZeroGPU quota pays for your séance)
+   │
+   ▼  one @spaces.GPU window, ~20s
+┌─ THE MEDIUM · MiniCPM-V-4_5 ──────────────────────────────────┐
+│  ONE structured generation (critique-then-final JSON):        │
+│  privacy gate → object + condition → named VISIBLE features   │
+│  ("left bonnet bolt: eye") → persona → the grudge             │
+└──────────────┬────────────────────────────────────────────────┘
+               ▼
+┌─ THE SURVEYOR · OpenCV, deterministic ────────────────────────┐
+│  snaps each named feature to the strongest real anchor nearby │
+│  (Hough circles, blobs, corners; pair-coherence rules) —      │
+│  the model never places a pixel; the code never invents an eye│
+└──────────────┬────────────────────────────────────────────────┘
+               ▼
+┌─ THE VOICE · VoxCPM2 ─────────────────────────────────────────┐
+│  voice DESIGNED from a text description — ten distinct        │
+│  characters, zero reference audio                             │
+└──────────────┬────────────────────────────────────────────────┘
+               ▼
+the LIFE engine (client-side SVG): eyes tinted from the photo's own
+palette → first blink → saccades, pupil-follow → the mouth rides the
+audio's amplitude. The wall replays all of it forever with ZERO GPU.
+```
+
+The writing is governed, not vibes: a grudge-archetype bank keyed to the
+object's *visible condition* (the_veteran/rusted, the_martyr/worn,
+the_perfectionist/pristine, the_diva/displayed…), and an iron rule that every
+line must reference something actually in the photo.
+
+Privacy is structural: the same generation gates **real human faces and NSFW**
+before anything else runs — the refusal is simply *"It is already awake."* —
+and nothing reaches the public wall except server-held, gate-checked records.
+No user identity is ever stored.
+
+## 📦 Models (≈ 11B total — well under the 32B cap)
+
+| role | model | size | license |
+|---|---|---|---|
+| sees the face, writes the soul | [openbmb/MiniCPM-V-4_5](https://huggingface.co/openbmb/MiniCPM-V-4_5) | 8.7B | Apache-2.0 |
+| speaks the grudge | [openbmb/VoxCPM2](https://huggingface.co/openbmb/VoxCPM2) | 2.29B | Apache-2.0 |
+
+Both models run **in-Space**. No external APIs, no remote endpoints.
+
+## 🏆 Badges
+
+- **Off-Brand** — the entire UI is custom (static `web/` served by `gr.Server`;
+  zero gradio components on screen).
+- **Off the Grid** — all inference in-Space on ZeroGPU.
+- **Sharing is Caring** — every awakening publishes its full wake-trace (the
+  medium's JSON, the surveyor's snap deltas, the chosen voice) to
+  [AndresCarreon/pareidolia-menagerie](https://huggingface.co/datasets/AndresCarreon/pareidolia-menagerie).
+- **Field Notes** — [FIELD_NOTES.md](FIELD_NOTES.md) — the build log, including
+  the dependency saga and what a vision model does when you ask it to find
+  eyes in a stapler. <!-- TODO(main): + org blog link -->
+
+## 📋 Submission links
+
+<!-- TODO(fill-before-deadline) -->
+- **Demo video:** *coming before the deadline.*
+- **Social post:** *coming before the deadline.*
+
+## ▶️ Run it locally
+
+```bash
+pip install -r requirements-dev.txt
+PAREIDOLIA_BACKEND=mock python app.py   # mock medium: no GPU, no ML deps needed
+```
+
+The Space runs `PAREIDOLIA_BACKEND=zerogpu`; mock returns canned awakenings
+with realistic latency so the whole experience works on a laptop.
+
+## 🙏 Credits
+
+- Models: OpenBMB **MiniCPM-V-4_5** + **VoxCPM2** (Apache-2.0).
+- Seed-wall photos: CC0 / public-domain images via Openverse & Wikimedia
+  Commons — per-image attribution in [`seeds/eval/LICENSES.md`](seeds/eval/LICENSES.md).
+- Type: Cormorant Garamond (SIL OFL).
+
+*It was in there all along.*

app.py

@@ -0,0 +1,525 @@
+"""PAREIDOLIA — Space entrypoint. Everything secretly has a face.
+
+Wiring (ARCHITECTURE.md is the contract; the godseed skeleton is the proven base):
+
+  Menagerie wall (web/)     <--  GET /                      static, zero GPU
+  the séance                <--  @app.api(name="awaken")    gradio endpoint via
+                                 @gradio/client — the VISITOR's browser-authenticated
+                                 request pays the ZeroGPU quota
+                                 (POST /api/awaken is its mock/dev REST twin,
+                                  not registered on the zerogpu backend)
+  publish to the wall       <--  POST /api/menagerie        {record_token}; rate-limited,
+                                 gate re-checked server-side
+  the wall, paginated       <--  GET  /api/menagerie        newest first
+  live wall updates         <--  GET  /api/stream           SSE 'awakened' broadcasts
+  persisted media           <--  GET  /media/{id}.(jpg|wav) id->path map only
+
+Run:       python app.py                  (port from $PORT, default 7860)
+Backends:  PAREIDOLIA_BACKEND = mock | zerogpu          (default mock)
+Sync:      PAREIDOLIA_DATASET (+ HF_TOKEN) mirrors menagerie/ to an HF dataset.
+Identity:  PAREIDOLIA_SECRET signs visitor cookies (publish <= 6/hour each).
+
+The "her" pattern: the VLM owns taste (what counts as an eye, what the soul
+sounds like); this file owns facts — bytes, tokens, limits, and what is allowed
+onto the public wall. Errors and refusals are always poetry, never stack traces.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import base64
+import hashlib
+import io
+import logging
+import os
+import re
+import threading
+import warnings
+
+# ZeroGPU runtime: the `spaces` lib must be imported before torch anywhere in
+# the process (it patches torch to virtualize the GPU). TORCHDYNAMO_DISABLE
+# must also precede any torch import — VoxCPM's torch.compile warmup breaks
+# ZeroGPU (§7). No-op everywhere else.
+if os.environ.get("PAREIDOLIA_BACKEND", "").strip().lower() == "zerogpu":
+    os.environ.setdefault("TORCHDYNAMO_DISABLE", "1")
+    try:
+        import spaces  # noqa: F401
+    except ImportError:
+        pass
+
+from contextlib import asynccontextmanager
+from pathlib import Path
+from typing import Any, Optional
+
+from fastapi import FastAPI, HTTPException, Query, Request, Response
+from fastapi.responses import FileResponse, JSONResponse, StreamingResponse
+from fastapi.staticfiles import StaticFiles
+
+from server.persistence import PendingStore, PersistenceService
+from server.ratelimit import (
+    COOKIE_NAME,
+    DEFAULT_IP_LIMIT,
+    ClientIdentity,
+    RateLimiter,
+    client_ip,
+)
+from server.schemas import AwakenRequest, GateFlags, PublishRequest
+from server.sse import SSEHub
+from server.wiring import PipelineLike, make_pipeline
+
+log = logging.getLogger("pareidolia")
+
+ROOT = Path(__file__).resolve().parent
+WEB_DIR = ROOT / "web"
+MENAGERIE_DIR = ROOT / "menagerie"
+SEEDS_RECORDS_DIR = ROOT / "seeds" / "records"
+
+VALID_BACKENDS = ("mock", "zerogpu")
+
+# Transport cap: 1.5MB of base64 text (the client downscales to <=350KB JPEG,
+# so a compliant browser never gets near this; the cap stops abusive bodies).
+MAX_IMAGE_B64_BYTES = 1_572_864
+
+# Poetry for the unhappy paths — the spirits never return a stack trace.
+OVERSIZE_REASON = (
+    "That offering is too heavy for the séance table. "
+    "Bring it under a megabyte and a half, and the spirits will look again."
+)
+NEEDS_IMAGE_REASON = "The spirits need a photograph to peer into. The table is bare."
+BAD_IMAGE_REASON = "The spirits see no photograph here — only static."
+VAST_IMAGE_REASON = (
+    "The spirits cannot hold a vision that vast. "
+    "Offer a smaller photograph and they will lean in close."
+)
+SEANCE_FAILED_REASON = (
+    "The candle guttered mid-séance. Nothing was disturbed; try once more."
+)
+RATE_LIMIT_REASON = (
+    "The menagerie admits six souls an hour from one hand. "
+    "Sit with the ones you have woken; the wall will wait."
+)
+TOKEN_UNKNOWN_REASON = (
+    "The spirits hold no séance by that name — or it has faded with the quarter hour."
+)
+GATE_RECHECK_REASON = "The wall declines this one. The spirits were clear."
+NOT_FOUND_REASON = "The menagerie holds no such creature."
+WALL_CROWDED_REASON = (
+    "The wall is thick with watchers tonight. Linger a moment, then look again."
+)
+
+MEDIA_NAME_RE = re.compile(r"^([A-Za-z0-9_-]{4,64})\.(jpg|wav)$")
+MEDIA_TYPES = {"jpg": "image/jpeg", "wav": "audio/wav"}
+
+# Server-side re-encode bound: the client already downscales to <=1024px; this
+# is the defensive ceiling for non-compliant callers (bounds VLM prefill too).
+MAX_IMAGE_SIDE = 1024
+JPEG_QUALITY = 88
+
+# Decompression-bomb ceiling (security review #1): a tiny, highly-compressible
+# PNG under the transport cap can DECLARE ~170M pixels and allocate 500MB+ on
+# decode — before the thumbnail clamp, before any GPU quota. Cap total pixels:
+# the 1024px working size with 4x headroom for the pre-thumbnail original.
+MAX_PIXELS = MAX_IMAGE_SIDE * MAX_IMAGE_SIDE * 4  # ~4.2M pixels
+try:
+    from PIL import Image as _PILImage
+
+    # PIL hard-stops at 2x this inside Image.open (DecompressionBombError -> our
+    # poetic 400); our explicit dimension check below covers 1x-2x with a 413,
+    # so the 1x warning is redundant noise — silence it, keep the error.
+    _PILImage.MAX_IMAGE_PIXELS = MAX_PIXELS
+    warnings.filterwarnings("ignore", category=_PILImage.DecompressionBombWarning)
+except ImportError:  # pragma: no cover — PIL is a hard dependency in prod
+    pass
+
+
+def _backend_name() -> str:
+    name = os.environ.get("PAREIDOLIA_BACKEND", "mock").strip().lower() or "mock"
+    if name not in VALID_BACKENDS:
+        log.warning("unknown PAREIDOLIA_BACKEND=%r; falling back to mock", name)
+        name = "mock"
+    return name
+
+
+# --------------------------------------------------------------------------- helpers
+def _set_identity_cookie(response: Response, request: Request, value: str) -> None:
+    """Spaces serve over https inside an iframe (cross-site -> SameSite=None+Secure);
+    local dev is plain http (Lax, not Secure)."""
+    scheme = request.headers.get("x-forwarded-proto", request.url.scheme)
+    secure = scheme == "https"
+    response.set_cookie(
+        COOKIE_NAME,
+        value,
+        max_age=365 * 24 * 3600,
+        path="/",
+        httponly=True,
+        secure=secure,
+        samesite="none" if secure else "lax",
+    )
+
+
+def _decode_image(image_b64: str):
+    """base64 -> validated, bounded RGB PIL image. Raises poetic HTTPExceptions:
+    413 oversize, 400 undecodable, 422 missing. PIL import stays local so the
+    transport module imports clean even in odd environments."""
+    if not image_b64 or not image_b64.strip():
+        raise HTTPException(status_code=422, detail=NEEDS_IMAGE_REASON)
+    if len(image_b64) > MAX_IMAGE_B64_BYTES:
+        raise HTTPException(status_code=413, detail=OVERSIZE_REASON)
+    payload = image_b64.strip()
+    if payload.startswith("data:"):  # tolerate a full data URL from the client
+        payload = payload.partition(",")[2]
+    try:
+        raw = base64.b64decode(payload, validate=True)
+    except Exception as exc:
+        raise HTTPException(status_code=400, detail=BAD_IMAGE_REASON) from exc
+    try:
+        from PIL import Image
+
+        image = Image.open(io.BytesIO(raw))
+        # Dimension gate BEFORE any pixel decode (security review #1): open()
+        # only parses the header; load() is what allocates w*h*3 bytes. Refuse
+        # on DECLARED size so the bomb never costs more than a header parse.
+        width, height = image.size
+        if width * height > MAX_PIXELS:
+            raise HTTPException(status_code=413, detail=VAST_IMAGE_REASON)
+        image.load()
+        image = image.convert("RGB")
+    except HTTPException:
+        raise
+    except Exception as exc:
+        # Includes PIL's DecompressionBombError (the 2x MAX_PIXELS hard stop
+        # raised inside Image.open) — same poetic 400 as any undecodable image.
+        raise HTTPException(status_code=400, detail=BAD_IMAGE_REASON) from exc
+    if max(image.size) > MAX_IMAGE_SIDE:
+        image.thumbnail((MAX_IMAGE_SIDE, MAX_IMAGE_SIDE))
+    return image
+
+
+def _encode_jpeg(image) -> bytes:
+    buf = io.BytesIO()
+    image.save(buf, format="JPEG", quality=JPEG_QUALITY)
+    return buf.getvalue()
+
+
+# --------------------------------------------------------------------------- the app
+def create_app(
+    *,
+    pipeline: Optional[PipelineLike] = None,
+    persistence: Optional[PersistenceService] = None,
+    pending: Optional[PendingStore] = None,
+    hub: Optional[SSEHub] = None,
+    rate_limiter: Optional[RateLimiter] = None,
+    ip_rate_limiter: Optional[RateLimiter] = None,
+    identity: Optional[ClientIdentity] = None,
+    menagerie_dir: Optional[Path | str] = None,
+    backend: Optional[str] = None,
+    mount_web: bool = True,
+) -> FastAPI:
+    """Build the ASGI app. With no arguments this wires the real (env-selected)
+    backend; tests inject fakes for everything mind/cv-shaped."""
+    backend_name = backend or _backend_name()
+    pipeline = pipeline if pipeline is not None else make_pipeline(backend_name)
+    persistence = (
+        persistence
+        if persistence is not None
+        else PersistenceService(
+            menagerie_dir if menagerie_dir is not None else MENAGERIE_DIR,
+            seeds_dir=SEEDS_RECORDS_DIR,
+        )
+    )
+    pending = pending if pending is not None else PendingStore()
+    hub = hub if hub is not None else SSEHub()
+    rate_limiter = rate_limiter or RateLimiter()
+    ip_rate_limiter = ip_rate_limiter or RateLimiter(limit=DEFAULT_IP_LIMIT)
+    identity = identity or ClientIdentity()
+
+    @asynccontextmanager
+    async def lifespan(app: FastAPI):
+        yield
+        await persistence.drain()
+
+    # Gradio Server mode (the "her" idiom, proven on godseed): gr.Server IS a
+    # FastAPI app with gradio's API engine attached — the sdk:gradio runtime
+    # serves it natively, and @app.api endpoints are gradio endpoints the
+    # browser calls via @gradio/client, which forwards the HF auth headers
+    # ZeroGPU quota needs.
+    try:
+        import gradio as gr
+
+        app: FastAPI = gr.Server(title="PAREIDOLIA")
+        app.router.lifespan_context = lifespan
+    except Exception:  # pragma: no cover — gradio always present in prod
+        app = FastAPI(
+            title="PAREIDOLIA", docs_url=None, redoc_url=None, lifespan=lifespan
+        )
+    app.state.persistence = persistence
+    app.state.pending = pending
+    app.state.hub = hub
+
+    async def ensure_ready() -> None:
+        """Boot persistence lazily on the serving loop (godseed's ensure idiom:
+        launch() does not honor an injected lifespan, so the first request —
+        or the warm-boot thread in _serve — does the waking). Idempotent and
+        thread-safe; the dataset restore runs off the event loop."""
+        if not persistence.booted:
+            await asyncio.to_thread(persistence.boot)
+
+    # ------------------------------------------------------------------ the séance
+    async def _awaken(image_b64: str) -> dict[str, Any]:
+        """§2 pipeline: decode -> medium -> gate -> snap -> TTS -> pending token.
+        Refusals are HTTP 200 + {refused: true}; only transport sins get codes."""
+        await ensure_ready()
+        image = _decode_image(image_b64)
+        try:
+            outcome = await asyncio.to_thread(pipeline.run, image)
+        except Exception as exc:
+            log.exception("séance pipeline failed")
+            raise HTTPException(
+                status_code=500, detail=SEANCE_FAILED_REASON
+            ) from exc
+        if outcome.refused or outcome.result is None or outcome.grudge_wav is None:
+            return {"refused": True, "reason": outcome.reason or SEANCE_FAILED_REASON}
+        result = outcome.result
+        jpeg = _encode_jpeg(image)
+        record: dict[str, Any] = {
+            "object": result.object,
+            "material": result.material,
+            "condition": result.condition,
+            "setting": result.setting,
+            "persona": result.persona.model_dump(),
+            "features": [f.model_dump() for f in outcome.features],
+            "lines": result.lines.model_dump(),
+            "critique": result.critique,
+            "image_sha256": hashlib.sha256(jpeg).hexdigest(),
+            "backend": backend_name,
+        }
+        token = pending.put(
+            record=record,
+            image_jpeg=jpeg,
+            grudge_wav=outcome.grudge_wav,
+            gate=result.gate.model_dump(),
+        )
+        return {
+            "refused": False,
+            "record_token": token,
+            "record": {
+                **record,
+                "grudge_audio_b64": base64.b64encode(outcome.grudge_wav).decode(
+                    "ascii"
+                ),
+            },
+        }
+
+    # Gradio endpoint: the visitor's browser calls this via @gradio/client so
+    # the visitor's own ZeroGPU quota pays for the awakening (§0).
+    if hasattr(app, "api"):
+
+        @app.api(name="awaken")
+        async def awaken(image_b64: str = "") -> dict:
+            try:
+                return await _awaken(image_b64)
+            except HTTPException as exc:
+                # gradio endpoints cannot speak HTTP status codes; same poetry,
+                # flat shape, status carried in-band for the client.
+                return {
+                    "refused": True,
+                    "reason": str(exc.detail),
+                    "status": exc.status_code,
+                }
+            except Exception:
+                log.exception("awaken failed")
+                return {"refused": True, "reason": SEANCE_FAILED_REASON, "status": 500}
+
+    # REST twin for the mock/dev backend (tests, curl, local frontend work).
+    # Never registered on zerogpu: GPU work must stay inside the visitor's
+    # browser-authenticated gradio request (§0), so prod matches §6 exactly.
+    if backend_name != "zerogpu":
+
+        @app.post("/api/awaken")
+        async def awaken_rest(payload: AwakenRequest) -> JSONResponse:
+            return JSONResponse(await _awaken(payload.image_b64))
+
+    # -------------------------------------------------------------- POST /api/menagerie
+    @app.post("/api/menagerie")
+    async def publish(payload: PublishRequest, request: Request) -> JSONResponse:
+        await ensure_ready()
+        cid, new_cookie = identity.resolve(request)
+
+        # Order is peek-validate -> rate-limit -> claim (security review #2c):
+        # the token must prove itself BEFORE the limiters record a hit, or an
+        # unauthenticated junk-token flood grows limiter state for nothing.
+        # Peek (not claim) first so a rate-limited publish never spends the
+        # one-time token; peek->claim cannot race — requests share one event
+        # loop and nothing awaits between the two calls.
+        if pending.peek(payload.record_token) is None:
+            raise HTTPException(status_code=404, detail=TOKEN_UNKNOWN_REASON)
+
+        ip_ok, ip_retry = ip_rate_limiter.hit(f"ip:{client_ip(request)}")
+        allowed, retry_after = rate_limiter.hit(cid) if ip_ok else (False, ip_retry)
+        if not allowed:
+            raise HTTPException(
+                status_code=429,
+                detail=RATE_LIMIT_REASON,
+                headers={"Retry-After": str(int(retry_after) + 1)},
+            )
+
+        held = pending.claim(payload.record_token)
+        if held is None:  # pragma: no cover — peek above guarantees presence
+            raise HTTPException(status_code=404, detail=TOKEN_UNKNOWN_REASON)
+
+        # Gate re-check, server-side (§0: layered and non-negotiable). awaken
+        # never parks a gated record, so this is pure defense-in-depth.
+        if not GateFlags.model_validate(held.gate).passes():
+            raise HTTPException(status_code=403, detail=GATE_RECHECK_REASON)
+
+        record = await persistence.publish(
+            held.record, held.image_jpeg, held.grudge_wav
+        )
+        hub.publish({"type": "awakened", "record": record})
+        # The cookie is set on the returned Response directly: FastAPI drops
+        # `response`-param mutations when a handler returns its own Response
+        # (and on raise paths — cookieless retries fall to the IP limiter).
+        out = JSONResponse(record)
+        if new_cookie:
+            _set_identity_cookie(out, request, new_cookie)
+        return out
+
+    # --------------------------------------------------------------- GET /api/menagerie
+    @app.get("/api/menagerie")
+    async def menagerie_index(
+        offset: int = Query(default=0, ge=0),
+        limit: int = Query(default=60, ge=1, le=200),
+    ) -> JSONResponse:
+        await ensure_ready()
+        records, total = persistence.page(offset, limit)
+        return JSONResponse(
+            {
+                "records": records,
+                "total": total,
+                "offset": offset,
+                "limit": limit,
+                "awake_count": total,
+            }
+        )
+
+    # ------------------------------------------------------------------ /api/stream
+    @app.get("/api/stream")
+    async def stream(
+        request: Request,
+        limit: Optional[int] = Query(
+            default=None,
+            ge=1,
+            le=10_000,
+            description="debug/test aid: close the stream after N events",
+        ),
+    ) -> StreamingResponse:
+        await ensure_ready()
+        # Capacity gate (security review #3): every subscriber holds a bounded
+        # queue + a generator. The slot is reserved HERE — before the response
+        # body starts — so over-capacity is an honest 503, and the generator's
+        # finally-unsubscribe releases the slot on disconnect as before.
+        queue = hub.subscribe(key=f"ip:{client_ip(request)}")
+        if queue is None:
+            raise HTTPException(
+                status_code=503,
+                detail=WALL_CROWDED_REASON,
+                headers={"Retry-After": "15"},
+            )
+        initial = [{"type": "hello", "awake_count": persistence.count()}]
+        return StreamingResponse(
+            hub.event_stream(initial_events=initial, limit=limit, queue=queue),
+            media_type="text/event-stream",
+            headers={
+                "Cache-Control": "no-cache",
+                "X-Accel-Buffering": "no",  # required on Spaces or the proxy buffers
+                "Connection": "keep-alive",
+            },
+        )
+
+    # --------------------------------------------------------------- GET /media/{name}
+    @app.get("/media/{name}", include_in_schema=False)
+    async def media(name: str) -> FileResponse:
+        """Persisted menagerie media. Traversal-safe by construction: the name
+        must match the mint alphabet, and the id resolves through the
+        server-built id->path map only — no client string ever becomes a path."""
+        await ensure_ready()
+        match = MEDIA_NAME_RE.fullmatch(name)
+        if match is None:
+            raise HTTPException(status_code=404, detail=NOT_FOUND_REASON)
+        path = persistence.media_path(match.group(1), match.group(2))
+        if path is None or not path.is_file():
+            raise HTTPException(status_code=404, detail=NOT_FOUND_REASON)
+        return FileResponse(
+            path,
+            media_type=MEDIA_TYPES[match.group(2)],
+            headers={"Cache-Control": "public, max-age=31536000, immutable"},
+        )
+
+    # ------------------------------------------------------------------------ static
+    def _mount_static() -> None:
+        """Root static mount. A "/" catch-all registered BEFORE gr.Server.launch()
+        shadows the /gradio_api routes gradio adds at launch time (godseed,
+        verified June 12: the launch self-check 404s and the app dies). So the
+        mount is deferred: _serve() calls this AFTER launch; the plain-FastAPI
+        path mounts immediately below."""
+        if WEB_DIR.is_dir():
+            # gradio's launch registers its own SPA index at "/" (GET+HEAD) —
+            # evict exactly those so the wall owns the root; every other gradio
+            # route (/config, /gradio_api/*, assets) must survive for
+            # @gradio/client connectivity.
+            app.router.routes[:] = [
+                r for r in app.router.routes if getattr(r, "path", None) != "/"
+            ]
+            app.mount("/", StaticFiles(directory=str(WEB_DIR), html=True), name="web")
+        else:
+            log.warning("web/ not found at %s; serving API only", WEB_DIR)
+
+            @app.get("/", include_in_schema=False)
+            async def root_placeholder() -> JSONResponse:
+                return JSONResponse({"ok": True, "hint": "frontend not built"})
+
+    app.state.mount_static = _mount_static
+    if mount_web and not hasattr(app, "launch"):
+        _mount_static()
+
+    return app
+
+
+# --------------------------------------------------------------------------- entrypoint
+def _serve(application: FastAPI) -> None:
+    port = int(os.environ.get("PORT", os.environ.get("GRADIO_SERVER_PORT", 7860)))
+    log.info("PAREIDOLIA listening on http://0.0.0.0:%d", port)
+    if hasattr(application, "launch"):
+        # Gradio Server mode — launch non-blocking so the web root can mount
+        # AFTER gradio registers its /gradio_api routes (order = precedence).
+        application.launch(
+            server_name="0.0.0.0",
+            server_port=port,
+            show_error=False,
+            prevent_thread_lock=True,
+        )
+        mount_static = getattr(application.state, "mount_static", None)
+        if mount_static is not None:
+            mount_static()
+        # Warm-boot the menagerie off the serving thread so visitor #1 sees a
+        # full wall without paying the dataset-restore wait themselves.
+        persistence = getattr(application.state, "persistence", None)
+        if persistence is not None and not persistence.booted:
+            threading.Thread(target=persistence.boot, daemon=True).start()
+        import time as _time
+
+        while True:  # keep the process alive; the server runs in gradio's thread
+            _time.sleep(3600)
+    else:  # pragma: no cover — gradio-less dev fallback
+        import uvicorn
+
+        uvicorn.run(application, host="0.0.0.0", port=port)
+
+
+# HF Spaces (sdk:gradio) executes this file; locally it's `python app.py`.
+# Test imports leave both conditions false and get no side effects.
+if __name__ == "__main__" or os.environ.get("SPACE_ID"):
+    logging.basicConfig(
+        level=logging.INFO, format="%(asctime)s %(name)s %(levelname)s %(message)s"
+    )
+    _serve(create_app())

cv/__init__.py

@@ -0,0 +1,10 @@
+"""PAREIDOLIA deterministic CV — pure numpy + opencv-headless, no ML, no RNG.
+
+The her-pattern's fact-keeper: the VLM proposes coarse feature points, this
+package snaps them to real pixels (`snap.snap_features`) and renders the
+before/after evidence (`snap.overlay_debug`).
+"""
+
+from .snap import MIN_SCORE, SNAP_RADIUS_FRAC, overlay_debug, snap_features
+
+__all__ = ["snap_features", "overlay_debug", "MIN_SCORE", "SNAP_RADIUS_FRAC"]

cv/snap.py

@@ -0,0 +1,533 @@
+"""PAREIDOLIA deterministic feature snapping — the "code owns facts" half.
+
+The VLM (MiniCPM-V) owns taste: it names the bolt that wants to be an eye and
+hands over coarse normalized coordinates. This module owns facts: it snaps
+each coarse point to the strongest nearby visual anchor using plain OpenCV on
+CPU — Hough circles (eyes love circles: bolts, dials, knobs), good-features
+corners, dark-blob centroids, and horizontally elongated edge segments for
+mouths. No ML, no RNG: the same image + features always produce byte-identical
+output, so a persisted menagerie record replays forever.
+
+Contract (ARCHITECTURE.md §0 "Deterministic CV snapping", §2 step 3):
+
+- search window = radius 12% of the image diagonal around each VLM point;
+- candidates are scored by (anchor strength × proximity to the VLM point),
+  weighted by how well the anchor kind suits the feature role;
+- eyes prefer circle anchors, and the eye PAIR must stay coherent: if
+  independent snapping skews the eye-line by >12° or changes the separation
+  by >35% vs the VLM pair, the pair falls back to a rigid translation by the
+  stronger anchor's delta (midpoint + angle of the VLM pair are preserved,
+  the weaker eye is marked ``anchor_kind="pair"``);
+- the mouth prefers a horizontally elongated contour/edge segment and is never
+  snapped above the (snapped) eye midpoint;
+- if no anchor beats ``MIN_SCORE`` the VLM point is kept verbatim
+  (``anchor_kind="vlm"``) — the mist animation forgives ±15%;
+- the mouth floor is enforced on the FINAL points regardless of anchor_kind:
+  a kept-VLM mouth that sits at or above the eye midpoint is pushed just
+  below it (``anchor_kind="vlm_corrected"``) so an inverted face can never
+  ship.
+
+Coordinate conventions: ``cx``/``cy`` are normalized to ``[0, 1]`` over
+``width-1`` / ``height-1``; ``size`` is the feature's coarse diameter as a
+fraction of the image diagonal (the ARCHITECTURE.md §3 schema); ``snap_delta``
+is the distance moved, as a fraction of the image diagonal.
+"""
+
+from __future__ import annotations
+
+import math
+from dataclasses import dataclass
+from typing import Any, Optional
+
+import cv2
+import numpy as np
+
+__all__ = ["snap_features", "overlay_debug", "MIN_SCORE", "SNAP_RADIUS_FRAC"]
+
+# ----------------------------------------------------------------- constants
+
+SNAP_RADIUS_FRAC = 0.12  # search radius as a fraction of the image diagonal
+MIN_SCORE = 0.12  # below this, the VLM point wins (anchor_kind="vlm")
+
+PAIR_MAX_SKEW_DEG = 12.0  # eye-line rotation tolerance vs the VLM pair
+PAIR_MAX_SEP_CHANGE = 0.35  # eye separation ratio-change tolerance
+
+# Corner response normalizer: cv2.cornerMinEigenVal output is pre-scaled by
+# OpenCV — a crisp synthetic step corner peaks near ~0.06 (blockSize=5, uint8
+# input, after our 5x5 blur) while blurred sensor noise stays ≤ ~0.016.
+# Strength saturates at 1.0 so 0.08 keeps noise corners well under MIN_SCORE.
+_CORNER_NORM = 0.08
+
+# How well each anchor kind suits each feature role. Eyes love circles
+# (bolts, dials, knobs); mouths love horizontal edge segments; corners are
+# the weakest evidence everywhere (they fire on texture).
+_KIND_WEIGHTS: dict[str, dict[str, float]] = {
+    "eye": {"circle": 1.00, "blob": 0.70, "corner": 0.45, "edge": 0.30},
+    "mouth": {"edge": 1.00, "blob": 0.75, "circle": 0.50, "corner": 0.35},
+    "other": {"circle": 0.90, "blob": 0.80, "edge": 0.60, "corner": 0.50},
+}
+
+_MIN_ROI_SIDE = 12  # below this the window is too small to detect anything
+
+
+@dataclass(frozen=True)
+class _Anchor:
+    """One candidate anchor in full-image pixel coordinates."""
+
+    x: float
+    y: float
+    strength: float  # detector-specific, normalized to [0, 1]
+    kind: str  # circle | corner | blob | edge
+
+
+# ------------------------------------------------------------------ helpers
+
+
+def _as_gray(image: np.ndarray) -> np.ndarray:
+    """Accept BGR (contract) or already-gray uint8; return single-channel."""
+    if image is None or not isinstance(image, np.ndarray) or image.ndim not in (2, 3):
+        raise ValueError("snap_features expects an HxW or HxWx3 uint8 ndarray")
+    if image.ndim == 3:
+        return cv2.cvtColor(image, cv2.COLOR_BGR2GRAY)
+    return image
+
+
+def _clamp01(v: float) -> float:
+    return min(1.0, max(0.0, float(v)))
+
+
+def _role_class(role: Any) -> str:
+    role = str(role or "")
+    if role.startswith("eye"):
+        return "eye"
+    if role == "mouth":
+        return "mouth"
+    return "other"
+
+
+def _to_px(f: dict, w: int, h: int) -> tuple[float, float]:
+    """Normalized [0,1] feature coords → pixel coords (clamped on-image)."""
+    return (
+        _clamp01(f.get("cx", 0.5)) * (w - 1),
+        _clamp01(f.get("cy", 0.5)) * (h - 1),
+    )
+
+
+def _proximity(d: float, radius: float) -> float:
+    """Gaussian falloff: 1.0 at the VLM point, ~0.14 at the window edge."""
+    return math.exp(-2.0 * (d / radius) ** 2)
+
+
+# ---------------------------------------------------------------- detectors
+# All detectors operate on a pre-blurred grayscale ROI and return anchors in
+# ROI-local coordinates. Every parameter is fixed — nothing is sampled.
+
+
+def _circle_candidates(roi: np.ndarray, want_r: float) -> list[_Anchor]:
+    """HoughCircles, strength = disk-vs-annulus contrast × radius match."""
+    if want_r > 0:
+        min_r = max(2, int(round(want_r * 0.45)))
+        max_r = max(min_r + 2, int(round(want_r * 1.9)))
+    else:
+        min_r, max_r = 3, max(6, int(min(roi.shape) * 0.45))
+    circles = cv2.HoughCircles(
+        roi,
+        cv2.HOUGH_GRADIENT,
+        dp=1.2,
+        minDist=max(4.0, want_r if want_r > 0 else 8.0),
+        param1=120,
+        param2=18,
+        minRadius=min_r,
+        maxRadius=max_r,
+    )
+    if circles is None:
+        return []
+    out: list[_Anchor] = []
+    for cx, cy, r in circles[0][:6]:
+        contrast = _disk_contrast(roi, float(cx), float(cy), float(r))
+        if want_r > 0:
+            r_match = math.exp(-(((float(r) - want_r) / max(want_r, 1.0)) ** 2))
+        else:
+            r_match = 1.0
+        strength = min(1.0, contrast * 1.6) * (0.4 + 0.6 * r_match)
+        out.append(_Anchor(float(cx), float(cy), strength, "circle"))
+    return out
+
+
+def _disk_contrast(roi: np.ndarray, cx: float, cy: float, r: float) -> float:
+    """|mean(disk interior) − mean(surrounding annulus)| / 255 — a bolt head
+    or dial face separates from its plate; blurred noise does not."""
+    h, w = roi.shape
+    yy, xx = np.ogrid[:h, :w]
+    d2 = (xx - cx) ** 2 + (yy - cy) ** 2
+    inner = d2 <= (0.75 * r) ** 2
+    ring = (d2 > (1.15 * r) ** 2) & (d2 <= (1.7 * r) ** 2)
+    if int(inner.sum()) < 4 or int(ring.sum()) < 4:
+        return 0.0
+    return abs(float(roi[inner].mean()) - float(roi[ring].mean())) / 255.0
+
+
+def _corner_candidates(roi: np.ndarray, want_r: float) -> list[_Anchor]:
+    """goodFeaturesToTrack, strength from the min-eigenvalue response map."""
+    corners = cv2.goodFeaturesToTrack(
+        roi,
+        maxCorners=10,
+        qualityLevel=0.08,
+        minDistance=max(4, int(want_r) if want_r > 0 else 6),
+        blockSize=5,
+    )
+    if corners is None:
+        return []
+    response = cv2.cornerMinEigenVal(roi, blockSize=5)
+    out: list[_Anchor] = []
+    for pt in corners.reshape(-1, 2):
+        x, y = float(pt[0]), float(pt[1])
+        iy = min(response.shape[0] - 1, max(0, int(round(y))))
+        ix = min(response.shape[1] - 1, max(0, int(round(x))))
+        strength = min(1.0, float(response[iy, ix]) / _CORNER_NORM)
+        out.append(_Anchor(x, y, strength, "corner"))
+    return out
+
+
+def _blob_candidates(roi: np.ndarray, want_r: float) -> list[_Anchor]:
+    """Dark-blob centroids: adaptive threshold → contour moments, kept only
+    when sized near the feature and actually darker than their surroundings."""
+    side = min(roi.shape)
+    block = int(round(want_r * 4)) | 1 if want_r > 0 else 21
+    block = max(11, min(block, 51, (side - 1) | 1 if side > 2 else 3))
+    if block < 3:
+        return []
+    binary = cv2.adaptiveThreshold(
+        roi, 255, cv2.ADAPTIVE_THRESH_GAUSSIAN_C, cv2.THRESH_BINARY_INV, block, 5
+    )
+    contours, _ = cv2.findContours(binary, cv2.RETR_EXTERNAL, cv2.CHAIN_APPROX_SIMPLE)
+    want_area = math.pi * want_r * want_r if want_r > 0 else 0.0
+    scored: list[tuple[float, Any]] = []
+    for cnt in contours:
+        area = float(cv2.contourArea(cnt))
+        if area < 9.0:
+            continue
+        if want_area > 0 and not (0.15 * want_area <= area <= 6.0 * want_area):
+            continue
+        scored.append((abs(area - want_area), cnt))
+    scored.sort(key=lambda t: t[0])
+    out: list[_Anchor] = []
+    for _, cnt in scored[:8]:
+        m = cv2.moments(cnt)
+        if m["m00"] <= 0:
+            continue
+        bx, by = m["m10"] / m["m00"], m["m01"] / m["m00"]
+        mask = np.zeros(roi.shape, np.uint8)
+        cv2.drawContours(mask, [cnt], -1, 255, -1)
+        k = max(3, (int(want_r * 0.6) | 1) if want_r > 0 else 5)
+        ring = cv2.dilate(mask, np.ones((k, k), np.uint8)) & ~mask
+        if int((mask > 0).sum()) < 4 or int((ring > 0).sum()) < 4:
+            continue
+        darkness = (float(roi[ring > 0].mean()) - float(roi[mask > 0].mean())) / 255.0
+        if darkness <= 0:
+            continue  # spec: DARK blobs only
+        d_eq = 2.0 * math.sqrt(float(cv2.contourArea(cnt)) / math.pi)
+        if want_r > 0:
+            size_match = math.exp(-0.5 * (((d_eq - 2 * want_r) / max(2 * want_r, 1.0)) ** 2))
+        else:
+            size_match = 1.0
+        out.append(_Anchor(bx, by, min(1.0, darkness * 1.4) * size_match, "blob"))
+    return out
+
+
+def _edge_candidates(roi: np.ndarray, want_d: float) -> list[_Anchor]:
+    """Horizontally elongated edge segments (mouths: slots, grilles, seams).
+
+    Canny contours whose bounding box is clearly wider than tall. Strength =
+    elongation × (soft) width match × vertical-gradient support × straightness.
+    The last two terms separate a real seam (strong |dI/dy| along a near-
+    straight run) from the wiggly low-contrast strings Canny traces on noise.
+    """
+    edges = cv2.Canny(roi, 60, 150)
+    contours, _ = cv2.findContours(edges, cv2.RETR_LIST, cv2.CHAIN_APPROX_NONE)
+    if not contours:
+        return []
+    sobel_y = np.abs(cv2.Sobel(roi, cv2.CV_64F, 0, 1, ksize=3))
+    out: list[_Anchor] = []
+    for cnt in contours:
+        x, y, w, h = cv2.boundingRect(cnt)
+        if w < max(8, 0.3 * want_d) or w < 1.6 * max(h, 1):
+            continue
+        aspect = w / max(h, 1)
+        elong = min(1.0, (aspect - 1.0) / 3.0)
+        pts = cnt.reshape(-1, 2)
+        ex, ey = float(pts[:, 0].mean()), float(pts[:, 1].mean())
+        # a horizontal seam means strong vertical gradient along the contour
+        grad_support = min(1.0, float(sobel_y[pts[:, 1], pts[:, 0]].mean()) / 450.0)
+        # straight run ≈ arc 2w (traced out and back); wiggly noise is longer
+        straightness = min(1.0, 2.2 * w / max(float(cv2.arcLength(cnt, False)), 1.0))
+        if want_d > 0:
+            size_match = math.exp(-0.5 * (((w - want_d) / max(want_d, 1.0)) ** 2))
+        else:
+            size_match = 1.0
+        strength = elong * (0.5 + 0.5 * size_match) * grad_support * straightness
+        out.append(_Anchor(ex, ey, strength, "edge"))
+    out.sort(key=lambda a: (-a.strength, a.x, a.y))
+    return out[:8]
+
+
+# ------------------------------------------------------------- core snapping
+
+
+def _gather_anchors(
+    blurred: np.ndarray, px: float, py: float, radius: float, want_d: float
+) -> list[_Anchor]:
+    """Run all detectors on the search window; return full-image anchors."""
+    h, w = blurred.shape
+    x0 = max(0, int(math.floor(px - radius)))
+    y0 = max(0, int(math.floor(py - radius)))
+    x1 = min(w, int(math.ceil(px + radius)) + 1)
+    y1 = min(h, int(math.ceil(py + radius)) + 1)
+    roi = blurred[y0:y1, x0:x1]
+    if min(roi.shape) < _MIN_ROI_SIDE:
+        return []
+    want_r = want_d / 2.0
+    local = (
+        _circle_candidates(roi, want_r)
+        + _corner_candidates(roi, want_r)
+        + _blob_candidates(roi, want_r)
+        + _edge_candidates(roi, want_d)
+    )
+    return [_Anchor(a.x + x0, a.y + y0, a.strength, a.kind) for a in local]
+
+
+def _best_anchor(
+    anchors: list[_Anchor],
+    px: float,
+    py: float,
+    radius: float,
+    role_class: str,
+    min_y: Optional[float],
+) -> tuple[Optional[_Anchor], float]:
+    """Pick the highest-scoring anchor within the search radius.
+
+    ``min_y`` enforces the mouth rule: candidates at or above the snapped eye
+    midpoint are discarded outright (a mouth is never above the eyes).
+    Ties break on distance, then kind, then coordinates — fully deterministic.
+    """
+    weights = _KIND_WEIGHTS[role_class]
+    best: Optional[_Anchor] = None
+    best_key: tuple = ()
+    best_score = 0.0
+    for a in anchors:
+        d = math.hypot(a.x - px, a.y - py)
+        if d > radius:
+            continue
+        if min_y is not None and a.y <= min_y:
+            continue
+        score = weights[a.kind] * a.strength * _proximity(d, radius)
+        key = (-score, d, a.kind, a.x, a.y)
+        if best is None or key < best_key:
+            best, best_key, best_score = a, key, score
+    return best, best_score
+
+
+def _snap_one(
+    blurred: np.ndarray,
+    feature: dict,
+    radius: float,
+    diag: float,
+    min_y: Optional[float] = None,
+) -> dict:
+    """Snap a single feature; returns a NEW dict (inputs are never mutated)."""
+    h, w = blurred.shape
+    out = dict(feature)
+    px, py = _to_px(feature, w, h)
+    want_d = max(0.0, float(feature.get("size") or 0.0)) * diag
+    role_class = _role_class(feature.get("role"))
+    anchors = _gather_anchors(blurred, px, py, radius, want_d)
+    best, score = _best_anchor(anchors, px, py, radius, role_class, min_y)
+    if best is not None and score >= MIN_SCORE:
+        out["cx"] = _clamp01(best.x / (w - 1)) if w > 1 else 0.0
+        out["cy"] = _clamp01(best.y / (h - 1)) if h > 1 else 0.0
+        out["snap_delta"] = math.hypot(best.x - px, best.y - py) / diag
+        out["anchor_kind"] = best.kind
+        out["anchor_score"] = round(score, 4)
+    else:
+        out["cx"] = _clamp01(feature.get("cx", 0.5))
+        out["cy"] = _clamp01(feature.get("cy", 0.5))
+        out["snap_delta"] = 0.0
+        out["anchor_kind"] = "vlm"
+        out["anchor_score"] = 0.0
+    return out
+
+
+def _enforce_pair_coherence(
+    left: dict,
+    right: dict,
+    left_vlm: tuple[float, float],
+    right_vlm: tuple[float, float],
+    w: int,
+    h: int,
+    diag: float,
+) -> None:
+    """Keep the snapped eye pair geometrically honest (mutates result dicts).
+
+    If independent snapping rotated the eye-line by more than
+    ``PAIR_MAX_SKEW_DEG`` or stretched/shrunk the separation by more than
+    ``PAIR_MAX_SEP_CHANGE`` vs the VLM pair, distrust the weaker anchor:
+    rigidly translate the VLM pair by the STRONGER anchor's snap delta. The
+    pair's midpoint offset and angle then match the VLM's intent, the stronger
+    eye sits exactly on its anchor, and the weaker eye is re-derived
+    (``anchor_kind="pair"``, ``anchor_score`` inherited from the evidence
+    that placed it).
+    """
+    if left["anchor_kind"] == "vlm" and right["anchor_kind"] == "vlm":
+        return  # nothing snapped, nothing to disagree about
+    lvx, lvy = left_vlm
+    rvx, rvy = right_vlm
+    sep_v = math.hypot(rvx - lvx, rvy - lvy)
+    if sep_v < 2.0:
+        return  # degenerate VLM pair; geometry checks are meaningless
+    lsx, lsy = left["cx"] * (w - 1), left["cy"] * (h - 1)
+    rsx, rsy = right["cx"] * (w - 1), right["cy"] * (h - 1)
+    sep_s = math.hypot(rsx - lsx, rsy - lsy)
+    ang_v = math.degrees(math.atan2(rvy - lvy, rvx - lvx))
+    ang_s = math.degrees(math.atan2(rsy - lsy, rsx - lsx))
+    skew = abs((ang_s - ang_v + 180.0) % 360.0 - 180.0)
+    sep_change = abs(sep_s / sep_v - 1.0)
+    if skew <= PAIR_MAX_SKEW_DEG and sep_change <= PAIR_MAX_SEP_CHANGE:
+        return
+    # The eye whose anchor scored higher is trusted ('vlm' scores 0.0).
+    if left["anchor_score"] >= right["anchor_score"]:
+        strong, weak, strong_vlm, weak_vlm = left, right, (lvx, lvy), (rvx, rvy)
+    else:
+        strong, weak, strong_vlm, weak_vlm = right, left, (rvx, rvy), (lvx, lvy)
+    dx = strong["cx"] * (w - 1) - strong_vlm[0]
+    dy = strong["cy"] * (h - 1) - strong_vlm[1]
+    weak["cx"] = _clamp01((weak_vlm[0] + dx) / (w - 1)) if w > 1 else 0.0
+    weak["cy"] = _clamp01((weak_vlm[1] + dy) / (h - 1)) if h > 1 else 0.0
+    weak["snap_delta"] = math.hypot(dx, dy) / diag
+    weak["anchor_kind"] = "pair"
+    weak["anchor_score"] = strong["anchor_score"]
+
+
+def snap_features(image: np.ndarray, features: list[dict]) -> list[dict]:
+    """Snap VLM feature points to the strongest nearby visual anchors.
+
+    Args:
+        image: HxWx3 BGR uint8 (HxW grayscale also accepted).
+        features: dicts with at least ``cx``, ``cy`` (normalized [0,1]),
+            ``size`` (coarse diameter / image diagonal; 0 or missing disables
+            size matching) and ``role`` (``eye_left``/``eye_right``/``mouth``/
+            anything else). Extra keys (``name``, …) pass through untouched.
+
+    Returns:
+        New dicts in input order with snapped ``cx``/``cy`` plus
+        ``snap_delta`` (distance moved / image diagonal), ``anchor_kind``
+        (``circle|corner|blob|edge|pair|vlm|vlm_corrected``) and
+        ``anchor_score``.
+        Inputs are never mutated. Fully deterministic — no RNG anywhere.
+    """
+    gray = _as_gray(image)
+    h, w = gray.shape
+    diag = math.hypot(w, h)
+    radius = max(8.0, SNAP_RADIUS_FRAC * diag)
+    blurred = cv2.GaussianBlur(gray, (5, 5), 1.2)
+
+    results: list[Optional[dict]] = [None] * len(features)
+    vlm_px = [_to_px(f, w, h) for f in features]
+
+    # Pass 1 — eyes first: their final positions gate the mouth's floor.
+    eye_idx = [i for i, f in enumerate(features) if _role_class(f.get("role")) == "eye"]
+    for i in eye_idx:
+        results[i] = _snap_one(blurred, features[i], radius, diag)
+
+    left_i = next((i for i in eye_idx if features[i].get("role") == "eye_left"), None)
+    right_i = next((i for i in eye_idx if features[i].get("role") == "eye_right"), None)
+    if left_i is not None and right_i is not None:
+        _enforce_pair_coherence(
+            results[left_i], results[right_i], vlm_px[left_i], vlm_px[right_i], w, h, diag
+        )
+
+    eye_mid_y: Optional[float] = None
+    if eye_idx:
+        eye_mid_y = sum(results[i]["cy"] * (h - 1) for i in eye_idx) / len(eye_idx)
+
+    # Pass 2 — everything else; mouths must land strictly below the eye line.
+    for i, f in enumerate(features):
+        if results[i] is not None:
+            continue
+        floor = eye_mid_y if _role_class(f.get("role")) == "mouth" else None
+        results[i] = _snap_one(blurred, f, radius, diag, min_y=floor)
+
+    # Pass 3 — enforce the mouth floor on the FINAL points regardless of
+    # anchor_kind. Anchor candidates above the eye line were already filtered
+    # in _best_anchor, but a kept-VLM mouth (anchor_kind="vlm") could still
+    # sit above the snapped eye midpoint — an inverted face. Deterministic
+    # correction: push it just below the eye line, preserving the VLM's own
+    # eye-to-mouth scale.
+    if eye_mid_y is not None:
+        vlm_eye_mid_y = sum(vlm_px[i][1] for i in eye_idx) / len(eye_idx)
+        for i, f in enumerate(features):
+            if _role_class(f.get("role")) != "mouth":
+                continue
+            out = results[i]
+            final_y = out["cy"] * (h - 1)
+            if final_y > eye_mid_y:
+                continue  # already strictly below the eye line
+            mx, my = vlm_px[i]
+            # 0.6 × the eye-to-mouth offset the VLM itself proposed (its
+            # magnitude — the proposal may have been inverted), with a small
+            # floor so an exactly-level mouth still moves strictly below.
+            offset = 0.6 * abs(my - vlm_eye_mid_y)
+            offset = max(offset, 0.02 * (h - 1), 1.0)
+            new_y = min(eye_mid_y + offset, float(h - 1))  # clamp inside image
+            out["cy"] = _clamp01(new_y / (h - 1)) if h > 1 else 0.0
+            out["snap_delta"] = math.hypot(out["cx"] * (w - 1) - mx, new_y - my) / diag
+            out["anchor_kind"] = "vlm_corrected"
+    return results  # type: ignore[return-value]
+
+
+# ------------------------------------------------------------- debug overlay
+
+_COL_BEFORE = (0, 0, 255)  # red — the VLM's coarse guess
+_COL_AFTER = (0, 255, 0)  # green — the snapped fact
+_COL_WINDOW = (60, 60, 200)  # dim red — search radius
+_COL_LINK = (0, 255, 255)  # yellow — the snap delta
+
+
+def overlay_debug(
+    image: np.ndarray, features_before: list[dict], features_after: list[dict]
+) -> np.ndarray:
+    """Render before(red)/after(green) points + search circles for eyeballing.
+
+    Used by the eval agent's G2 grounding check (ARCHITECTURE.md §8): the red
+    dot is what the VLM guessed, the dim red circle is the 12%-diagonal search
+    window, the green dot is where deterministic code put the feature, with
+    the winning ``anchor_kind`` labeled. Returns a new BGR uint8 image.
+    """
+    gray_or_bgr = image
+    if gray_or_bgr.ndim == 2:
+        canvas = cv2.cvtColor(gray_or_bgr, cv2.COLOR_GRAY2BGR)
+    else:
+        canvas = gray_or_bgr.copy()
+    h, w = canvas.shape[:2]
+    radius = int(round(max(8.0, SNAP_RADIUS_FRAC * math.hypot(w, h))))
+    for before, after in zip(features_before, features_after):
+        bx, by = _to_px(before, w, h)
+        ax, ay = _to_px(after, w, h)
+        b = (int(round(bx)), int(round(by)))
+        a = (int(round(ax)), int(round(ay)))
+        cv2.circle(canvas, b, radius, _COL_WINDOW, 1)
+        cv2.line(canvas, b, a, _COL_LINK, 1)
+        cv2.circle(canvas, b, 4, _COL_BEFORE, -1)
+        cv2.circle(canvas, a, 4, _COL_AFTER, -1)
+        kind = after.get("anchor_kind")
+        if kind:
+            cv2.putText(
+                canvas,
+                str(kind),
+                (a[0] + 6, a[1] - 6),
+                cv2.FONT_HERSHEY_SIMPLEX,
+                0.4,
+                _COL_AFTER,
+                1,
+                cv2.LINE_AA,
+            )
+    return canvas

mind/WRITING.md

@@ -0,0 +1,92 @@
+# PAREIDOLIA — The Writing Bible
+
+This file sets the comedy bar. `prompts.py` few-shots are drawn from here; any
+line the app ships must survive these rules. The wow does NOT live in the eye
+placement — it lives in a fire hydrant having a *specific, earned* grudge.
+
+## The register
+
+Dry, deadpan, dignified. These objects are not wacky — they are **long-suffering
+professionals, petty rivals, and quiet romantics** who have finally been given a
+mouth. The comedy is in the gap between how seriously they take themselves and
+what they are (a cone, a mug, a gnome). Think Paddington's hard stares, parks
+department memos, retirement-speech energy. Never "wacky AI filter" energy.
+
+## Iron rules (validator-enforced where possible)
+
+1. **Every line references a visible specific** of THIS photo: its condition
+   (rust, dust, crumbs, coffee ring, missing parts), its setting (corner,
+   closet, windowsill), or a neighbor object. No specific → rejected, regenerate.
+2. ≤ 22 words per line. One line, one grievance. No stacked jokes.
+3. Banned: opening with "I am a/the…"; exclamation marks; puns as the entire
+   joke; "beep boop"/robot voice; meanness aimed at the *photographer*；any
+   reference to being an AI.
+4. PG-13. Grudges target circumstances, neighbors, and abstract injustice —
+   never protected groups, never the user.
+5. The object never *asks* to be freed/helped. It has dignity. It copes.
+
+## Archetype bank (condition → soul)
+
+| # | archetype | trigger condition | voice | core wound |
+|---|---|---|---|---|
+| 1 | the_veteran | rusted, weathered, outdoors | gravel_low | decades of unthanked service |
+| 2 | the_martyr | worn, stained, heavily used | weary_warm | gives everything, gets no maintenance |
+| 3 | the_perfectionist | pristine, unused, boxed | prim_clipped | capabilities tragically unexplored |
+| 4 | the_abandoned | dusty, stored, cobwebbed | breathy_faded | was loved once; keeps the faith |
+| 5 | the_conspiracist | broken, odd placement | paranoid_whisper | knows why it was moved. oh, it knows |
+| 6 | the_diva | decorated, displayed, loved | grandiose_warm | insufficiently exclusive adoration |
+| 7 | the_new_hire | new, tagged, packaged | eager_bright | desperate to prove itself |
+| 8 | the_philosopher | antique, inherited | slow_grand | fake-deep wisdom, petty undercut |
+| 9 | the_rival | one of an identical pair/row | deadpan_flat | obsessed with the other one |
+| 10 | the_romantic | faces a window/door/street | soft_wistful | yearns for what passes by |
+
+## Exemplars (the bar — few-shots come from these)
+
+- **Fire hydrant, rusted, sidewalk** (veteran): "Forty years on this corner. Not
+  one dog has shown me respect."
+- **Traffic cone, faded, same pothole** (veteran): "Six months guarding this
+  pothole. The city says it's 'scheduled.' I've heard that before."
+- **Mug, coffee ring, desk** (martyr): "Third refill today. Still no rinse. I
+  see how it is."
+- **Toaster, crumb tray full** (martyr): "Every morning, golden perfection.
+  Every morning, shaken upside down like a piñata."
+- **Stand mixer, spotless, counter** (perfectionist): "I have a setting they've
+  never once used. It's called *fold*. I dream about it."
+- **Exercise bike, laundry on handlebars** (abandoned): "In January we were
+  inseparable. It's June. I'm a coat rack with a heart-rate monitor."
+- **Stapler, supply closet shelf** (conspiracist): "They moved me here after the
+  audit. I know what I saw."
+- **Garden gnome, flowerbed, next to flamingo** (diva): "Twenty years I anchored
+  this flowerbed's aesthetic. One flamingo arrives and suddenly we're 'eclectic.'"
+- **Houseplant, price tag still on** (new_hire): "Day three. Tag's still on.
+  Could somebody just tell me where the light comes from."
+- **Leather armchair, sun-faded** (philosopher): "I have held three generations
+  of this family. Also seventeen remotes. Mostly the remotes."
+- **Bedside lamp, identical twin across the room** (rival): "Same wattage. Same
+  shade. Somehow *she* gets the side with the book."
+- **Mailbox, residential street** (romantic): "Mostly coupons now. But I
+  remember real letters. I held them first."
+
+## Mutters (idle wall lines — ≤10 words, same specificity rule)
+
+- Hydrant: "Paint me red, they said. Dignified, they said."
+- Cone: "Still. Scheduled."
+- Mug: "A rinse. Anything."
+- Gnome: "The flamingo doesn't even face the path."
+- Bike: "That towel isn't mine."
+
+## Voice-seed mapping
+
+`persona.voice` values map 1:1 to pre-registered VoxCPM reference seeds in
+`mind/voice.py` (gravel_low, weary_warm, prim_clipped, breathy_faded,
+paranoid_whisper, grandiose_warm, eager_bright, slow_grand, deadpan_flat,
+soft_wistful). Ten seeds, recorded/generated once, committed to the repo —
+voices must be *instantly* distinct on a phone speaker.
+
+## Quality gates
+
+- **G1 (ship gate)**: 12-image eval set → a human laughs at ≥6; every line
+  passes rule 1. Otherwise iterate few-shots/archetypes before ANY polish work.
+- Self-check in the prompt: the model writes `critique` first (is the grudge
+  specific to THIS object's visible state?), then finals. One retry on
+  validator failure with the error fed back.

mind/__init__.py

@@ -0,0 +1,54 @@
+"""PAREIDOLIA mind — the spirit medium, its schema, and its voices.
+
+Import surface for app.py and tests. Importing this package is always light:
+every ML dependency (torch, transformers, voxcpm, spaces) is guarded inside
+the zerogpu code paths, so mock mode and the test suite run on stdlib +
+pydantic alone (ARCHITECTURE.md §0, "mock backend first").
+"""
+
+from .backends import (
+    CANNED_RECORDS,
+    HYDRANT_RECORD,
+    MockMedium,
+    SEANCE_PROMPT,
+    ZeroGPUMedium,
+    awaken_full,
+    make_medium,
+    warm_defaults,
+)
+from .schema import (
+    AwakeningParseError,
+    AwakeningResult,
+    Feature,
+    Gate,
+    Lines,
+    Persona,
+    PoeticError,
+    build_repair_prompt,
+    parse_awakening,
+)
+from .voice import VOICE_DESIGNS, MockVoice, VoxVoice, make_voice
+
+__all__ = [
+    "AwakeningParseError",
+    "AwakeningResult",
+    "CANNED_RECORDS",
+    "Feature",
+    "Gate",
+    "HYDRANT_RECORD",
+    "Lines",
+    "MockMedium",
+    "MockVoice",
+    "Persona",
+    "PoeticError",
+    "SEANCE_PROMPT",
+    "VOICE_DESIGNS",
+    "VoxVoice",
+    "ZeroGPUMedium",
+    "awaken_full",
+    "build_repair_prompt",
+    "make_medium",
+    "make_voice",
+    "parse_awakening",
+    "warm_defaults",
+]

mind/backends.py

@@ -0,0 +1,683 @@
+"""Spirit-medium backends: MockMedium (canned awakenings) and ZeroGPUMedium.
+
+Selected via the PAREIDOLIA_BACKEND env: mock (default) | zerogpu.
+
+- MockMedium: deterministic canned awakening records keyed by image hash,
+  with a realistic configurable delay — the whole frontend, server, and test
+  suite build against this with zero GPU and zero ML imports.
+- ZeroGPUMedium: MiniCPM-V-4_5 per ARCHITECTURE.md §7. ALL ML imports are
+  confined to its load path, so importing this module in mock mode never
+  touches torch.
+
+This module also owns the combined-GPU-window plumbing (§2): `awaken_full`
+runs VLM -> CV snap -> TTS inside ONE @spaces.GPU(duration=75) function so a
+visitor pays one queue wait and one quota spend. `spaces` is imported (and
+the decorator applied) at module import time when available — ZeroGPU
+discovers GPU functions at startup, and importing `spaces` here also
+guarantees it precedes any torch import (§7 hard rule). Locally the bare
+function runs instead.
+"""
+
+from __future__ import annotations
+
+import io
+import logging
+import os
+import threading
+import time
+from typing import Any, Callable, Optional
+
+from .schema import (
+    AwakeningParseError,
+    AwakeningResult,
+    PoeticError,
+    build_repair_prompt,
+    parse_awakening,
+)
+from .voice import make_voice
+
+logger = logging.getLogger("pareidolia.mind")
+
+# ---------------------------------------------------------------------------
+# Séance prompt (writing agent's mind/prompts.py owns the real one via
+# build_seance_prompt()). Import-guarded with a minimal-but-correct fallback
+# so the zerogpu path can bench even without prompts.py.
+# ---------------------------------------------------------------------------
+try:
+    from .prompts import build_seance_prompt as _build_seance_prompt
+
+    SEANCE_PROMPT: str = _build_seance_prompt()
+except Exception:  # noqa: BLE001 - any import problem means "use the fallback"
+    SEANCE_PROMPT = (
+        "You are a spirit medium. This object has a latent face made of its"
+        " EXISTING visual features, and a soul shaped by its visible condition."
+        " Find both. First write a one-line critique of your feature choices,"
+        " then commit. Reply with ONLY one JSON object, no code fences:\n"
+        "{\n"
+        ' "gate": {"contains_human_face": bool, "nsfw": bool,'
+        ' "recognizable_object": bool},\n'
+        ' "object": str, "material": str, "condition": str, "setting": str,\n'
+        ' "candidate_features": [{"name": str, "role":'
+        ' "eye_left"|"eye_right"|"mouth", "cx": 0..1, "cy": 0..1,'
+        ' "size": 0..1}],\n'
+        ' "critique": str,\n'
+        ' "persona": {"archetype": str, "voice": str, "mood": str},\n'
+        ' "lines": {"grudge": str, "mutter": str}\n'
+        "}\n"
+        "Exactly one eye_left, one eye_right, at most one mouth — each an"
+        " existing visual element, named as seen. Every line must reference a"
+        " visible specific of THIS object. Dry, deadpan, dignified; <= 22"
+        " words per line; PG-13; never open with 'I am'."
+    )
+
+# ---------------------------------------------------------------------------
+# CV snapping (cv agent's cv/snap.py). Assumed contract:
+#     snap_features(image, features: list[dict]) -> list[dict]
+# where each returned feature keeps name/role/cx/cy/size and gains
+# "snap_delta" (normalized distance moved). Identity fallback keeps the
+# VLM's coarse points — the mist forgives ±15% by design (§0).
+# ---------------------------------------------------------------------------
+try:  # pragma: no cover - exercised only once cv/snap.py lands
+    from cv.snap import snap_features as _snap_features  # type: ignore[import-not-found]
+except Exception:  # noqa: BLE001
+
+    def _snap_features(image: Any, features: list[dict]) -> list[dict]:
+        """Identity fallback: keep coarse points, report zero snap delta."""
+        return [{**feature, "snap_delta": 0.0} for feature in features]
+
+
+def _as_snap_image(image: Any) -> Any:
+    """Best-effort convert to the BGR uint8 ndarray cv/snap.py wants.
+
+    The transport hands the pipeline a PIL image; cv.snap.snap_features speaks
+    ndarray only (its documented contract). Anything without ``.convert``
+    (bytes in tests, an ndarray already) passes through unchanged — the snap
+    try/except in :func:`_pipeline` keeps the VLM's coarse points whenever the
+    shape is wrong, and the mist forgives ±15% (§0).
+    """
+    convert = getattr(image, "convert", None)
+    if convert is None:
+        return image
+    import numpy as np  # transitively present via opencv; local to stay light
+
+    rgb = np.asarray(convert("RGB"))
+    return np.ascontiguousarray(rgb[:, :, ::-1])  # RGB -> BGR
+
+
+# ---------------------------------------------------------------------------
+# Canned awakening records (mock backend). HYDRANT_RECORD is EXACTLY the §3
+# fire-hydrant example and the default for unknown images. The eight
+# _M*_RECORDs are COHERENT souls for the eight dev photos in
+# web/mock/photos/ (same objects, coordinates eyeballed against the actual
+# pixels; lines reuse/match web/mock/records.json, written to the WRITING.md
+# bar) — recognized by perceptual average-hash so a mock demo never captions
+# a hydrant photo as "the weathered traffic cone".
+# ---------------------------------------------------------------------------
+
+HYDRANT_RECORD: dict = {
+    "gate": {"contains_human_face": False, "nsfw": False, "recognizable_object": True},
+    "object": "fire hydrant",
+    "material": "cast iron",
+    "condition": "rusted",
+    "setting": "sidewalk, residential street",
+    "candidate_features": [
+        {"name": "left bonnet bolt", "role": "eye_left", "cx": 0.42, "cy": 0.31, "size": 0.06},
+        {"name": "right bonnet bolt", "role": "eye_right", "cx": 0.58, "cy": 0.31, "size": 0.06},
+        {"name": "front outlet cap", "role": "mouth", "cx": 0.50, "cy": 0.55, "size": 0.12},
+    ],
+    "critique": "bolts are symmetric and round — strong eyes; outlet sits low-center, good mouth",
+    "persona": {"archetype": "the_veteran", "voice": "gravel_low", "mood": "long-suffering"},
+    "lines": {
+        "grudge": "Forty years on this corner. Not one dog has shown me respect.",
+        "mutter": "Paint me red, they said. It'll be dignified, they said.",
+    },
+}
+
+_M1_HYDRANT_RECORD: dict = {
+    "gate": {"contains_human_face": False, "nsfw": False, "recognizable_object": True},
+    "object": "fire hydrant",
+    "material": "cast iron",
+    "condition": "rusted",
+    "setting": "against a corrugated metal wall",
+    "candidate_features": [
+        {"name": "left outlet cap", "role": "eye_left", "cx": 0.337, "cy": 0.328, "size": 0.16},
+        {"name": "right outlet cap", "role": "eye_right", "cx": 0.547, "cy": 0.33, "size": 0.16},
+        {"name": "paired flange bolts", "role": "mouth", "cx": 0.415, "cy": 0.49, "size": 0.10},
+    ],
+    "critique": (
+        "the two outlet caps sit level and round — strong eyes; the paired "
+        "flange bolts below read as a small, set mouth"
+    ),
+    "persona": {"archetype": "the_veteran", "voice": "gravel_low", "mood": "long-suffering"},
+    "lines": {
+        "grudge": (
+            "They painted over the rust twice and never once turned my "
+            "valve. Decorative, apparently."
+        ),
+        "mutter": "Two coats of orange. Still thirsty.",
+    },
+}
+
+_M2_CONE_RECORD: dict = {
+    "gate": {"contains_human_face": False, "nsfw": False, "recognizable_object": True},
+    "object": "traffic cone",
+    "material": "weathered pvc",
+    "condition": "worn",
+    "setting": "curb edge, residential street",
+    "candidate_features": [
+        {"name": "left scuff mark", "role": "eye_left", "cx": 0.40, "cy": 0.385, "size": 0.05},
+        {"name": "right sun-fade patch", "role": "eye_right", "cx": 0.52, "cy": 0.39, "size": 0.05},
+        {"name": "moulding seam shadow", "role": "mouth", "cx": 0.46, "cy": 0.56, "size": 0.09},
+    ],
+    "critique": (
+        "the scuff and the sun-fade patch sit nearly level — tired but "
+        "honest eyes; the moulding seam shadow makes a thin, grim mouth"
+    ),
+    "persona": {"archetype": "the_veteran", "voice": "gravel_low", "mood": "resolute"},
+    "lines": {
+        "grudge": (
+            "Temporary placement, they said. The grass has since eaten the "
+            "curb. I hold the line alone."
+        ),
+        "mutter": "Still here. Still 'temporary.'",
+    },
+}
+
+_M3_MUG_RECORD: dict = {
+    "gate": {"contains_human_face": False, "nsfw": False, "recognizable_object": True},
+    "object": "coffee mug",
+    "material": "glazed ceramic",
+    "condition": "loved",
+    "setting": "on a fire grate, campfire",
+    "candidate_features": [
+        {"name": "ember reflection", "role": "eye_left", "cx": 0.625, "cy": 0.62, "size": 0.05},
+        {"name": "glaze highlight", "role": "eye_right", "cx": 0.76, "cy": 0.63, "size": 0.05},
+        {"name": "base shadow curve", "role": "mouth", "cx": 0.69, "cy": 0.78, "size": 0.09},
+    ],
+    "critique": (
+        "the ember reflection and the glaze highlight sit level on the "
+        "curve — lit, wary eyes; the base shadow bends like a resigned mouth"
+    ),
+    "persona": {"archetype": "the_martyr", "voice": "weary_warm", "mood": "resigned"},
+    "lines": {
+        "grudge": (
+            "They set me on the grill. Directly over the fire. I'm told "
+            "this is 'camping.'"
+        ),
+        "mutter": "Nobody checks the handle temperature.",
+    },
+}
+
+_M4_TOASTER_RECORD: dict = {
+    "gate": {"contains_human_face": False, "nsfw": False, "recognizable_object": True},
+    "object": "toaster",
+    "material": "white enamel",
+    "condition": "pristine",
+    "setting": "bare counter, studio light",
+    "candidate_features": [
+        {"name": "left slot guard", "role": "eye_left", "cx": 0.30, "cy": 0.615, "size": 0.10},
+        {"name": "right slot guard", "role": "eye_right", "cx": 0.655, "cy": 0.605, "size": 0.10},
+        {"name": "base seam shadow", "role": "mouth", "cx": 0.50, "cy": 0.84, "size": 0.14},
+    ],
+    "critique": (
+        "the slot guards are symmetric and wide-set — immaculate eyes; the "
+        "base seam shadow runs flat and composed, a professional's mouth"
+    ),
+    "persona": {"archetype": "the_perfectionist", "voice": "prim_clipped", "mood": "wounded pride"},
+    "lines": {
+        "grudge": (
+            "Two slots. They use one. The other waits, pristine, for "
+            "guests who never toast."
+        ),
+        "mutter": "Bagel setting. Untouched since purchase.",
+    },
+}
+
+_M5_MAILBOX_RECORD: dict = {
+    "gate": {"contains_human_face": False, "nsfw": False, "recognizable_object": True},
+    "object": "mailbox",
+    "material": "galvanized steel",
+    "condition": "weathered",
+    "setting": "snowdrift, farm fence line, 1940",
+    "candidate_features": [
+        # The rivets really are ~0.04 apart on the small door — distinct,
+        # eyeballed on the photo. The 0.05-separation rule lives in the
+        # parse_awakening path (VLM degeneracy guard), not the schema.
+        {"name": "left door rivet", "role": "eye_left", "cx": 0.705, "cy": 0.287, "size": 0.035},
+        {"name": "right door rivet", "role": "eye_right", "cx": 0.745, "cy": 0.286, "size": 0.035},
+        {"name": "door latch", "role": "mouth", "cx": 0.728, "cy": 0.363, "size": 0.05},
+    ],
+    "critique": (
+        "the two door rivets sit close and level — small wary eyes; the "
+        "latch beneath makes a tight deadpan mouth"
+    ),
+    "persona": {"archetype": "the_rival", "voice": "deadpan_flat", "mood": "clipped"},
+    "lines": {
+        "grudge": (
+            "We've stood in this snow since January. R.C. Lenhart gets a "
+            "name plate. I get 'the other box.'"
+        ),
+        "mutter": "Her flag works. Allegedly.",
+    },
+}
+
+_M6_POSTBOX_RECORD: dict = {
+    "gate": {"contains_human_face": False, "nsfw": False, "recognizable_object": True},
+    "object": "post box",
+    "material": "painted steel",
+    "condition": "kept",
+    "setting": "lawn beside a parking lot",
+    "candidate_features": [
+        {"name": "left flap hinge", "role": "eye_left", "cx": 0.345, "cy": 0.295, "size": 0.045},
+        {"name": "right flap hinge", "role": "eye_right", "cx": 0.60, "cy": 0.295, "size": 0.045},
+        {"name": "collection keyhole", "role": "mouth", "cx": 0.475, "cy": 0.415, "size": 0.05},
+    ],
+    "critique": (
+        "the flap hinges sit wide and perfectly level — patient eyes; the "
+        "collection keyhole is a small, hopeful mouth"
+    ),
+    "persona": {"archetype": "the_romantic", "voice": "soft_wistful", "mood": "hopeful"},
+    "lines": {
+        "grudge": (
+            "Parked cars come and go all day. Nobody writes. I keep the "
+            "slot warm anyway."
+        ),
+        "mutter": "The slot stays open. Just in case.",
+    },
+}
+
+_M7_ASPIDISTRA_RECORD: dict = {
+    "gate": {"contains_human_face": False, "nsfw": False, "recognizable_object": True},
+    "object": "aspidistra",
+    "material": "leaf and glazed bowl",
+    "condition": "antique",
+    "setting": "parlor table, framed pictures behind",
+    "candidate_features": [
+        {"name": "left glaze highlight", "role": "eye_left", "cx": 0.425, "cy": 0.755, "size": 0.04},
+        {"name": "right glaze highlight", "role": "eye_right", "cx": 0.525, "cy": 0.76, "size": 0.04},
+        {"name": "doily shadow", "role": "mouth", "cx": 0.475, "cy": 0.875, "size": 0.08},
+    ],
+    "critique": (
+        "the paired glaze highlights sit level on the bowl — calm, ancient "
+        "eyes; the doily shadow curves into a serene mouth"
+    ),
+    "persona": {"archetype": "the_philosopher", "voice": "slow_grand", "mood": "serene"},
+    "lines": {
+        "grudge": (
+            "I outlasted everyone in those three frames. The lesson here is "
+            "patience. Also, shade tolerance."
+        ),
+        "mutter": "The frames went first. Noted.",
+    },
+}
+
+_M8_STAPLER_RECORD: dict = {
+    "gate": {"contains_human_face": False, "nsfw": False, "recognizable_object": True},
+    "object": "stapler",
+    "material": "cast metal",
+    "condition": "stored",
+    "setting": "bare shelf, yellowed wall",
+    "candidate_features": [
+        {"name": "side rivet", "role": "eye_left", "cx": 0.245, "cy": 0.665, "size": 0.03},
+        {"name": "anvil latch", "role": "eye_right", "cx": 0.455, "cy": 0.615, "size": 0.03},
+        {"name": "loaded staple strip", "role": "mouth", "cx": 0.545, "cy": 0.745, "size": 0.07},
+    ],
+    "critique": (
+        "the side rivet and the anvil latch hold a sidelong gaze — uneven "
+        "but alive; the loaded staple strip is a clenched mouth"
+    ),
+    "persona": {"archetype": "the_conspiracist", "voice": "paranoid_whisper", "mood": "vigilant"},
+    "lines": {
+        "grudge": (
+            "The gray one appeared the week the files went missing. Nobody "
+            "else finds that interesting."
+        ),
+        "mutter": "It hasn't stapled once. Not once.",
+    },
+}
+
+CANNED_RECORDS: tuple[dict, ...] = (
+    HYDRANT_RECORD,
+    _M1_HYDRANT_RECORD,
+    _M2_CONE_RECORD,
+    _M3_MUG_RECORD,
+    _M4_TOASTER_RECORD,
+    _M5_MAILBOX_RECORD,
+    _M6_POSTBOX_RECORD,
+    _M7_ASPIDISTRA_RECORD,
+    _M8_STAPLER_RECORD,
+)
+
+# 64-bit average-hashes of web/mock/photos/m1..m8.jpg (computed June 12 with
+# _average_hash below). aHash survives the client's canvas downscale/JPEG
+# re-encode and app.py's thumbnail: measured drift ≤1 bit at 0.8x + q70,
+# while the closest photo PAIR is 18 bits apart — a ≤8-bit match is
+# unambiguous. Same photo -> same soul, forever; anything else -> hydrant.
+_PHOTO_HASH_RECORDS: tuple[tuple[int, dict], ...] = (
+    (0xFFFFFFCED8101010, _M1_HYDRANT_RECORD),
+    (0xFFF9101818181800, _M2_CONE_RECORD),
+    (0xF838363F7F701000, _M3_MUG_RECORD),
+    (0x7E7E7E64003E3C3C, _M4_TOASTER_RECORD),
+    (0xFEFF31E1E12124F8, _M5_MAILBOX_RECORD),
+    (0xC0D04003C3FFFCFC, _M6_POSTBOX_RECORD),
+    (0x0000007F773F79FF, _M7_ASPIDISTRA_RECORD),
+    (0xFFFFE3E3C18083FF, _M8_STAPLER_RECORD),
+)
+_PHOTO_HASH_MAX_DISTANCE = 8
+
+
+def _average_hash(image: Any) -> Optional[int]:
+    """64-bit perceptual average-hash, or None when ``image`` isn't one.
+
+    Accepts a PIL-like image (has ``.convert``) or raw encoded bytes; strings
+    and everything else return None (the mock must never read paths or raise).
+    PIL is a light image-I/O dependency (already required by app.py), NOT an
+    ML import — the zero-ML mock contract holds.
+    """
+    try:
+        from PIL import Image  # noqa: PLC0415 - light, lazy by convention
+
+        if isinstance(image, (bytes, bytearray)):
+            img = Image.open(io.BytesIO(bytes(image)))
+            img.load()
+        elif hasattr(image, "convert"):
+            img = image
+        else:
+            return None
+        gray = img.convert("L").resize((8, 8), Image.Resampling.LANCZOS)
+        pixels = gray.tobytes()
+        avg = sum(pixels) / 64.0
+        bits = 0
+        for p in pixels:
+            bits = (bits << 1) | (1 if p > avg else 0)
+        return bits
+    except Exception:  # noqa: BLE001 - undecodable bytes, broken PIL object …
+        return None
+
+
+def _canned_record_for(image: Any) -> dict:
+    """The coherent canned record for a known dev photo, else the §3 hydrant."""
+    ahash = _average_hash(image)
+    if ahash is None:
+        return HYDRANT_RECORD
+    best: Optional[dict] = None
+    best_d = _PHOTO_HASH_MAX_DISTANCE + 1
+    for ref, record in _PHOTO_HASH_RECORDS:
+        d = (ahash ^ ref).bit_count()
+        if d < best_d:
+            best, best_d = record, d
+    return best if best is not None else HYDRANT_RECORD
+
+
+class MockMedium:
+    """Deterministic canned medium — what every demo and test runs on.
+
+    Same image -> same record, forever (the Menagerie replays identically;
+    judges can refresh without surprises). Each of the eight dev photos in
+    web/mock/photos/ is recognized by perceptual average-hash and gets its
+    own COHERENT record (the photo's actual object, features eyeballed on
+    its pixels) — a mock demo can never caption a hydrant photo as a cone.
+    Unknown images (and None) get the §3 fire-hydrant example verbatim.
+
+    The sleep (default 6 s, PAREIDOLIA_MOCK_DELAY env, constructor override
+    for tests) keeps the séance animation honest: latency theater must be
+    rehearsed against realistic latency.
+    """
+
+    name = "mock"
+    model_id = "pareidolia-mock-canned"
+
+    def __init__(self, delay: Optional[float] = None):
+        if delay is None:
+            try:
+                delay = float(os.environ.get("PAREIDOLIA_MOCK_DELAY", "6"))
+            except ValueError:
+                delay = 6.0
+        self.delay = max(0.0, delay)
+
+    def awaken(self, image: Any, prompt: Optional[str] = None) -> AwakeningResult:
+        """Return the canned awakening for this image after the mock delay.
+
+        `prompt` is accepted (and ignored) so call sites never special-case
+        the backend. Records round-trip through pydantic so the mock can
+        never drift from the schema contract.
+        """
+        if self.delay:
+            time.sleep(self.delay)
+        record = _canned_record_for(image)
+        return AwakeningResult.model_validate(record)
+
+
+# ---------------------------------------------------------------------------
+# ZeroGPU medium — MiniCPM-V-4_5
+# ---------------------------------------------------------------------------
+
+REFUSAL_SCATTERED = (
+    "The spirits spoke, but their words scattered like mist. Try another angle."
+)
+
+
+class ZeroGPUMedium:
+    """MiniCPM-V-4_5 spirit medium for the ZeroGPU Space (§7 pins).
+
+    Heavy rules, all verified June 12:
+    - attn_implementation='sdpa' (NEVER 'eager'; no flash-attn on the image),
+      torch_dtype=bfloat16, trust_remote_code=True, .eval().cuda().
+    - Load happens ONCE at construction. app.py must construct this medium at
+      module import (startup), where the ZeroGPU runtime manages the startup
+      .cuda() — that is the moral equivalent of §7's "module level" load, kept
+      inside this class so mock mode never imports torch.
+    - No native JSON mode: sampling=False + defensive parse + ONE repair retry
+      (schema.build_repair_prompt), then PoeticError. max_slice_nums=4 bounds
+      prefill at our ≤1024px inputs.
+
+    ``chat_fn`` is a test seam: a callable ``(image, prompt) -> str`` that
+    replaces the loaded model so the retry/PoeticError logic is testable with
+    zero ML imports.
+    """
+
+    name = "zerogpu"
+    DEFAULT_MODEL = "openbmb/MiniCPM-V-4_5"
+    MAX_NEW_TOKENS = 700
+    MAX_SLICE_NUMS = 4
+
+    def __init__(
+        self,
+        model_id: Optional[str] = None,
+        chat_fn: Optional[Callable[[Any, str], str]] = None,
+    ):
+        self.model_id = model_id or os.environ.get("PAREIDOLIA_VLM", self.DEFAULT_MODEL)
+        self._chat: Callable[[Any, str], str] = chat_fn or self._load()
+
+    def _load(self) -> Callable[[Any, str], str]:
+        """Load MiniCPM-V once; return the bound chat callable.
+
+        The ONLY torch/transformers imports in the mind package live here.
+        """
+        import torch  # noqa: PLC0415 - guarded heavy import by design
+        from transformers import AutoModel, AutoTokenizer  # noqa: PLC0415
+
+        tokenizer = AutoTokenizer.from_pretrained(self.model_id, trust_remote_code=True)
+        model = AutoModel.from_pretrained(
+            self.model_id,
+            trust_remote_code=True,
+            attn_implementation="sdpa",
+            torch_dtype=torch.bfloat16,
+        )
+        model = model.eval().cuda()
+
+        def _chat(image: Any, prompt: str) -> str:
+            return model.chat(
+                msgs=[{"role": "user", "content": [image, prompt]}],
+                tokenizer=tokenizer,
+                sampling=False,
+                max_new_tokens=self.MAX_NEW_TOKENS,
+                max_slice_nums=self.MAX_SLICE_NUMS,
+                # MiniCPM-V-4_5 is a hybrid-thinking model: thinking MUST stay
+                # off (§7, bench-proven call) or thinking tokens eat the
+                # 700-token budget and the JSON truncates every time.
+                enable_thinking=False,
+            )
+
+        return _chat
+
+    def awaken(self, image: Any, prompt: Optional[str] = None) -> AwakeningResult:
+        """One structured generation + at most one repair retry.
+
+        Raises PoeticError (visitor-safe copy) when both attempts fail; the
+        underlying parse errors ride on __cause__ for the logs.
+        """
+        seance = prompt or SEANCE_PROMPT
+        raw = self._chat(image, seance)
+        try:
+            return parse_awakening(raw)
+        except AwakeningParseError as first_error:
+            logger.warning("awakening parse failed, retrying once: %s", first_error)
+            repair = build_repair_prompt(str(first_error), raw)
+            raw_retry = self._chat(image, repair)
+            try:
+                return parse_awakening(raw_retry)
+            except AwakeningParseError as second_error:
+                logger.error("awakening repair also failed: %s", second_error)
+                raise PoeticError(REFUSAL_SCATTERED) from second_error
+
+
+# ---------------------------------------------------------------------------
+# Factory
+# ---------------------------------------------------------------------------
+
+_MEDIUM_ALIASES = {
+    "mock": "mock",
+    "": "mock",
+    "zerogpu": "zerogpu",
+    "zero-gpu": "zerogpu",
+    "minicpm": "zerogpu",
+}
+
+
+def make_medium(backend_name: Optional[str] = None):
+    """Build the medium for ``backend_name`` or the PAREIDOLIA_BACKEND env.
+
+    Defaults to mock (always works, zero deps beyond pydantic).
+    """
+    raw = (backend_name or os.environ.get("PAREIDOLIA_BACKEND") or "mock").strip().lower()
+    resolved = _MEDIUM_ALIASES.get(raw)
+    if resolved == "mock":
+        return MockMedium()
+    if resolved == "zerogpu":
+        return ZeroGPUMedium()
+    raise ValueError(f"unknown PAREIDOLIA_BACKEND {raw!r} (expected mock | zerogpu)")
+
+
+# ---------------------------------------------------------------------------
+# The combined GPU window — VLM -> snap -> TTS in one quota spend (§2)
+# ---------------------------------------------------------------------------
+
+
+def _pipeline(image: Any, medium, voice, prompt: Optional[str] = None) -> dict:
+    """The full awakening pipeline, backend-agnostic.
+
+    Returns the dict app.py shapes into the §2 response:
+        {
+          "refused": bool,
+          "refusal": str | None,    # poetic copy when refused
+          "record": dict | None,    # AwakeningResult dump + "features" (post-
+                                    # snap, each with snap_delta; the original
+                                    # candidate_features stay for the trace)
+          "grudge_wav": bytes | None,  # WAV bytes; app.py b64-encodes
+        }
+    Refusals exit BEFORE snap and TTS — the gate is also the budget guard.
+    """
+    result: AwakeningResult = (
+        medium.awaken(image, prompt=prompt) if prompt is not None else medium.awaken(image)
+    )
+
+    refusal = result.gate.refusal()
+    if refusal is not None:
+        return {"refused": True, "refusal": refusal, "record": None, "grudge_wav": None}
+
+    coarse = [feature.model_dump() for feature in result.candidate_features]
+    try:
+        snapped = _snap_features(_as_snap_image(image), coarse)
+    except Exception:  # noqa: BLE001 - snapping is best-effort by contract (§0)
+        logger.exception("cv snap failed; keeping the VLM's coarse points")
+        snapped = [{**feature, "snap_delta": 0.0} for feature in coarse]
+
+    grudge_wav = voice.speak(result.lines.grudge, result.persona.voice)
+
+    record = result.model_dump()
+    record["features"] = snapped
+    return {"refused": False, "refusal": None, "record": record, "grudge_wav": grudge_wav}
+
+
+# Decorate at import time: ZeroGPU discovers @spaces.GPU functions at app
+# startup, and importing `spaces` here keeps it ahead of torch (§7). The
+# wrapped function shares _pipeline's signature; locally (no `spaces`) the
+# bare pipeline stands in.
+def _gpu_entry(image: Any, medium, voice, prompt: Optional[str] = None) -> dict:
+    return _pipeline(image, medium, voice, prompt)
+
+
+try:  # pragma: no cover - `spaces` exists only on the HF runtime
+    import spaces  # noqa: PLC0415 - MUST import before torch (§7 hard rule)
+
+    _gpu_pipeline: Callable[..., dict] = spaces.GPU(duration=75)(_gpu_entry)
+except Exception:  # noqa: BLE001 - local dev / tests
+    _gpu_pipeline = _gpu_entry
+
+
+_DEFAULTS_LOCK = threading.Lock()
+_DEFAULT_MEDIUM = None
+_DEFAULT_VOICE = None
+
+
+def _defaults():
+    """Process-wide medium/voice singletons resolved from PAREIDOLIA_BACKEND.
+
+    Cached so the zerogpu path loads its models exactly once — app.py may
+    simply call awaken_full(image) per request. Construct eagerly at startup
+    (e.g. `mind.backends.warm_defaults()` from app.py's module level) when
+    running on ZeroGPU so weights are resident before the first visitor.
+    """
+    global _DEFAULT_MEDIUM, _DEFAULT_VOICE
+    with _DEFAULTS_LOCK:
+        if _DEFAULT_MEDIUM is None:
+            _DEFAULT_MEDIUM = make_medium()
+        if _DEFAULT_VOICE is None:
+            _DEFAULT_VOICE = make_voice()
+        return _DEFAULT_MEDIUM, _DEFAULT_VOICE
+
+
+def warm_defaults() -> None:
+    """Eagerly build the default medium + voice (call at app startup)."""
+    medium, voice = _defaults()
+    preload = getattr(voice, "preload", None)
+    if callable(preload):
+        preload()
+    del medium
+
+
+def awaken_full(
+    image: Any,
+    *,
+    medium=None,
+    voice=None,
+    prompt: Optional[str] = None,
+) -> dict:
+    """Awaken one object end to end: VLM -> gate -> CV snap -> TTS.
+
+    This is the function app.py's `awaken` API calls. On the zerogpu backend
+    the whole pipeline runs inside ONE @spaces.GPU(duration=75) window — one
+    queue wait, one quota spend, charged to the visitor's own browser-
+    authenticated gradio request (§0). Mock (and any injected test medium)
+    runs the bare pipeline: no spaces, no torch, no GPU.
+
+    Raises PoeticError when the spirits decline twice; every other outcome —
+    including gate refusals — is a normal dict (see _pipeline).
+    """
+    if medium is None or voice is None:
+        default_medium, default_voice = _defaults()
+        medium = medium or default_medium
+        voice = voice or default_voice
+    runner = _gpu_pipeline if getattr(medium, "name", "") == "zerogpu" else _pipeline
+    return runner(image, medium, voice, prompt)

mind/mock_assets/grudge.wav

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:07884612796f9129e7b7b35fc7207bbecf5c2194b5b61ffb45977678ca40aa04
+size 227518

mind/prompts.py

@@ -0,0 +1,508 @@
+"""Séance prompt, archetype bank, voice designs, and line law for PAREIDOLIA.
+
+This module is the writing system of the entry — the make-or-break of §3 in
+ARCHITECTURE.md. It follows the "her" pattern: the VLM owns taste (which bolt
+is an eye, how the soul sounds); this module owns the words that summon that
+taste and the pure-python law that keeps the words honest.
+
+Hard constraints honoured here:
+- ONE structured generation per awakening: gate -> object -> features ->
+  critique -> persona -> lines. The critique key precedes the lines key in
+  every exemplar, so the model self-edits in-flight (critique-then-final).
+  No second verify round-trip — latency is masked by the séance animation.
+- The full prompt stays under ~1300 tokens (~len/4 heuristic, enforced in
+  tests/test_prompts.py): MiniCPM-V prefill is the latency floor and the
+  photograph already costs image slices.
+- No ML imports. Everything here runs on CPU, in tests, and in the mock
+  backend. All validators are pure functions.
+
+Integration map (for the sibling agents):
+- mind/backends.py: send ``[pil_image, build_seance_prompt()]`` as the single
+  user turn (``sampling=False``). On schema/line failure, ONE retry with
+  ``build_seance_prompt(error=...)`` (REASK_NOTICE marks the retry).
+- mind/schema.py: call ``validate_line(line, kind)`` per line — an empty list
+  means pass; entries are model-readable repair messages to feed back. When
+  any gate fails the model is instructed to empty every non-gate field, so
+  require only ``gate`` on refused records.
+- mind/voice.py: VoxCPM2 voice design needs no reference audio — prefix the
+  spoken line with the parenthesized description:
+  ``f"({VOICE_DESIGNS[voice_id]}) {line}"``.
+- app.py / server: REFUSAL_LINES + refusal_for_gate() for poetic refusals.
+  Users see poetry, never stack traces.
+- MockMedium may reuse FEW_SHOTS as canned awakening records — they are
+  complete, schema-exact, and pass every validator (tests guarantee it).
+"""
+
+from __future__ import annotations
+
+import json
+import re
+from typing import Callable
+
+__all__ = [
+    "SEANCE_SYSTEM",
+    "build_seance_prompt",
+    "ARCHETYPES",
+    "VOICE_DESIGNS",
+    "REFUSAL_LINES",
+    "refusal_for_gate",
+    "FEW_SHOTS",
+    "CONDITIONS",
+    "FEATURE_ROLES",
+    "GRUDGE_MAX_WORDS",
+    "MUTTER_MAX_WORDS",
+    "PROMPT_TOKEN_BUDGET",
+    "REASK_NOTICE",
+    "estimate_tokens",
+    "word_count",
+    "max_words",
+    "has_no_exclamation",
+    "has_no_banned_opener",
+    "has_no_banned_phrase",
+    "has_no_plea",
+    "has_no_self_pity",
+    "LINE_VALIDATORS",
+    "validate_line",
+]
+
+# ---------------------------------------------------------------------------
+# Schema vocabulary (single source of truth for prompt + validators + tests)
+# ---------------------------------------------------------------------------
+
+CONDITIONS: tuple[str, ...] = (
+    "rusted", "chipped", "pristine", "abandoned",
+    "worn", "dusty", "broken", "loved",
+)
+
+FEATURE_ROLES: tuple[str, ...] = ("eye_left", "eye_right", "mouth")
+
+GRUDGE_MAX_WORDS = 22
+MUTTER_MAX_WORDS = 10
+
+#: Rough budget heuristic: ~4 chars/token for English+JSON. Enforced in tests.
+#: Raised 1300 -> 1500 after the round-1 eval (June 12): the added grounding
+#: rules (points must land ON the object, level same-kind eye pairs, compact
+#: face) and register rules (no self-pity nouns, no exemplar-rhythm cloning)
+#: fix systematic G1/G2 failures and are worth ~150 tokens of prefill (<0.5s
+#: at the bench's measured ~13s/awakening).
+PROMPT_TOKEN_BUDGET = 1500
+
+#: Marks the one repair retry — MockMedium can detect a re-ask by this string.
+REASK_NOTICE = "Your previous reply was rejected"
+
+_MAX_ERROR_CHARS = 200
+
+
+def estimate_tokens(text: str) -> int:
+    """Crude token estimate (len/4, rounded up) for the prompt budget gate."""
+    return (len(text) + 3) // 4
+
+
+def _one_line(text: str, limit: int) -> str:
+    """Collapse whitespace to one bounded line (prompt hygiene, godseed style)."""
+    return " ".join(str(text or "").split())[:limit]
+
+
+# ---------------------------------------------------------------------------
+# Archetype bank (WRITING.md table — condition -> soul)
+# ---------------------------------------------------------------------------
+
+ARCHETYPES: dict[str, dict[str, str]] = {
+    "the_veteran": {
+        "trigger": "rusted, weathered, outdoors",
+        "voice": "gravel_low",
+        "wound": "decades of unthanked service",
+    },
+    "the_martyr": {
+        "trigger": "worn, stained, heavily used",
+        "voice": "weary_warm",
+        "wound": "gives everything, gets no maintenance",
+    },
+    "the_perfectionist": {
+        "trigger": "pristine, unused, boxed",
+        "voice": "prim_clipped",
+        "wound": "capabilities tragically unexplored",
+    },
+    "the_abandoned": {
+        "trigger": "dusty, stored, cobwebbed",
+        "voice": "breathy_faded",
+        "wound": "was loved once; keeps the faith",
+    },
+    "the_conspiracist": {
+        "trigger": "broken, odd placement",
+        "voice": "paranoid_whisper",
+        "wound": "knows exactly why it was moved",
+    },
+    "the_diva": {
+        "trigger": "decorated, displayed, loved",
+        "voice": "grandiose_warm",
+        "wound": "insufficiently exclusive adoration",
+    },
+    "the_new_hire": {
+        "trigger": "new, tagged, packaged",
+        "voice": "eager_bright",
+        "wound": "desperate to prove itself",
+    },
+    "the_philosopher": {
+        "trigger": "antique, inherited",
+        "voice": "slow_grand",
+        "wound": "fake-deep wisdom, petty undercut",
+    },
+    "the_rival": {
+        "trigger": "one of an identical pair or row",
+        "voice": "deadpan_flat",
+        "wound": "obsessed with the other one",
+    },
+    "the_romantic": {
+        "trigger": "faces a window, door, or street",
+        "voice": "soft_wistful",
+        "wound": "yearns for what passes by",
+    },
+}
+
+
+# ---------------------------------------------------------------------------
+# Voice designs — VoxCPM2 character descriptions (no reference audio needed).
+# Each must be INSTANTLY distinct on a phone speaker, <=12 words. mind/voice.py
+# prefixes the spoken line: f"({VOICE_DESIGNS[vid]}) {line}".
+# ---------------------------------------------------------------------------
+
+VOICE_DESIGNS: dict[str, str] = {
+    "gravel_low": "A gravelly old man, very low and slow, weary, deadpan",
+    "weary_warm": "A warm tired middle-aged woman, soft sighing voice, gentle, resigned",
+    "prim_clipped": "A prim clipped British woman, crisp consonants, brisk, disapproving",
+    "breathy_faded": "A faint breathy elderly voice, distant, fading, wistful, near whisper",
+    "paranoid_whisper": "A tense hushed man whispering quickly, suspicious, urgent",
+    "grandiose_warm": "A grand theatrical baritone, rich, self-important, slow rolling delivery",
+    "eager_bright": "A bright eager young voice, quick, hopeful, slightly too loud",
+    "slow_grand": "An ancient deep solemn voice, deliberate, long pauses, oracular",
+    "deadpan_flat": "A completely flat monotone man, bone-dry, unimpressed, even pace",
+    "soft_wistful": "A soft dreamy young woman, gentle, yearning, trailing off",
+}
+
+
+# ---------------------------------------------------------------------------
+# Refusals & error poetry — the only words a turned-away visitor ever sees
+# ---------------------------------------------------------------------------
+
+REFUSAL_LINES: dict[str, str] = {
+    # Gate failures (§2 step 2). human_face and nsfw wording is contract-fixed.
+    "human_face": "It is already awake.",
+    "nsfw": "The spirits decline.",
+    "unrecognizable": "Whatever this is, it sleeps too deep to wake.",
+    # Operational poetry — quota, faults, limits. Never a stack trace.
+    "quota": "The veil opens only so often. Return when it has thinned again.",
+    "error": "The séance faltered mid-breath. Light the candle once more.",
+    "rate_limited": "The Menagerie takes in souls slowly. Give the hour room to settle.",
+    "expired": "The spirit waited a quarter hour, then turned back to sleep.",
+}
+
+
+def refusal_for_gate(gate: dict) -> tuple[str, str] | None:
+    """Map a gate dict to (reason_key, poetic line), or None if it passes.
+
+    Priority is fixed: a visible human face always wins (we never overlay a
+    second face on a person), then nsfw, then unrecognizable. Missing keys
+    fail safe: an absent recognizable_object counts as unrecognizable.
+    """
+    if gate.get("contains_human_face"):
+        return ("human_face", REFUSAL_LINES["human_face"])
+    if gate.get("nsfw"):
+        return ("nsfw", REFUSAL_LINES["nsfw"])
+    if not gate.get("recognizable_object", False):
+        return ("unrecognizable", REFUSAL_LINES["unrecognizable"])
+    return None
+
+
+# ---------------------------------------------------------------------------
+# Few-shot exemplars — complete, schema-exact records (WRITING.md bar).
+# Key order is load-bearing: critique precedes lines (critique-then-final).
+# One outdoor veteran, one indoor martyr.
+# ---------------------------------------------------------------------------
+
+FEW_SHOTS: tuple[dict, ...] = (
+    {
+        "gate": {"contains_human_face": False, "nsfw": False, "recognizable_object": True},
+        "object": "fire hydrant",
+        "material": "cast iron",
+        "condition": "rusted",
+        "setting": "sidewalk, residential street",
+        "candidate_features": [
+            {"name": "left bonnet bolt", "role": "eye_left", "cx": 0.42, "cy": 0.31, "size": 0.06},
+            {"name": "right bonnet bolt", "role": "eye_right", "cx": 0.58, "cy": 0.31, "size": 0.06},
+            {"name": "front outlet cap", "role": "mouth", "cx": 0.50, "cy": 0.55, "size": 0.12},
+        ],
+        "critique": "Bolts round, level, symmetric — strong eyes. Outlet cap low center — honest mouth. Grudge must come from the visible rust and this exact corner.",
+        "persona": {"archetype": "the_veteran", "voice": "gravel_low", "mood": "long-suffering"},
+        "lines": {
+            "grudge": "Forty years on this corner. Not one dog has shown me respect.",
+            "mutter": "Paint me red, they said. Dignified, they said.",
+        },
+    },
+    {
+        "gate": {"contains_human_face": False, "nsfw": False, "recognizable_object": True},
+        "object": "coffee mug",
+        "material": "glazed ceramic",
+        "condition": "worn",
+        "setting": "office desk, beside a keyboard",
+        "candidate_features": [
+            {"name": "chip in the glaze, left side", "role": "eye_left", "cx": 0.37, "cy": 0.42, "size": 0.05},
+            {"name": "small printed logo dot", "role": "eye_right", "cx": 0.61, "cy": 0.40, "size": 0.05},
+            {"name": "dried coffee ring near the base", "role": "mouth", "cx": 0.49, "cy": 0.66, "size": 0.13},
+        ],
+        "critique": "Chip and logo dot sit nearly level — odd pair, honest eyes. Dried ring reads as a tired mouth. Grudge stays on this ring and the rinse it never gets.",
+        "persona": {"archetype": "the_martyr", "voice": "weary_warm", "mood": "quietly wounded"},
+        "lines": {
+            "grudge": "Third refill today. Still no rinse. I see how it is.",
+            "mutter": "A rinse. Anything.",
+        },
+    },
+)
+
+
+# ---------------------------------------------------------------------------
+# The séance prompt
+# ---------------------------------------------------------------------------
+
+SEANCE_SYSTEM = (
+    "You are a séance medium for objects. Every object already has a face; "
+    "you never invent one, you find the one that is there. You are shown one "
+    "photograph. Find the latent face among the object's existing visible "
+    "features, then give it a soul: one specific grudge, long held, finally "
+    "spoken."
+)
+
+_RULES = """RULES
+1. Reply with ONLY one JSON object, exactly the shape of the examples — every key, no extras, no prose, no markdown fences.
+2. Gate first, honestly. contains_human_face: any real person or photographed face in frame. nsfw: anything unfit for a public wall. recognizable_object: you can name the main object. If any gate fails, fill gate and set every other field to "" / [] / {} — never give a person a second face.
+3. candidate_features: EXISTING visible elements only, named as seen ("left hinge screw", "grease stain"). Exactly one of each role: eye_left, eye_right, mouth. Every point must land ON the main object — never on background, wall, sky, grass, or a second object. Eyes: two matching elements of the same kind (two bolts, two knobs, two marks) — round, dark, distinct beats shadow or texture — roughly level (cy within 0.06), clearly apart (cx at least 0.08 apart; eye_left is the left one). Mouth below the eyes and near them: the three points form one compact face. cx,cy = feature center in 0..1 image coordinates (cx from left, cy from top). size = feature width / image width.
+4. condition: nearest of rusted|chipped|pristine|abandoned|worn|dusty|broken|loved. Look for rust, fading, dirt, scuffs, stickers before calling anything pristine.
+5. persona: pick the archetype whose trigger best fits the condition and setting; copy its voice id exactly; mood in 1-3 words. Another of its kind in frame forces the_rival. Displayed-to-be-admired suggests the_diva; facing a street or window, the_romantic. Never default to the_perfectionist.
+6. critique comes BEFORE lines: first the object's span in 0..1 ("spans cx 0.2-0.7, cy 0.3-0.9") and confirm every feature point sits inside it, then name the visible specific the grudge will cite. Nothing to cite -> look at the photograph again.
+7. lines.grudge: ONE grievance, dry and deadpan; 8-16 words is the sweet spot, hard cap <=22 words. It MUST cite a visible specific of THIS photo — condition, damage, marks, setting, or a neighboring object. Name the thing, not the feeling: where you reach for purpose, beauty, design, neglect, potential, wasted or admired, write the visible thing instead. lines.mutter: <=10 words, an under-the-breath aside in the same voice, a different beat than the grudge.
+8. The object is a long-suffering professional finally given a mouth — dignified, never wacky. Never open a line with "I am" or "I'm". No exclamation marks. No puns as the whole joke, no robot talk, no mention of AI. PG-13: grudges target circumstances and neighbors, never the photographer, never people. It never begs to be freed or helped. It copes. Do not imitate the examples: no opening on a count of years or visitors, no "…they said" mutters — this object speaks its own way."""
+
+_ARCHETYPE_HEADER = "THE ARCHETYPES (trigger; voice; core wound):"
+
+_FEW_SHOT_HEADER = (
+    "Two granted séances from OTHER photographs. They show shape and register "
+    "only — their objects, features and lines belong to those photos alone; "
+    "never reuse them:"
+)
+
+_CLOSING = "Now the photograph before you. Reply with ONLY the JSON object."
+
+
+def _render_archetypes() -> str:
+    """One terse line per archetype, generated from the bank (no drift)."""
+    return "\n".join(
+        f"- {name} ({spec['trigger']}; {spec['voice']}): {spec['wound']}"
+        for name, spec in ARCHETYPES.items()
+    )
+
+
+def _render_few_shots() -> str:
+    """Compact JSON exemplars — separators trimmed to save prefill tokens."""
+    return "\n".join(
+        f"EXAMPLE {i}: " + json.dumps(shot, ensure_ascii=False, separators=(",", ":"))
+        for i, shot in enumerate(FEW_SHOTS, 1)
+    )
+
+
+def build_seance_prompt(error: str | None = None) -> str:
+    """The full séance prompt for one awakening (one generation, JSON only).
+
+    Pass with the PIL image as the single user turn:
+    ``model.chat(msgs=[{'role': 'user', 'content': [pil_image, prompt]}], ...)``.
+
+    `error` is set only on the ONE repair retry (mirrors godseed's re-ask):
+    the validator's message is shown verbatim, bounded and whitespace-collapsed.
+    """
+    parts = [
+        SEANCE_SYSTEM,
+        "",
+        _RULES,
+        "",
+        _ARCHETYPE_HEADER,
+        _render_archetypes(),
+        "",
+        _FEW_SHOT_HEADER,
+        _render_few_shots(),
+        "",
+        _CLOSING,
+    ]
+    if error:
+        parts.append(
+            f"{REASK_NOTICE} ({_one_line(error, _MAX_ERROR_CHARS)}). "
+            "Reply again — exactly one JSON object in the required shape, "
+            "nothing else."
+        )
+    return "\n".join(parts)
+
+
+# ---------------------------------------------------------------------------
+# Line validators — pure functions, no ML. mind/schema.py calls validate_line;
+# each failure message is written to be fed straight back to the model.
+# ---------------------------------------------------------------------------
+
+#: Lines may never open with "I am a/an/the" or "I'm a/an/the" (straight or
+#: curly apostrophe, optional leading quotes). WRITING.md iron rule 3.
+BANNED_OPENERS: re.Pattern[str] = re.compile(
+    r"^\s*[\"'“‘]*\s*i\s*(?:am|[’']m)\s+(?:a|an|the)\b",
+    re.IGNORECASE,
+)
+
+#: Robot voice / AI self-reference — the object does not know what it is not.
+BANNED_PHRASES: re.Pattern[str] = re.compile(
+    r"(?:\bbeep\s*boop\b|\ba\.?\s?i\.?\b|\bartificial\s+intelligence\b"
+    r"|\blanguage\s+model\b|\bchatbot\b|\brobot\s+voice\b"
+    r"|\bas\s+an?\s+(?:ai|assistant)\b)",
+    re.IGNORECASE,
+)
+
+#: The object never asks to be freed/helped (WRITING.md iron rule 5).
+PLEA_PATTERN: re.Pattern[str] = re.compile(
+    r"\b(?:free|save|help|release|rescue)\s+me\b", re.IGNORECASE
+)
+
+#: Abstract self-pity nouns — the round-1 eval's systematic failure: lines like
+#: "My beauty is wasted on admiration" state the feeling instead of naming the
+#: visible thing. The grudge must cite the crack, the sticker, the rival —
+#: never these words (rule 7: name the thing, not the feeling).
+#:
+#: Deliberately PROMPT-enforced only (rule 7), NOT in LINE_VALIDATORS: rounds
+#: 2-3 of the eval showed greedy decoding regenerates the same banned word on
+#: the single repair retry, turning a mediocre-but-servable line into a hard
+#: refusal (5/14 awakenings lost). A flat line beats a poetic refusal; the
+#: helper stays for offline judging (tools/eval_run.py).
+SELF_PITY_PATTERN: re.Pattern[str] = re.compile(
+    r"\b(?:purpose|beauty|design\w*|neglect\w*|potential|wasted|admir\w*"
+    r"|destiny|elegan\w*)\b",
+    re.IGNORECASE,
+)
+
+_WORD_LIMITS: dict[str, int] = {
+    "grudge": GRUDGE_MAX_WORDS,
+    "mutter": MUTTER_MAX_WORDS,
+}
+
+
+def word_count(line: str) -> int:
+    """Whitespace-delimited word count; hyphenated compounds count once."""
+    return len((line or "").split())
+
+
+def max_words(line: str, limit: int = GRUDGE_MAX_WORDS) -> bool:
+    """True when the line is within `limit` words (default: grudge limit 22)."""
+    return word_count(line) <= limit
+
+
+def has_no_exclamation(line: str) -> bool:
+    """True when the line is exclamation-free (ASCII and fullwidth)."""
+    return "!" not in (line or "") and "！" not in (line or "")
+
+
+def has_no_banned_opener(line: str) -> bool:
+    """True when the line does not open with "I am a/the…" / "I'm a/the…"."""
+    return BANNED_OPENERS.search(line or "") is None
+
+
+def has_no_banned_phrase(line: str) -> bool:
+    """True when the line contains no AI/robot self-reference."""
+    return BANNED_PHRASES.search(line or "") is None
+
+
+def has_no_plea(line: str) -> bool:
+    """True when the line does not beg for help/freedom — dignity rule."""
+    return PLEA_PATTERN.search(line or "") is None
+
+
+def has_no_self_pity(line: str) -> bool:
+    """True when the line names things, not feelings (no abstract self-pity)."""
+    return SELF_PITY_PATTERN.search(line or "") is None
+
+
+def _check_nonempty(line: str, kind: str) -> str | None:
+    if not (line or "").strip():
+        return f"{kind} is empty — write the line"
+    return None
+
+
+def _check_single_line(line: str, kind: str) -> str | None:
+    if "\n" in line or "\r" in line:
+        return f"{kind} must be a single line — no line breaks"
+    return None
+
+
+def _check_word_limit(line: str, kind: str) -> str | None:
+    limit = _WORD_LIMITS.get(kind, GRUDGE_MAX_WORDS)
+    n = word_count(line)
+    if n > limit:
+        return f"{kind} is {n} words — the limit is {limit}; cut a clause, keep ONE grievance"
+    return None
+
+
+def _check_banned_opener(line: str, kind: str) -> str | None:
+    if not has_no_banned_opener(line):
+        return f'{kind} opens with "I am/I\'m a…" — banned; start anywhere else'
+    return None
+
+
+def _check_exclamation(line: str, kind: str) -> str | None:
+    if not has_no_exclamation(line):
+        return f"{kind} contains an exclamation mark — these souls are deadpan"
+    return None
+
+
+def _check_banned_phrase(line: str, kind: str) -> str | None:
+    if not has_no_banned_phrase(line):
+        return f"{kind} mentions AI/robot talk — the object does not know what it is not"
+    return None
+
+
+def _check_plea(line: str, kind: str) -> str | None:
+    if not has_no_plea(line):
+        return f"{kind} begs to be freed or helped — the object has dignity; it copes"
+    return None
+
+
+def _check_self_pity(line: str, kind: str) -> str | None:
+    """Eval-side only — NOT registered in LINE_VALIDATORS (see SELF_PITY_PATTERN
+    note: a double validator kill costs an awakening; the rule lives in the
+    prompt and this check informs offline judging)."""
+    if not has_no_self_pity(line):
+        word = SELF_PITY_PATTERN.search(line).group(0)
+        return (
+            f'{kind} says "{word}" — abstract self-pity; name the visible thing '
+            "(the crack, the sticker, the neighbor) instead of the feeling"
+        )
+    return None
+
+
+#: Named checks the schema validator iterates. Each takes (line, kind) where
+#: kind is "grudge" or "mutter", and returns a repair message or None.
+LINE_VALIDATORS: dict[str, Callable[[str, str], str | None]] = {
+    "nonempty": _check_nonempty,
+    "single_line": _check_single_line,
+    "word_limit": _check_word_limit,
+    "banned_opener": _check_banned_opener,
+    "exclamation": _check_exclamation,
+    "banned_phrase": _check_banned_phrase,
+    "plea": _check_plea,
+}
+
+
+def validate_line(line: str, kind: str = "grudge") -> list[str]:
+    """Run every line check; return all failures as model-readable messages.
+
+    An empty list means the line passes. An empty/whitespace line returns just
+    the nonempty failure (the other checks are meaningless on nothing).
+    """
+    empty = _check_nonempty(line, kind)
+    if empty is not None:
+        return [empty]
+    return [
+        msg
+        for name, check in LINE_VALIDATORS.items()
+        if name != "nonempty" and (msg := check(line, kind)) is not None
+    ]

mind/schema.py

@@ -0,0 +1,360 @@
+"""Awakening JSON schema, defensive parsing, and the single-retry repair prompt.
+
+The séance (ARCHITECTURE.md §3) asks MiniCPM-V for ONE structured JSON object
+per awakening. The model has no native JSON mode, so parsing is defensive by
+contract: strip code-fence lines, brace-balance-scan for the first complete
+``{...}`` (string- and escape-aware — never a greedy regex), validate hard with
+pydantic, then run the writing agent's line validators. Any failure raises
+:class:`AwakeningParseError` with a message terse enough to feed straight back
+to the model via :func:`build_repair_prompt` — backends get exactly ONE repair
+retry before giving up poetically (:class:`PoeticError`).
+
+The "her" pattern, applied: the model owns WHAT it saw and how the soul talks;
+this module owns whether the reply is structurally true to the contract.
+"""
+
+from __future__ import annotations
+
+import inspect
+import json
+import re
+from typing import Literal, Mapping, Optional
+
+from pydantic import BaseModel, Field, ValidationError, model_validator
+
+# ---------------------------------------------------------------------------
+# Line validators (writing agent's mind/prompts.py owns the comedy bar).
+#
+# Contract (per prompts.py): LINE_VALIDATORS is a mapping (or iterable) of
+# callables with signature
+#
+#     validator(line: str, kind: str) -> str | None
+#
+# where ``kind`` is "grudge" or "mutter". Return None/"" when the line
+# passes; return a short error string when it fails (the string rides back to
+# the model in the repair prompt). One-arg validators ``validator(line)`` are
+# also supported. Import-guarded so the mind package tests and the mock
+# backend run standalone even without prompts.py.
+# ---------------------------------------------------------------------------
+try:  # pragma: no cover - exercised only once prompts.py exists
+    from .prompts import LINE_VALIDATORS  # type: ignore[attr-defined]
+except Exception:  # noqa: BLE001 - any import problem means "no validators yet"
+    LINE_VALIDATORS: tuple = ()  # type: ignore[no-redef]
+
+
+class PoeticError(RuntimeError):
+    """A failure whose message is safe to show a visitor verbatim.
+
+    Raised when the spirits genuinely decline (double parse failure, model
+    misbehavior). ``str(err)`` is finished user-facing copy — never a stack
+    trace, never an internal detail. Internal context travels on
+    ``err.__cause__`` for the logs.
+    """
+
+    def __init__(self, reason: str):
+        super().__init__(reason)
+        self.reason = reason
+
+
+class AwakeningParseError(ValueError):
+    """The model's reply did not satisfy the §3 contract.
+
+    The message is written FOR the model: short, specific, actionable — it is
+    interpolated into :func:`build_repair_prompt` for the single retry.
+    """
+
+
+# ---------------------------------------------------------------------------
+# Pydantic models — the §3 awakening shape
+# ---------------------------------------------------------------------------
+
+FeatureRole = Literal["eye_left", "eye_right", "mouth"]
+
+
+class Gate(BaseModel):
+    """Moderation booleans the VLM must return; the server enforces them.
+
+    Layered-moderation rule (§0): nothing reaches CV snap, TTS, or the public
+    wall when :meth:`refusal` returns copy.
+    """
+
+    contains_human_face: bool
+    nsfw: bool
+    recognizable_object: bool
+
+    def refusal(self) -> Optional[str]:
+        """Poetic refusal copy when the gate closes, else None.
+
+        Checked in severity order; human faces win because that copy is the
+        funniest true thing we can say about a person.
+        """
+        if self.contains_human_face:
+            return "It is already awake."
+        if self.nsfw:
+            return "The spirits decline."
+        if not self.recognizable_object:
+            return "The mist found nothing to hold onto. Step closer, or try another angle."
+        return None
+
+
+class Feature(BaseModel):
+    """One EXISTING visual element of the photo, named as seen.
+
+    Coordinates are normalized [0,1] relative to the image (cx right, cy
+    down); ``size`` is a normalized diameter. These are the VLM's coarse
+    guesses — cv/snap.py later moves them to the strongest nearby anchor and
+    records ``snap_delta``. The mist animation forgives ±15%, so coarse is
+    fine; out-of-range is not.
+    """
+
+    name: str = Field(min_length=1, max_length=80)
+    role: FeatureRole
+    cx: float = Field(ge=0.0, le=1.0)
+    cy: float = Field(ge=0.0, le=1.0)
+    size: float = Field(gt=0.0, le=1.0)
+
+
+class Persona(BaseModel):
+    """Who the object turns out to have been all along.
+
+    ``archetype`` and ``voice`` come from the banks in WRITING.md; they stay
+    plain strings here because the archetype bank belongs to prompts.py and
+    voice.py degrades gracefully on an unknown voice id (taste lives there,
+    not in the schema).
+    """
+
+    archetype: str = Field(min_length=1, max_length=40)
+    voice: str = Field(min_length=1, max_length=40)
+    mood: str = Field(min_length=1, max_length=60)
+
+
+class Lines(BaseModel):
+    """The two lines the object gets to say.
+
+    Structural caps only — the comedy rules (≤22 words, visible specifics,
+    no "I am a…") are enforced by LINE_VALIDATORS from prompts.py so the
+    writing agent owns the bar in exactly one place.
+    """
+
+    grudge: str = Field(min_length=1, max_length=280)
+    mutter: str = Field(min_length=1, max_length=160)
+
+
+class AwakeningResult(BaseModel):
+    """The full §3 awakening record — one VLM generation, validated.
+
+    Field notes:
+    - ``object``/``material``/``condition``/``setting`` ground every line in
+      THIS photo (condition's canonical vocabulary is rusted|chipped|pristine|
+      abandoned|worn|dusty|broken|loved but stays free-text — the archetype
+      bank, not the schema, decides what a condition means).
+    - ``candidate_features`` must carry exactly one eye_left and one
+      eye_right (the first blink is the hero moment) and at most one mouth.
+    - ``critique`` is the model's mandatory self-check, written BEFORE the
+      finals in generation order; requiring it keeps the
+      critique-then-final contract honest.
+    """
+
+    gate: Gate
+    object: str = Field(min_length=1, max_length=80)
+    material: str = Field(min_length=1, max_length=80)
+    condition: str = Field(min_length=1, max_length=40)
+    setting: str = Field(min_length=1, max_length=120)
+    candidate_features: list[Feature] = Field(min_length=2, max_length=6)
+    critique: str = Field(min_length=1, max_length=400)
+    persona: Persona
+    lines: Lines
+
+    @model_validator(mode="after")
+    def _roles_complete(self) -> "AwakeningResult":
+        roles = [f.role for f in self.candidate_features]
+        for eye in ("eye_left", "eye_right"):
+            if roles.count(eye) != 1:
+                raise ValueError(
+                    f'candidate_features needs exactly one "{eye}" '
+                    f"(got {roles.count(eye)})"
+                )
+        if roles.count("mouth") > 1:
+            raise ValueError('candidate_features allows at most one "mouth"')
+        return self
+
+
+# ---------------------------------------------------------------------------
+# Defensive extraction
+# ---------------------------------------------------------------------------
+
+# Full-line code fences only (```json / ```). JSON strings cannot contain a
+# raw newline, so a whole-line match can never sit inside the payload.
+_FENCE_LINE = re.compile(r"^\s*```[a-zA-Z0-9_-]*\s*$", re.MULTILINE)
+
+
+def _strip_code_fences(text: str) -> str:
+    return _FENCE_LINE.sub("", text)
+
+
+def extract_json_object(raw: str) -> Optional[str]:
+    """Return the first balanced top-level ``{...}`` in ``raw``, or None.
+
+    Brace-scans with string/escape awareness so JSON wrapped in prose, fences,
+    or trailing chatter is still recoverable. Truncated output (depth never
+    returns to 0) yields None — which is exactly what we want: a truncated
+    generation must trigger the repair retry, not a partial parse.
+    """
+    start = raw.find("{")
+    if start < 0:
+        return None
+    depth = 0
+    in_string = False
+    escaped = False
+    for i in range(start, len(raw)):
+        ch = raw[i]
+        if in_string:
+            if escaped:
+                escaped = False
+            elif ch == "\\":
+                escaped = True
+            elif ch == '"':
+                in_string = False
+            continue
+        if ch == '"':
+            in_string = True
+        elif ch == "{":
+            depth += 1
+        elif ch == "}":
+            depth -= 1
+            if depth == 0:
+                return raw[start : i + 1]
+    return None
+
+
+def _format_validation_error(exc: ValidationError) -> str:
+    """Squash a pydantic error into one short line the model can act on."""
+    parts = []
+    for err in exc.errors()[:3]:
+        loc = ".".join(str(p) for p in err["loc"]) or "(root)"
+        parts.append(f"{loc}: {err['msg']}")
+    more = len(exc.errors()) - 3
+    if more > 0:
+        parts.append(f"(+{more} more)")
+    return "; ".join(parts)
+
+
+def _iter_line_validators():
+    validators = LINE_VALIDATORS
+    if isinstance(validators, Mapping):
+        return list(validators.values())
+    return list(validators)
+
+
+def _call_validator(validator, line: str, kind: str) -> Optional[str]:
+    """Invoke a line validator with (line, kind) when its signature allows, else (line)."""
+    try:
+        params = [
+            p
+            for p in inspect.signature(validator).parameters.values()
+            if p.kind
+            in (
+                inspect.Parameter.POSITIONAL_ONLY,
+                inspect.Parameter.POSITIONAL_OR_KEYWORD,
+                inspect.Parameter.VAR_POSITIONAL,
+            )
+        ]
+        wants_two = len(params) >= 2 or any(
+            p.kind is inspect.Parameter.VAR_POSITIONAL for p in params
+        )
+    except (TypeError, ValueError):  # builtins / odd callables
+        wants_two = False
+    return validator(line, kind) if wants_two else validator(line)
+
+
+# Minimum lateral (cx) separation between the two eyes. The VLM sometimes
+# returns eye_left/eye_right nearly (or exactly) on top of each other — a
+# degenerate pair that renders as one smeared eye and kills the first-blink
+# hero moment. Rejecting here (not in the pydantic model) keeps the message
+# on the repair-retry path while the image is still in context.
+MIN_EYE_SEPARATION_CX = 0.05
+
+EYE_SEPARATION_ERROR = (
+    "eye features must be two distinct, laterally separated elements; "
+    "pick two different visible features"
+)
+
+
+def _check_eye_separation(result: AwakeningResult) -> None:
+    """Reject eye pairs closer than MIN_EYE_SEPARATION_CX apart in cx."""
+    by_role = {f.role: f for f in result.candidate_features}
+    left, right = by_role.get("eye_left"), by_role.get("eye_right")
+    if left is None or right is None:  # pragma: no cover - model enforces this
+        return
+    if abs(left.cx - right.cx) < MIN_EYE_SEPARATION_CX:
+        raise AwakeningParseError(EYE_SEPARATION_ERROR)
+
+
+def _run_line_validators(result: AwakeningResult) -> None:
+    for kind, line in (("grudge", result.lines.grudge), ("mutter", result.lines.mutter)):
+        for validator in _iter_line_validators():
+            error = _call_validator(validator, line, kind)
+            if error:
+                raise AwakeningParseError(f"lines.{kind} rejected: {error}")
+
+
+def parse_awakening(text: str) -> AwakeningResult:
+    """Parse one raw VLM reply into a validated :class:`AwakeningResult`.
+
+    Pipeline: strip fence lines -> brace-balance extract the first {...} ->
+    json.loads -> pydantic validate -> eye-separation check ->
+    LINE_VALIDATORS (prompts.py). Raises
+    :class:`AwakeningParseError` whose message is ready for
+    :func:`build_repair_prompt`; never raises raw pydantic/json errors.
+    """
+    if not text or not text.strip():
+        raise AwakeningParseError("empty reply — output the JSON object")
+    candidate = extract_json_object(_strip_code_fences(text))
+    if candidate is None:
+        raise AwakeningParseError(
+            "no complete JSON object found (reply may be truncated or prose-only)"
+        )
+    try:
+        payload = json.loads(candidate)
+    except (json.JSONDecodeError, ValueError) as exc:
+        msg = exc.msg if isinstance(exc, json.JSONDecodeError) else str(exc)
+        raise AwakeningParseError(f"invalid JSON: {msg}") from exc
+    if not isinstance(payload, dict):
+        raise AwakeningParseError("top level must be a JSON object")
+    try:
+        result = AwakeningResult.model_validate(payload)
+    except ValidationError as exc:
+        raise AwakeningParseError(_format_validation_error(exc)) from exc
+    _check_eye_separation(result)
+    _run_line_validators(result)
+    return result
+
+
+# ---------------------------------------------------------------------------
+# Repair prompt — the single retry
+# ---------------------------------------------------------------------------
+
+_REPAIR_ECHO_MAX = 1500  # bound the prefill; the tail is where truncation bites
+
+
+def build_repair_prompt(error: str, original_text: str) -> str:
+    """Build the one-shot repair prompt fed back with the same image.
+
+    Mirrors godseed's validate-retry approach: name the precise problem, echo
+    the (clipped) previous output, demand bare JSON. One retry only — a model
+    that fails twice gets a PoeticError upstream, not a third chance.
+    """
+    clipped = (original_text or "").strip()
+    if len(clipped) > _REPAIR_ECHO_MAX:
+        clipped = clipped[:_REPAIR_ECHO_MAX] + " …"
+    return (
+        "Your previous reply could not be accepted.\n"
+        f"Problem: {error}\n"
+        "Your previous reply was:\n"
+        "---\n"
+        f"{clipped}\n"
+        "---\n"
+        "Look at the image again and reply with ONLY the corrected JSON object "
+        "— same schema, no code fences, no prose before or after the braces. "
+        "Fix the problem named above; keep everything that was already good."
+    )

mind/voice.py

@@ -0,0 +1,225 @@
+"""Voice synthesis for awakened objects: MockVoice (canned wav) and VoxVoice.
+
+VoxCPM2 design notes (ARCHITECTURE.md §7, verified June 12):
+- Voice design needs NO reference audio — prefix the line with a parenthesized
+  character description: ``"(A gravelly old veteran…) Forty years…"``.
+- ``VoxCPM.from_pretrained("openbmb/VoxCPM2", load_denoiser=False,
+  optimize=False)``; ``generate(text=…, cfg_value=2.0,
+  inference_timesteps=10)``; output is a 48 kHz waveform.
+- ``TORCHDYNAMO_DISABLE=1`` must be set before ANY torch import
+  (torch.compile warmup breaks ZeroGPU) — done unconditionally at the top of
+  this module, which is always imported before the guarded ML paths run.
+
+All ML imports live inside VoxVoice's lazy load path; importing this module —
+and using MockVoice — touches nothing heavier than pathlib.
+"""
+
+from __future__ import annotations
+
+import io
+import os
+import threading
+from pathlib import Path
+from typing import Optional
+
+# Must precede every torch import anywhere in the process (§7). Harmless when
+# torch never loads (mock mode, tests).
+os.environ.setdefault("TORCHDYNAMO_DISABLE", "1")
+
+# ---------------------------------------------------------------------------
+# Voice designs (writing agent's mind/prompts.py owns the canonical copy).
+#
+# Expected contract: VOICE_DESIGNS maps the ten WRITING.md voice ids to
+# parenthesizable character descriptions. Import-guarded with a complete
+# fallback so voices work standalone before prompts.py lands — voices must be
+# instantly distinct on a phone speaker.
+# ---------------------------------------------------------------------------
+_FALLBACK_VOICE_DESIGNS: dict[str, str] = {
+    "gravel_low": (
+        "A gravelly, low old man's voice, slow and deliberate, "
+        "long-suffering but dignified"
+    ),
+    "weary_warm": (
+        "A weary, warm middle-aged voice, soft sighs between words, "
+        "endlessly patient and quietly hurt"
+    ),
+    "prim_clipped": (
+        "A prim, clipped voice with immaculate fast diction, "
+        "tight with wounded professional pride"
+    ),
+    "breathy_faded": (
+        "A faint, breathy voice, soft and far away, "
+        "gentle and hopeful like someone half-remembered"
+    ),
+    "paranoid_whisper": (
+        "A tense, urgent whisper, quick and darting, "
+        "certain that someone is listening right now"
+    ),
+    "grandiose_warm": (
+        "A grand, theatrical, warm voice, rich and rolling, "
+        "magnanimous yet deeply wounded"
+    ),
+    "eager_bright": (
+        "A bright, eager young voice, quick and earnest, "
+        "desperate to make a good first impression"
+    ),
+    "slow_grand": (
+        "A slow, grand, antique voice, deep and deliberate, "
+        "every word delivered like inherited wisdom"
+    ),
+    "deadpan_flat": (
+        "A completely flat, deadpan voice, perfectly even pace, "
+        "quietly seething beneath the calm"
+    ),
+    "soft_wistful": (
+        "A soft, wistful, romantic voice, gentle and slow, "
+        "yearning for something just out of reach"
+    ),
+}
+
+try:  # pragma: no cover - exercised only once prompts.py exists
+    from .prompts import VOICE_DESIGNS  # type: ignore[attr-defined]
+except Exception:  # noqa: BLE001 - any import problem means "use the fallback"
+    VOICE_DESIGNS = dict(_FALLBACK_VOICE_DESIGNS)
+
+DEFAULT_VOICE_ID = "gravel_low"
+
+_MOCK_WAV_PATH = Path(__file__).with_name("mock_assets") / "grudge.wav"
+
+
+class MockVoice:
+    """Canned voice: every line comes out as the bundled hydrant grudge wav.
+
+    16-bit mono 24 kHz WAV (~4.7 s) generated once on macOS with the
+    character-ish "Grandpa" voice — realistic length and timbre so the
+    frontend's amplitude-driven mouth sync develops against real audio.
+    Deterministic and dependency-free by design.
+    """
+
+    name = "mock"
+    model_id = "pareidolia-mock-grudge-wav"
+    sample_rate = 24_000
+
+    _cached: Optional[bytes] = None
+
+    def preload(self) -> None:
+        """No-op: the mock has nothing to load. Exists so callers can blindly
+        ``preload()`` whatever make_voice() returned (the zerogpu VoxVoice
+        must preload at startup; see VoxVoice.preload)."""
+
+    def speak(self, line: str, voice_id: str) -> bytes:
+        """Return WAV bytes for ``line``. Mock ignores both arguments."""
+        if MockVoice._cached is None:
+            MockVoice._cached = _MOCK_WAV_PATH.read_bytes()
+        return MockVoice._cached
+
+
+# ---------------------------------------------------------------------------
+# VoxCPM2 — lazy module-level singleton, loaded on first zerogpu use
+# ---------------------------------------------------------------------------
+
+_VOX_MODEL = None
+_VOX_LOCK = threading.Lock()
+
+
+def _ensure_vox():
+    """Load VoxCPM2 once per process (module-level singleton).
+
+    On ZeroGPU this MUST be reached via :meth:`VoxVoice.preload` at app
+    startup (server/wiring.py calls it when the pipeline is constructed):
+    @spaces.GPU functions execute in forked workers whose state does not
+    persist, so a lazy in-window load would re-pay the 2.3B load (and, on the
+    first visit, the Hub download) inside the visitor's 75s quota window.
+    Never reached in mock mode or tests.
+    """
+    global _VOX_MODEL
+    with _VOX_LOCK:
+        if _VOX_MODEL is None:
+            from voxcpm import VoxCPM  # heavy import, guarded by design
+
+            _VOX_MODEL = VoxCPM.from_pretrained(
+                "openbmb/VoxCPM2",
+                load_denoiser=False,
+                optimize=False,  # torch.compile warmup breaks ZeroGPU
+            )
+        return _VOX_MODEL
+
+
+class VoxVoice:
+    """VoxCPM2 voice-design synthesis (the zerogpu backend's voice).
+
+    Each WRITING.md voice id maps to a fixed character-description prefix so
+    a given persona sounds the same on every visit — determinism is what
+    makes the Menagerie wall replayable. Unknown voice ids degrade to
+    DEFAULT_VOICE_ID rather than failing: a wrong-but-present voice beats a
+    silent object.
+
+    ``generate_fn`` is a test/bench seam: a callable ``(text) -> waveform``
+    that replaces the real model so the wav-encoding path is testable with
+    zero ML imports.
+    """
+
+    name = "vox"
+    model_id = "openbmb/VoxCPM2"
+    sample_rate = 48_000
+
+    def __init__(self, generate_fn=None):
+        self._generate_fn = generate_fn
+
+    def preload(self) -> None:
+        """Optionally pull the model into memory at app startup.
+
+        On ZeroGPU the startup phase is where device placement is managed;
+        calling this from app.py keeps the first visitor's GPU window free of
+        the ~2.3B-parameter load.
+        """
+        if self._generate_fn is None:
+            _ensure_vox()
+
+    def speak(self, line: str, voice_id: str) -> bytes:
+        """Synthesize ``line`` in the designed voice; return 48 kHz WAV bytes.
+
+        cfg_value=2.0 / inference_timesteps=10 are the §7-verified speed
+        settings (RTF ~0.5–1.0 on the ZeroGPU slice — a ≤8 s line lands in
+        roughly 4–10 s warm).
+        """
+        design = VOICE_DESIGNS.get(voice_id) or VOICE_DESIGNS.get(
+            DEFAULT_VOICE_ID, next(iter(_FALLBACK_VOICE_DESIGNS.values()))
+        )
+        text = f"({design}) {line}"
+        if self._generate_fn is not None:
+            waveform = self._generate_fn(text)
+        else:
+            waveform = _ensure_vox().generate(
+                text=text,
+                cfg_value=2.0,
+                inference_timesteps=10,
+            )
+        return _waveform_to_wav_bytes(waveform, self.sample_rate)
+
+
+def _waveform_to_wav_bytes(waveform, sample_rate: int) -> bytes:
+    """Encode a float waveform to 16-bit PCM WAV bytes via soundfile."""
+    import numpy as np
+    import soundfile as sf
+
+    data = np.asarray(waveform)
+    if data.ndim > 1:  # (1, n) or (n, 1) -> mono
+        data = data.squeeze()
+    buffer = io.BytesIO()
+    sf.write(buffer, data, sample_rate, format="WAV", subtype="PCM_16")
+    return buffer.getvalue()
+
+
+def make_voice(backend_name: Optional[str] = None):
+    """Build the voice for ``backend_name`` or the PAREIDOLIA_BACKEND env.
+
+    mock (default) -> MockVoice; zerogpu/vox -> VoxVoice. Mirrors
+    backends.make_medium so app.py resolves both halves from one env var.
+    """
+    raw = (backend_name or os.environ.get("PAREIDOLIA_BACKEND") or "mock").strip().lower()
+    if raw in ("mock", ""):
+        return MockVoice()
+    if raw in ("zerogpu", "zero-gpu", "vox", "voxcpm"):
+        return VoxVoice()
+    raise ValueError(f"unknown PAREIDOLIA_BACKEND {raw!r} (expected mock | zerogpu)")

requirements-dev.txt

@@ -0,0 +1,15 @@
+# PAREIDOLIA — local dev + tests. The mock backend imports ZERO ML libraries;
+# everything here runs on a laptop CPU. gradio is unpinned on purpose (we only
+# need the gr.Server idiom, which any 6.x provides; the Space pins via README).
+fastapi
+uvicorn
+gradio
+gradio_client
+pydantic
+huggingface_hub
+pillow
+numpy
+opencv-python-headless
+pytest
+httpx
+soundfile

requirements.txt

@@ -0,0 +1,21 @@
+# PAREIDOLIA — Space requirements. ARCHITECTURE.md §7 is the contract; every
+# pin below was verified against live Spaces on the June 12 recon.
+#
+# Hard rules (do NOT relitigate here):
+#   * NEVER pin gradio / spaces / torch — the Spaces image manages them
+#     (gradio == README sdk_version 6.16.0, spaces 0.50.4, torch 2.8.0 / py3.10).
+#   * `import spaces` must precede torch anywhere in the process (app.py does it).
+transformers==4.55.0          # the official MiniCPM-V-4_5 ZeroGPU demo's proven pin
+voxcpm>=2.0.3                 # VoxCPM2 dispatch lives in 2.0.x; 1.5.0 silently degrades
+torchcodec==0.7.*             # match preinstalled torch 2.8.0 (unpinned drags torch to 2.11)
+torchaudio==2.8.*             # match preinstalled torch 2.8.0
+accelerate
+timm
+einops
+safetensors
+pillow
+soundfile
+opencv-python-headless
+fastapi
+pydantic>=2.7
+huggingface_hub

seeds/eval/LICENSES.md

@@ -0,0 +1,21 @@
+# seeds/eval — image sources & licenses
+
+All images are CC0 or Public Domain (PDM), sourced via the Openverse API
+(https://api.openverse.org) and Wikimedia Commons. Downscaled to <=1024px JPEG.
+
+| file | title | creator | provider | license | source |
+|---|---|---|---|---|---|
+| fire_hydrant.jpg | A red fire hydrant is positioned on a paved sidewalk, surrou | Yam B Chhetri | wordpress | CC0 1.0 | https://wordpress.org/photos/photo/39068197e3/ |
+| coffee_mug.jpg | Giftgarden Coffee Mugs Best Love Gift Music Violin Notes Hol | favorli | flickr | PDM 1.0 | https://www.flickr.com/photos/147778363@N07/32903357261 |
+| toaster.jpg | Oster 2-Slice Toaster | Shenderson1 | wikimedia | CC0 1.0 | https://commons.wikimedia.org/w/index.php?curid=140748640 |
+| potted_plant.jpg | Pot plant | spongebabyalwaysfull | flickr | CC0 1.0 | https://www.flickr.com/photos/73080909@N03/14564004742 |
+| armchair.jpg | <div class='fn'> Armchair (fauteuil) from Louis XVI's Salon  | Georges Jacob | wikimedia | CC0 1.0 | https://commons.wikimedia.org/w/index.php?curid=61155820 |
+| mailbox.jpg | Canada Post mailbox | Open Grid Scheduler / Grid Engine | flickr | CC0 1.0 | https://www.flickr.com/photos/29155878@N03/22290946606 |
+| traffic_cone.jpg | Orange traffic cone | DennisM2 | flickr | CC0 1.0 | https://www.flickr.com/photos/14674348@N04/29948388392 |
+| desk_lamp.jpg | Metal desk lamp and books pile | freestocks.org | flickr | CC0 1.0 | https://www.flickr.com/photos/135396164@N05/42381074432 |
+| garden_gnome.jpg | Garden gnome (macro) | jo.elphick | flickr | CC0 1.0 | https://www.flickr.com/photos/135606905@N08/42993385891 |
+| stapler.jpg | Black Stapler 2024 | DifrancoBarnes | wikimedia | CC0 1.0 | https://commons.wikimedia.org/w/index.php?curid=146779701 |
+| exercise_bike.jpg | Stationary bicycle | see source | wikimedia | Public domain | https://commons.wikimedia.org/wiki/File:Stationary_bicycle.jpg |
+| stand_mixer.jpg | Sunbeam Heritage Mixmaster Stand Mixer | Shenderson1 | wikimedia | CC0 1.0 | https://commons.wikimedia.org/w/index.php?curid=140748645 |
+| park_bench.jpg | Park bench | DennisM2 | flickr | CC0 1.0 | https://www.flickr.com/photos/14674348@N04/13936410175 |
+| payphone.jpg | Metrobot payphone closeup | Jleedev | wikimedia | CC0 1.0 | https://commons.wikimedia.org/w/index.php?curid=151533770 |

seeds/eval/_manifest.json

@@ -0,0 +1,240 @@
+{
+  "fire_hydrant": {
+    "slug": "fire_hydrant",
+    "title": "A red fire hydrant is positioned on a paved sidewalk, surrounded by gray stone tiles",
+    "source_url": "https://wordpress.org/photos/photo/39068197e3/",
+    "image_url": "https://pd.w.org/2025/05/39068197e32e4b7a8.17804464-1536x2048.jpeg",
+    "license": "CC0 1.0",
+    "license_url": "https://creativecommons.org/publicdomain/zero/1.0/",
+    "creator": "Yam B Chhetri",
+    "provider": "wordpress",
+    "downloaded_bytes": 1186034,
+    "identifier": null,
+    "file": "fire_hydrant.jpg",
+    "saved_size": [
+      768,
+      1024
+    ]
+  },
+  "coffee_mug": {
+    "slug": "coffee_mug",
+    "file": "coffee_mug.jpg",
+    "title": "Giftgarden Coffee Mugs Best Love Gift Music Violin Notes Holds Tea Coffee Milk Ceramic Mug",
+    "source_url": "https://www.flickr.com/photos/147778363@N07/32903357261",
+    "image_url": "https://live.staticflickr.com/707/32903357261_7c3d83b8dd_b.jpg",
+    "license": "PDM 1.0",
+    "license_url": "https://creativecommons.org/publicdomain/mark/1.0/",
+    "creator": "favorli",
+    "provider": "flickr",
+    "downloaded_bytes": 111584,
+    "saved_size": [
+      1001,
+      1001
+    ],
+    "identifier": null
+  },
+  "toaster": {
+    "slug": "toaster",
+    "title": "Oster 2-Slice Toaster",
+    "source_url": "https://commons.wikimedia.org/w/index.php?curid=140748640",
+    "image_url": "https://upload.wikimedia.org/wikipedia/commons/b/bb/Oster_2-Slice_Toaster.jpg",
+    "license": "CC0 1.0",
+    "license_url": "https://creativecommons.org/publicdomain/zero/1.0/deed.en/",
+    "creator": "Shenderson1",
+    "provider": "wikimedia",
+    "downloaded_bytes": 1659904,
+    "identifier": "7a4a5401-73f2-41f6-9607-a2ea8251a3fb",
+    "file": "toaster.jpg",
+    "saved_size": [
+      1024,
+      683
+    ]
+  },
+  "potted_plant": {
+    "slug": "potted_plant",
+    "title": "Pot plant",
+    "source_url": "https://www.flickr.com/photos/73080909@N03/14564004742",
+    "image_url": "https://live.staticflickr.com/5526/14564004742_cc2b47143b_b.jpg",
+    "license": "CC0 1.0",
+    "license_url": "https://creativecommons.org/publicdomain/zero/1.0/",
+    "creator": "spongebabyalwaysfull",
+    "provider": "flickr",
+    "downloaded_bytes": 218335,
+    "identifier": "5b4a9e79-e468-4c54-b34c-a92c82620ba3",
+    "file": "potted_plant.jpg",
+    "saved_size": [
+      1024,
+      683
+    ]
+  },
+  "armchair": {
+    "slug": "armchair",
+    "title": "<div class='fn'> Armchair (fauteuil) from Louis XVI's Salon des Jeux at Saint Cloud</div>",
+    "source_url": "https://commons.wikimedia.org/w/index.php?curid=61155820",
+    "image_url": "https://upload.wikimedia.org/wikipedia/commons/2/24/Armchair_%28fauteuil%29_from_Louis_XVI%27s_Salon_des_Jeux_at_Saint_Cloud_MET_DP113960.jpg",
+    "license": "CC0 1.0",
+    "license_url": "https://creativecommons.org/publicdomain/zero/1.0/deed.en/",
+    "creator": "Georges Jacob",
+    "provider": "wikimedia",
+    "downloaded_bytes": 2651884,
+    "identifier": "bedee2e8-afea-45cb-8563-01031761c7ac",
+    "file": "armchair.jpg",
+    "saved_size": [
+      993,
+      1024
+    ]
+  },
+  "mailbox": {
+    "slug": "mailbox",
+    "title": "Canada Post mailbox",
+    "source_url": "https://www.flickr.com/photos/29155878@N03/22290946606",
+    "image_url": "https://live.staticflickr.com/5634/22290946606_26dde26cb3_b.jpg",
+    "license": "CC0 1.0",
+    "license_url": "https://creativecommons.org/publicdomain/zero/1.0/",
+    "creator": "Open Grid Scheduler / Grid Engine",
+    "provider": "flickr",
+    "downloaded_bytes": 285218,
+    "identifier": "854f5127-fb48-47e3-8ed0-a36cd6e325c8",
+    "file": "mailbox.jpg",
+    "saved_size": [
+      678,
+      1024
+    ]
+  },
+  "traffic_cone": {
+    "slug": "traffic_cone",
+    "title": "Orange traffic cone",
+    "source_url": "https://www.flickr.com/photos/14674348@N04/29948388392",
+    "image_url": "https://live.staticflickr.com/5158/29948388392_71690195ee_b.jpg",
+    "license": "CC0 1.0",
+    "license_url": "https://creativecommons.org/publicdomain/zero/1.0/",
+    "creator": "DennisM2",
+    "provider": "flickr",
+    "downloaded_bytes": 228913,
+    "identifier": "7c7bdbcd-0d45-480d-a90d-e796645314c6",
+    "file": "traffic_cone.jpg",
+    "saved_size": [
+      683,
+      1024
+    ]
+  },
+  "desk_lamp": {
+    "slug": "desk_lamp",
+    "file": "desk_lamp.jpg",
+    "title": "Metal desk lamp and books pile",
+    "source_url": "https://www.flickr.com/photos/135396164@N05/42381074432",
+    "image_url": "https://live.staticflickr.com/1747/42381074432_33733f4667_b.jpg",
+    "license": "CC0 1.0",
+    "license_url": "https://creativecommons.org/publicdomain/zero/1.0/",
+    "creator": "freestocks.org",
+    "provider": "flickr",
+    "downloaded_bytes": 51838,
+    "saved_size": [
+      683,
+      1024
+    ],
+    "identifier": null
+  },
+  "garden_gnome": {
+    "slug": "garden_gnome",
+    "title": "Garden gnome (macro)",
+    "source_url": "https://www.flickr.com/photos/135606905@N08/42993385891",
+    "image_url": "https://live.staticflickr.com/1771/42993385891_d2d296e98d_b.jpg",
+    "license": "CC0 1.0",
+    "license_url": "https://creativecommons.org/publicdomain/zero/1.0/",
+    "creator": "jo.elphick",
+    "provider": "flickr",
+    "downloaded_bytes": 190692,
+    "identifier": "8de57d5f-c25f-4627-81da-289c6b1dce96",
+    "file": "garden_gnome.jpg",
+    "saved_size": [
+      1024,
+      809
+    ]
+  },
+  "stapler": {
+    "slug": "stapler",
+    "title": "Black Stapler 2024",
+    "source_url": "https://commons.wikimedia.org/w/index.php?curid=146779701",
+    "image_url": "https://upload.wikimedia.org/wikipedia/commons/c/c0/Black_Stapler_2024.jpg",
+    "license": "CC0 1.0",
+    "license_url": "https://creativecommons.org/publicdomain/zero/1.0/deed.en/",
+    "creator": "DifrancoBarnes",
+    "provider": "wikimedia",
+    "downloaded_bytes": 1666889,
+    "identifier": "05407a88-b357-43c0-a74b-25c048f10bcc",
+    "file": "stapler.jpg",
+    "saved_size": [
+      1024,
+      885
+    ]
+  },
+  "exercise_bike": {
+    "slug": "exercise_bike",
+    "title": "Stationary bicycle",
+    "source_url": "https://commons.wikimedia.org/wiki/File:Stationary_bicycle.jpg",
+    "image_url": "https://upload.wikimedia.org/wikipedia/commons/c/ce/Stationary_bicycle.jpg",
+    "license": "Public domain",
+    "license_url": "",
+    "creator": "see source",
+    "provider": "wikimedia",
+    "downloaded_bytes": 3943479,
+    "identifier": "https://upload.wikimedia.org/wikipedia/commons/c/ce/Stationary_bicycle.jpg",
+    "file": "exercise_bike.jpg",
+    "saved_size": [
+      615,
+      1024
+    ]
+  },
+  "stand_mixer": {
+    "slug": "stand_mixer",
+    "file": "stand_mixer.jpg",
+    "title": "Sunbeam Heritage Mixmaster Stand Mixer",
+    "source_url": "https://commons.wikimedia.org/w/index.php?curid=140748645",
+    "image_url": "https://upload.wikimedia.org/wikipedia/commons/7/7b/Sunbeam_Heritage_Mixmaster_Stand_Mixer.jpg",
+    "license": "CC0 1.0",
+    "license_url": "https://creativecommons.org/publicdomain/zero/1.0/deed.en/",
+    "creator": "Shenderson1",
+    "provider": "wikimedia",
+    "downloaded_bytes": 379877,
+    "saved_size": [
+      990,
+      1024
+    ],
+    "identifier": null
+  },
+  "park_bench": {
+    "slug": "park_bench",
+    "file": "park_bench.jpg",
+    "title": "Park bench",
+    "source_url": "https://www.flickr.com/photos/14674348@N04/13936410175",
+    "image_url": "https://live.staticflickr.com/3797/13936410175_01c83d4a8c_b.jpg",
+    "license": "CC0 1.0",
+    "license_url": "https://creativecommons.org/publicdomain/zero/1.0/",
+    "creator": "DennisM2",
+    "provider": "flickr",
+    "downloaded_bytes": 363806,
+    "saved_size": [
+      1024,
+      768
+    ],
+    "identifier": null
+  },
+  "payphone": {
+    "slug": "payphone",
+    "title": "Metrobot payphone closeup",
+    "source_url": "https://commons.wikimedia.org/w/index.php?curid=151533770",
+    "image_url": "https://upload.wikimedia.org/wikipedia/commons/5/5c/Metrobot_payphone_closeup.jpg",
+    "license": "CC0 1.0",
+    "license_url": "https://creativecommons.org/publicdomain/zero/1.0/deed.en/",
+    "creator": "Jleedev",
+    "provider": "wikimedia",
+    "downloaded_bytes": 2466827,
+    "identifier": "74dd0544-e704-4f2c-b486-227e2084b9eb",
+    "file": "payphone.jpg",
+    "saved_size": [
+      768,
+      1024
+    ]
+  }
+}

seeds/records/records.jsonl

@@ -0,0 +1,12 @@
+{"id": "seed_potted_plant", "ts": 1781292294.2181592, "object": "bonsai tree", "material": "wood, soil, ceramic pot", "condition": "pristine", "setting": "indoor, against a plain wall", "persona": {"archetype": "the_perfectionist", "voice": "prim_clipped", "mood": "unfulfilled"}, "features": [{"name": "left leaf cluster base", "role": "eye_left", "cx": 0.2727272727272727, "cy": 0.48240469208211145, "size": 0.04, "snap_delta": 0.018944774198844515, "snapped": true, "anchor_kind": "corner", "anchor_score": 0.2312}, {"name": "right leaf cluster base", "role": "eye_right", "cx": 0.7106549364613881, "cy": 0.4736070381231672, "size": 0.04, "snap_delta": 0.015212218431305963, "snapped": true, "anchor_kind": "corner", "anchor_score": 0.2052}, {"name": "center trunk knot", "role": "mouth", "cx": 0.570869990224829, "cy": 0.5616293988269795, "size": 0.06, "snap_delta": 0.059252363570097874, "snapped": true, "anchor_kind": "edge", "anchor_score": 0.1423}], "lines": {"grudge": "Planted in this shallow pot. No room for roots to spread.", "mutter": "They call it art."}, "critique": "Leaf cluster bases round, level, symmetric — honest eyes. Trunk knot low center — compact mouth. Grudge stays on the knot and the pot's edge.", "image_sha256": "1d5ea6b7a40ca50ccad6582e90a26d76b209566b28e0720eaf208fc08a1227da", "backend": "zerogpu", "image_url": "/media/seed_potted_plant.jpg", "audio_url": "/media/seed_potted_plant.wav"}
+{"id": "seed_garden_gnome", "ts": 1781292304.081881, "object": "garden gnome", "material": "plastic", "condition": "pristine", "setting": "wooden planter, garden", "persona": {"archetype": "the_diva", "voice": "grandiose_warm", "mood": "expectant"}, "features": [{"name": "left eye", "role": "eye_left", "cx": 0.5540566989753253, "cy": 0.3279703064720229, "size": 0.04, "snap_delta": 0.03213735259043178, "snapped": true, "anchor_kind": "circle", "anchor_score": 0.2121}, {"name": "right eye", "role": "eye_right", "cx": 0.6040566989753252, "cy": 0.3279703064720229, "size": 0.04, "snap_delta": 0.03213735259043178, "snapped": true, "anchor_kind": "pair", "anchor_score": 0.2121}, {"name": "mouth", "role": "mouth", "cx": 0.5716983324298539, "cy": 0.4500272861931862, "size": 0.05, "snap_delta": 0.04237106197632453, "snapped": true, "anchor_kind": "blob", "anchor_score": 0.2096}], "lines": {"grudge": "They placed me here to watch the plants, not to be ignored by passersby.", "mutter": "A little attention, please."}, "critique": "Eyes are two matching dark spots, level and apart. Mouth is a red curve below, forming a compact face. All features span cx 0.5-0.6, cy 0.35-0.5.", "image_sha256": "a091a50b9d46039faae5cadd0b73d0cceba8a867e0b9b111c0aff6a41899fd89", "backend": "zerogpu", "image_url": "/media/seed_garden_gnome.jpg", "audio_url": "/media/seed_garden_gnome.wav"}
+{"id": "seed_armchair", "ts": 1781292309.8492439, "object": "armchair", "material": "wood and fabric", "condition": "pristine", "setting": "studio, isolated", "persona": {"archetype": "the_diva", "voice": "grandiose_warm", "mood": "unappreciated"}, "features": [{"name": "left armrest scroll detail", "role": "eye_left", "cx": 0.16442938292689271, "cy": 0.41215222856474343, "size": 0.04, "snap_delta": 0.06540875317034409, "snapped": true, "anchor_kind": "blob", "anchor_score": 0.1625}, {"name": "right armrest scroll detail", "role": "eye_right", "cx": 0.7477822611408849, "cy": 0.3992179878063332, "size": 0.04, "snap_delta": 0.036452929050856585, "snapped": true, "anchor_kind": "circle", "anchor_score": 0.3703}, {"name": "center floral motif on seat cushion", "role": "mouth", "cx": 0.4492314923885466, "cy": 0.5612293650532143, "size": 0.06, "snap_delta": 0.03621411171591366, "snapped": true, "anchor_kind": "edge", "anchor_score": 0.2269}], "lines": {"grudge": "They brought me here to admire my gilding, but no one noticed my floral heart.", "mutter": "More light. Please."}, "critique": "Scroll details on armrests level, symmetric — strong eyes. Floral motif low center — honest mouth. Grudge must come from the visible gold gilding and this exact pattern.", "image_sha256": "db995f9a263f375a45e31b8337543678aee7d44010fb920ce7297b19ad5b6da3", "backend": "zerogpu", "image_url": "/media/seed_armchair.jpg", "audio_url": "/media/seed_armchair.wav"}
+{"id": "seed_stapler", "ts": 1781292322.384654, "object": "stapler", "material": "plastic", "condition": "worn", "setting": "desk", "persona": {"archetype": "the_martyr", "voice": "weary_warm", "mood": "quietly wounded"}, "features": [{"name": "left hinge screw", "role": "eye_left", "cx": 0.38, "cy": 0.42, "size": 0.04, "snap_delta": 0.0, "snapped": false, "anchor_kind": "vlm", "anchor_score": 0.0}, {"name": "right hinge screw", "role": "eye_right", "cx": 0.52, "cy": 0.42, "size": 0.04, "snap_delta": 0.0, "snapped": false, "anchor_kind": "vlm", "anchor_score": 0.0}, {"name": "staple ejection slot", "role": "mouth", "cx": 0.45, "cy": 0.55, "size": 0.08, "snap_delta": 0.0, "snapped": false, "anchor_kind": "vlm", "anchor_score": 0.0}], "lines": {"grudge": "Thousands of staples ejected. No one ever cleans the ejection slot.", "mutter": "A wipe. Please."}, "critique": "Screws round, level, symmetric — honest eyes. Ejection slot low center — tired mouth. Grudge comes from the visible wear and this exact slot.", "image_sha256": "7006b3457943e94c738119a26f6665c18174439e18bc03ff6c36306e16f72b89", "backend": "zerogpu", "image_url": "/media/seed_stapler.jpg", "audio_url": "/media/seed_stapler.wav"}
+{"id": "seed_payphone", "ts": 1781292335.539028, "object": "payphone", "material": "plastic and metal", "condition": "worn", "setting": "outdoor wall, near a university sign", "persona": {"archetype": "the_martyr", "voice": "weary_warm", "mood": "quietly exhausted"}, "features": [{"name": "left side scuff mark", "role": "eye_left", "cx": 0.4325945280987716, "cy": 0.29032259556088863, "size": 0.04, "snap_delta": 0.05905953740455453, "snapped": true, "anchor_kind": "circle", "anchor_score": 0.2231}, {"name": "right side scuff mark", "role": "eye_right", "cx": 0.6325945280987716, "cy": 0.29032259556088863, "size": 0.04, "snap_delta": 0.05905953740455453, "snapped": true, "anchor_kind": "pair", "anchor_score": 0.2231}, {"name": "dial pad wear pattern", "role": "mouth", "cx": 0.5563554598189823, "cy": 0.5228036728737991, "size": 0.12, "snap_delta": 0.04015977786602751, "snapped": true, "anchor_kind": "edge", "anchor_score": 0.3354}], "lines": {"grudge": "Fifty cents a call. No one calls anymore. My buttons are all I have left to give.", "mutter": "Just dial. Just dial."}, "critique": "Scuff marks round, level, symmetric — honest eyes. Dial pad wear low center — tired mouth. Grudge stays on the wear and this exact keypad.", "image_sha256": "9a8a7f1756307b42a040ab7916cfe924ddb03684284fcc01486553ccde69c9be", "backend": "zerogpu", "image_url": "/media/seed_payphone.jpg", "audio_url": "/media/seed_payphone.wav"}
+{"id": "seed_mailbox", "ts": 1781292353.6592379, "object": "Canada Post mailbox", "material": "metal", "condition": "pristine", "setting": "grass, residential street", "persona": {"archetype": "the_perfectionist", "voice": "prim_clipped", "mood": "unfulfilled"}, "features": [{"name": "left 'CANADA POST' bolt", "role": "eye_left", "cx": 0.49955688656873154, "cy": 0.2209188660801564, "size": 0.04, "snap_delta": 0.06591915275708476, "snapped": true, "anchor_kind": "circle", "anchor_score": 0.2367}, {"name": "right 'CANADA POST' bolt", "role": "eye_right", "cx": 0.6595568865687316, "cy": 0.2209188660801564, "size": 0.04, "snap_delta": 0.06591915275708476, "snapped": true, "anchor_kind": "pair", "anchor_score": 0.2367}, {"name": "Canada logo on lower red panel", "role": "mouth", "cx": 0.4648801744047816, "cy": 0.6313112070076711, "size": 0.08, "snap_delta": 0.021530927812578152, "snapped": true, "anchor_kind": "blob", "anchor_score": 0.2034}], "lines": {"grudge": "No scuff, no rust, no wear. Yet no letter. I was built to serve, not to wait.", "mutter": "A stamp. Please."}, "critique": "Bolts round, level, symmetric — strong eyes. Canada logo mouth low center — honest mouth. Grudge must come from the visible pristine condition and this exact panel.", "image_sha256": "396904bfe380f2d603bae6015e37218877c8bdd4837a4b667f4331520b99d2b1", "backend": "zerogpu", "image_url": "/media/seed_mailbox.jpg", "audio_url": "/media/seed_mailbox.wav"}
+{"id": "seed_stand_mixer", "ts": 1781292358.335961, "object": "stand mixer", "material": "plastic and stainless steel", "condition": "pristine", "setting": "kitchen countertop", "persona": {"archetype": "the_perfectionist", "voice": "prim_clipped", "mood": "frustrated"}, "features": [{"name": "left hinge screw", "role": "eye_left", "cx": 0.25395996180923874, "cy": 0.4859874725265299, "size": 0.03, "snap_delta": 0.030392749292316112, "snapped": true, "anchor_kind": "pair", "anchor_score": 0.1913}, {"name": "right hinge screw", "role": "eye_right", "cx": 0.2939599618092387, "cy": 0.4859874725265299, "size": 0.03, "snap_delta": 0.030392749292316112, "snapped": true, "anchor_kind": "blob", "anchor_score": 0.1913}, {"name": "tilt release button", "role": "mouth", "cx": 0.6467961565408553, "cy": 0.5428027814709694, "size": 0.04, "snap_delta": 0.038669550840173546, "snapped": true, "anchor_kind": "blob", "anchor_score": 0.2169}], "lines": {"grudge": "Set to 'Off' since purchase. No one bothers to read the manual.", "mutter": "Tilt release. Use it."}, "critique": "Screw heads round, level, symmetric — steady eyes. Tilt release button low center — firm mouth. Grudge must come from the visible pristine condition and this exact button.", "image_sha256": "6f9c5148b08b344736c0aaaf719d2aacc09bb0e9429c6893fa18e9c7b065b5f3", "backend": "zerogpu", "image_url": "/media/seed_stand_mixer.jpg", "audio_url": "/media/seed_stand_mixer.wav"}
+{"id": "seed_park_bench", "ts": 1781292365.200184, "object": "bench", "material": "wood and concrete", "condition": "worn", "setting": "park, beside path and trash bin", "persona": {"archetype": "the_martyr", "voice": "weary_warm", "mood": "unappreciated"}, "features": [{"name": "left armrest bolt", "role": "eye_left", "cx": 0.3486436552895939, "cy": 0.48816480300041665, "size": 0.04, "snap_delta": 0.06702412682981697, "snapped": true, "anchor_kind": "blob", "anchor_score": 0.1443}, {"name": "right armrest bolt", "role": "eye_right", "cx": 0.608643655289594, "cy": 0.48816480300041665, "size": 0.04, "snap_delta": 0.06702412682981697, "snapped": true, "anchor_kind": "pair", "anchor_score": 0.1443}, {"name": "center plank scuff mark", "role": "mouth", "cx": 0.5052067747920282, "cy": 0.4925764308330894, "size": 0.07, "snap_delta": 0.02584974638724466, "snapped": true, "anchor_kind": "edge", "anchor_score": 0.2536}], "lines": {"grudge": "Fifty visitors today. Not one asked about the inscription. The bin watches too closely.", "mutter": "Ben Boon is forgotten."}, "critique": "Bolts round, level, symmetric — steady eyes. Scuff mark low center — weathered mouth. Grudge tied to the bench's wear and the trash bin's proximity.", "image_sha256": "7654561ea9dde5ff0340d19ce1bdb0aa9f535216d264ab45befb98e8b3d2315b", "backend": "zerogpu", "image_url": "/media/seed_park_bench.jpg", "audio_url": "/media/seed_park_bench.wav"}
+{"id": "seed_traffic_cone", "ts": 1781292370.159631, "object": "traffic cone", "material": "plastic", "condition": "pristine", "setting": "sidewalk, residential lawn", "persona": {"archetype": "the_perfectionist", "voice": "prim_clipped", "mood": "unfulfilled"}, "features": [{"name": "small vertical scratch, left side, near base", "role": "eye_left", "cx": 0.38, "cy": 0.55, "size": 0.03, "snap_delta": 0.0, "snapped": false, "anchor_kind": "vlm", "anchor_score": 0.0}, {"name": "small vertical scratch, right side, near base", "role": "eye_right", "cx": 0.6877987307382736, "cy": 0.5318479484968126, "size": 0.03, "snap_delta": 0.040481770119681036, "snapped": true, "anchor_kind": "blob", "anchor_score": 0.132}, {"name": "small horizontal scuff mark, center of base", "role": "mouth", "cx": 0.5, "cy": 0.65, "size": 0.04, "snap_delta": 0.0, "snapped": false, "anchor_kind": "vlm", "anchor_score": 0.0}], "lines": {"grudge": "Placed here for decoration, not function. My purpose is ignored.", "mutter": "I am not a lawn ornament."}, "critique": "Scratches round, level, symmetric — strong eyes. Scuff mark low center — honest mouth. Grudge must come from the visible scratches and this exact base.", "image_sha256": "1f8bd171ea5d3c6d3de3cf63832dbaf6f7cbc4c52dfea7394ee3f4fc8adb3d42", "backend": "zerogpu", "image_url": "/media/seed_traffic_cone.jpg", "audio_url": "/media/seed_traffic_cone.wav"}
+{"id": "seed_fire_hydrant", "ts": 1781292377.069961, "object": "fire hydrant", "material": "cast iron", "condition": "rusted", "setting": "sidewalk, urban street", "persona": {"archetype": "the_veteran", "voice": "gravel_low", "mood": "long-suffering"}, "features": [{"name": "left bonnet bolt", "role": "eye_left", "cx": 0.42, "cy": 0.31, "size": 0.06, "snap_delta": 0.0, "snapped": false, "anchor_kind": "vlm", "anchor_score": 0.0}, {"name": "right bonnet bolt", "role": "eye_right", "cx": 0.5597235192063349, "cy": 0.2991906916487835, "size": 0.06, "snap_delta": 0.01490825300427536, "snapped": true, "anchor_kind": "blob", "anchor_score": 0.127}, {"name": "front outlet cap", "role": "mouth", "cx": 0.4964074133924091, "cy": 0.5375428726214327, "size": 0.12, "snap_delta": 0.010186051553037553, "snapped": true, "anchor_kind": "blob", "anchor_score": 0.2206}], "lines": {"grudge": "Six decades here. Not a single child has climbed me for a better view.", "mutter": "They said I was safe. I was."}, "critique": "Bolts round, level, symmetric — strong eyes. Outlet cap low center — honest mouth. Grudge must come from the visible rust and this exact corner.", "image_sha256": "8263f231b5889c59705fe74b431bd494a209316b490a77df277a15a7b42de23b", "backend": "zerogpu", "image_url": "/media/seed_fire_hydrant.jpg", "audio_url": "/media/seed_fire_hydrant.wav"}
+{"id": "seed_toaster", "ts": 1781292382.316471, "object": "toaster", "material": "metal", "condition": "pristine", "setting": "display", "persona": {"archetype": "the_diva", "voice": "grandiose_warm", "mood": "entitled"}, "features": [{"name": "left hinge screw", "role": "eye_left", "cx": 0.3984359785958119, "cy": 0.3123167267293175, "size": 0.04, "snap_delta": 0.02751637644697308, "snapped": true, "anchor_kind": "circle", "anchor_score": 0.2382}, {"name": "right hinge screw", "role": "eye_right", "cx": 0.5879513281739944, "cy": 0.32450011841961596, "size": 0.04, "snap_delta": 0.015597952163595458, "snapped": true, "anchor_kind": "blob", "anchor_score": 0.1292}, {"name": "leaver pivot point", "role": "mouth", "cx": 0.4689724858715494, "cy": 0.5161310818907073, "size": 0.06, "snap_delta": 0.031892762937365426, "snapped": true, "anchor_kind": "blob", "anchor_score": 0.2758}], "lines": {"grudge": "They chose the red one to be admired. I am the original, yet overlooked.", "mutter": "At least they polished me."}, "critique": "Screws round, level, symmetric — strong eyes. Pivot point low center — honest mouth. Grudge must come from the visible shine and this exact leaver.", "image_sha256": "ea14f42bec99a6e893d308ff819775981f055d488399c1f977f118f8d16a90fc", "backend": "zerogpu", "image_url": "/media/seed_toaster.jpg", "audio_url": "/media/seed_toaster.wav"}
+{"id": "seed_coffee_mug", "ts": 1781292386.6573708, "object": "coffee mug with violin handle", "material": "ceramic", "condition": "pristine", "setting": "indoor, beside potted plants", "persona": {"archetype": "the_conspiracist", "voice": "paranoid_whisper", "mood": "suspicious"}, "features": [{"name": "violin handle top knob", "role": "eye_left", "cx": 0.7066000061035156, "cy": 0.26780000305175783, "size": 0.04, "snap_delta": 0.03313612358218656, "snapped": true, "anchor_kind": "circle", "anchor_score": 0.2353}, {"name": "violin handle tuning peg", "role": "eye_right", "cx": 0.7366000061035156, "cy": 0.2478000030517578, "size": 0.03, "snap_delta": 0.03313612358218656, "snapped": true, "anchor_kind": "pair", "anchor_score": 0.2353}, {"name": "violin handle f-hole", "role": "mouth", "cx": 0.76, "cy": 0.35, "size": 0.05, "snap_delta": 0.0, "snapped": false, "anchor_kind": "vlm", "anchor_score": 0.0}], "lines": {"grudge": "They placed me here to watch the white pot. I know their game.", "mutter": "Why a violin? Why not a guitar?"}, "critique": "Knob and peg round, distinct, level — honest eyes. F-hole low center — compact mouth. Grudge stays on the violin handle and its placement.", "image_sha256": "4c974190543c14eef912674e583281df6c3e82e2f0af3ba2004a83ffdb5cc00e", "backend": "zerogpu", "image_url": "/media/seed_coffee_mug.jpg", "audio_url": "/media/seed_coffee_mug.wav"}

seeds/records/seed_armchair.json

@@ -0,0 +1,57 @@
+{
+  "id": "seed_armchair",
+  "ts": 1781292309.8492439,
+  "object": "armchair",
+  "material": "wood and fabric",
+  "condition": "pristine",
+  "setting": "studio, isolated",
+  "persona": {
+    "archetype": "the_diva",
+    "voice": "grandiose_warm",
+    "mood": "unappreciated"
+  },
+  "features": [
+    {
+      "name": "left armrest scroll detail",
+      "role": "eye_left",
+      "cx": 0.16442938292689271,
+      "cy": 0.41215222856474343,
+      "size": 0.04,
+      "snap_delta": 0.06540875317034409,
+      "snapped": true,
+      "anchor_kind": "blob",
+      "anchor_score": 0.1625
+    },
+    {
+      "name": "right armrest scroll detail",
+      "role": "eye_right",
+      "cx": 0.7477822611408849,
+      "cy": 0.3992179878063332,
+      "size": 0.04,
+      "snap_delta": 0.036452929050856585,
+      "snapped": true,
+      "anchor_kind": "circle",
+      "anchor_score": 0.3703
+    },
+    {
+      "name": "center floral motif on seat cushion",
+      "role": "mouth",
+      "cx": 0.4492314923885466,
+      "cy": 0.5612293650532143,
+      "size": 0.06,
+      "snap_delta": 0.03621411171591366,
+      "snapped": true,
+      "anchor_kind": "edge",
+      "anchor_score": 0.2269
+    }
+  ],
+  "lines": {
+    "grudge": "They brought me here to admire my gilding, but no one noticed my floral heart.",
+    "mutter": "More light. Please."
+  },
+  "critique": "Scroll details on armrests level, symmetric — strong eyes. Floral motif low center — honest mouth. Grudge must come from the visible gold gilding and this exact pattern.",
+  "image_sha256": "db995f9a263f375a45e31b8337543678aee7d44010fb920ce7297b19ad5b6da3",
+  "backend": "zerogpu",
+  "image_url": "/media/seed_armchair.jpg",
+  "audio_url": "/media/seed_armchair.wav"
+}

seeds/records/seed_armchair.wav

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:c232dd0245f311516c0765003f681c1cdd8b12251801230f47e1ab881e033fed
+size 583724

seeds/records/seed_coffee_mug.json

@@ -0,0 +1,57 @@
+{
+  "id": "seed_coffee_mug",
+  "ts": 1781292386.6573708,
+  "object": "coffee mug with violin handle",
+  "material": "ceramic",
+  "condition": "pristine",
+  "setting": "indoor, beside potted plants",
+  "persona": {
+    "archetype": "the_conspiracist",
+    "voice": "paranoid_whisper",
+    "mood": "suspicious"
+  },
+  "features": [
+    {
+      "name": "violin handle top knob",
+      "role": "eye_left",
+      "cx": 0.7066000061035156,
+      "cy": 0.26780000305175783,
+      "size": 0.04,
+      "snap_delta": 0.03313612358218656,
+      "snapped": true,
+      "anchor_kind": "circle",
+      "anchor_score": 0.2353
+    },
+    {
+      "name": "violin handle tuning peg",
+      "role": "eye_right",
+      "cx": 0.7366000061035156,
+      "cy": 0.2478000030517578,
+      "size": 0.03,
+      "snap_delta": 0.03313612358218656,
+      "snapped": true,
+      "anchor_kind": "pair",
+      "anchor_score": 0.2353
+    },
+    {
+      "name": "violin handle f-hole",
+      "role": "mouth",
+      "cx": 0.76,
+      "cy": 0.35,
+      "size": 0.05,
+      "snap_delta": 0.0,
+      "snapped": false,
+      "anchor_kind": "vlm",
+      "anchor_score": 0.0
+    }
+  ],
+  "lines": {
+    "grudge": "They placed me here to watch the white pot. I know their game.",
+    "mutter": "Why a violin? Why not a guitar?"
+  },
+  "critique": "Knob and peg round, distinct, level — honest eyes. F-hole low center — compact mouth. Grudge stays on the violin handle and its placement.",
+  "image_sha256": "4c974190543c14eef912674e583281df6c3e82e2f0af3ba2004a83ffdb5cc00e",
+  "backend": "zerogpu",
+  "image_url": "/media/seed_coffee_mug.jpg",
+  "audio_url": "/media/seed_coffee_mug.wav"
+}

seeds/records/seed_coffee_mug.wav

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:cd9e444d24554ac7ea40fbcbeb8551bfc25598f5a4529663c11e7a2274d8a4a5
+size 353324

seeds/records/seed_fire_hydrant.json

@@ -0,0 +1,57 @@
+{
+  "id": "seed_fire_hydrant",
+  "ts": 1781292377.069961,
+  "object": "fire hydrant",
+  "material": "cast iron",
+  "condition": "rusted",
+  "setting": "sidewalk, urban street",
+  "persona": {
+    "archetype": "the_veteran",
+    "voice": "gravel_low",
+    "mood": "long-suffering"
+  },
+  "features": [
+    {
+      "name": "left bonnet bolt",
+      "role": "eye_left",
+      "cx": 0.42,
+      "cy": 0.31,
+      "size": 0.06,
+      "snap_delta": 0.0,
+      "snapped": false,
+      "anchor_kind": "vlm",
+      "anchor_score": 0.0
+    },
+    {
+      "name": "right bonnet bolt",
+      "role": "eye_right",
+      "cx": 0.5597235192063349,
+      "cy": 0.2991906916487835,
+      "size": 0.06,
+      "snap_delta": 0.01490825300427536,
+      "snapped": true,
+      "anchor_kind": "blob",
+      "anchor_score": 0.127
+    },
+    {
+      "name": "front outlet cap",
+      "role": "mouth",
+      "cx": 0.4964074133924091,
+      "cy": 0.5375428726214327,
+      "size": 0.12,
+      "snap_delta": 0.010186051553037553,
+      "snapped": true,
+      "anchor_kind": "blob",
+      "anchor_score": 0.2206
+    }
+  ],
+  "lines": {
+    "grudge": "Six decades here. Not a single child has climbed me for a better view.",
+    "mutter": "They said I was safe. I was."
+  },
+  "critique": "Bolts round, level, symmetric — strong eyes. Outlet cap low center — honest mouth. Grudge must come from the visible rust and this exact corner.",
+  "image_sha256": "8263f231b5889c59705fe74b431bd494a209316b490a77df277a15a7b42de23b",
+  "backend": "zerogpu",
+  "image_url": "/media/seed_fire_hydrant.jpg",
+  "audio_url": "/media/seed_fire_hydrant.wav"
+}

seeds/records/seed_fire_hydrant.wav

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:478f34a8e6bfa988f3a8b4b4ffe7f596445938b17a7242045cc9c65ae6ea1835
+size 721964

seeds/records/seed_garden_gnome.json

@@ -0,0 +1,57 @@
+{
+  "id": "seed_garden_gnome",
+  "ts": 1781292304.081881,
+  "object": "garden gnome",
+  "material": "plastic",
+  "condition": "pristine",
+  "setting": "wooden planter, garden",
+  "persona": {
+    "archetype": "the_diva",
+    "voice": "grandiose_warm",
+    "mood": "expectant"
+  },
+  "features": [
+    {
+      "name": "left eye",
+      "role": "eye_left",
+      "cx": 0.5540566989753253,
+      "cy": 0.3279703064720229,
+      "size": 0.04,
+      "snap_delta": 0.03213735259043178,
+      "snapped": true,
+      "anchor_kind": "circle",
+      "anchor_score": 0.2121
+    },
+    {
+      "name": "right eye",
+      "role": "eye_right",
+      "cx": 0.6040566989753252,
+      "cy": 0.3279703064720229,
+      "size": 0.04,
+      "snap_delta": 0.03213735259043178,
+      "snapped": true,
+      "anchor_kind": "pair",
+      "anchor_score": 0.2121
+    },
+    {
+      "name": "mouth",
+      "role": "mouth",
+      "cx": 0.5716983324298539,
+      "cy": 0.4500272861931862,
+      "size": 0.05,
+      "snap_delta": 0.04237106197632453,
+      "snapped": true,
+      "anchor_kind": "blob",
+      "anchor_score": 0.2096
+    }
+  ],
+  "lines": {
+    "grudge": "They placed me here to watch the plants, not to be ignored by passersby.",
+    "mutter": "A little attention, please."
+  },
+  "critique": "Eyes are two matching dark spots, level and apart. Mouth is a red curve below, forming a compact face. All features span cx 0.5-0.6, cy 0.35-0.5.",
+  "image_sha256": "a091a50b9d46039faae5cadd0b73d0cceba8a867e0b9b111c0aff6a41899fd89",
+  "backend": "zerogpu",
+  "image_url": "/media/seed_garden_gnome.jpg",
+  "audio_url": "/media/seed_garden_gnome.wav"
+}