Spaces:
Running
Running
| # Clanker — Roadmap | |
| **The first VADUGWI project.** A community-cared creature with persistent memory and | |
| emotion whose purpose is to make the 7-dimensional VADUGWI state **visible, audible, and | |
| explainable in real time** — and to **log real usage so the VADUGWI formulas can be | |
| audited and improved**. The pet is the vehicle; showing off VADUGWI is the point. | |
| ## Framing: this is a SHOWROOM FLOOR | |
| The whole UI is a **showroom for the VADUGWI engine** — every mechanic is on demonstrative | |
| display, not hidden behind a cute pet. The visitor should *see the machine work*: the raw | |
| read, **how the soul's VADUGWI governs how much new emotion it accepts (resilience/armor)**, | |
| the mood that results, and **how words/actions have shaped the soul over time**. The pet is | |
| the exhibit; the engine is the product. | |
| ## Governing principle (HARD RULE) | |
| **VADUGWI drives everything — full stop.** Every feature, mechanic, toy, care action, | |
| animation, sound, and bit of GFX must *read from or write to* the VADUGWI state. Nothing is | |
| cosmetic-only; nothing is faked. If a proposed addition can't be tied to a concrete VADUGWI | |
| cause or effect, it does not ship. The creature's every behavior must trace back to real | |
| engine math — and that trace must be loggable for the audit flywheel below. | |
| ## Why this matters (the flywheel) | |
| People talk to the creature → clanker-lang scores it → clanker-soul accumulates mood → | |
| the creature shows *exactly why* it feels how it feels (words detected, roles, structures, | |
| per-dimension contributions). Every interaction is logged (input + full VADUGWI + trace). | |
| That corpus lets us **audit the engine against real-world language** — find cases that read | |
| neutral but shouldn't, miscalibrated dimensions, blind spots — and feed fixes back into | |
| the formulas. The pet is a continuous, free, real-world evaluation harness with a face. | |
| ## Current status (Phase 1, shipped 2026-06-15) | |
| Live at `huggingface.co/spaces/deucebucket/clanker` (Docker Space, FastAPI + vanilla JS, | |
| no model — simlish voice via browser Web Speech, one shared global SQLite soul). | |
| **Known gap that M1 fixes:** the engine works (VADUGWI moves on every message) but the | |
| showcase is buried — color/face/word are bucketed into only 5 discrete regions so small | |
| talk looks frozen; the numbers hide in one drawer; and the **trace (what it detected) is | |
| discarded entirely** (`scorer.py` drops it). A placeholder "guest" chip clutters the | |
| corner. GFX read as rough-draft; the room is empty. | |
| ## Locked decisions | |
| - **Build order:** M1 (showcase core) first. | |
| - **Audit/data store:** a **private HF Dataset** repo — every interaction appended | |
| (input text, full VADUGWI, trace, care/context, timestamp). Durable, survives rebuilds, | |
| easy to pull for analysis. | |
| - **Identity:** **anonymous-first**; HF login optional (unlocks being remembered + care | |
| credit). Maximizes community reach. | |
| - **No language model, ever.** Voice = simlish + emoticons via browser Web Speech ($0). | |
| - **One shared global creature**, permanent state, community-shaped. | |
| --- | |
| ## M1 — Make VADUGWI visible + auditable *(the fix + the point)* | |
| The current Space's defect and the showcase, together. | |
| - **Continuous appearance** — color/posture interpolate smoothly across the VADUGWI space | |
| instead of snapping between 5 buckets, so every message visibly moves the creature. | |
| - **Live 7-dim HUD** — all of V A D U G W I on screen as labeled meters, each showing its | |
| current value AND the **per-message delta** (e.g. `W −6`). Always visible, not hidden. | |
| - **"What it detected" panel** — surface the discarded trace: the words that fired, their | |
| roles (SELF_REF, EMOTIONAL, NEGATOR, AMPLIFIER, …), structures detected, and each | |
| dimension's contributors. This is the explainability no neural pet can do. | |
| - **"Why it feels this way"** — current mood = soul baseline + recent interactions, shown | |
| as readable contributions. | |
| - **Surface the raw per-message read** (undamped) next to the slow soul mood, so the engine's | |
| reactivity is obvious even when the soul moves slowly. | |
| - **Resilience/acceptance display** — show how the soul's armor (from its W/D) absorbed part | |
| of each incoming read (`absorbed_pct`), so the read→mood gap is explained, not mysterious. | |
| - **Soul-over-time** — a timeline of how words/actions shaped the soul across the creature's | |
| life (from the event log); full historical persistence is M2. | |
| - **Born flimsy** — a newborn soul has low W/D + near-zero resilience, so it swings hard on | |
| every message (resilience is earned later, see M3). Reset the live creature to baby. | |
| - **Log unknown words / suspected vocab gaps** as first-class audit rows (Jerry's priority). | |
| - **Richer mood vocabulary** — many more mood words than the current 5. | |
| - **Remove the mystery box** (the placeholder identity chip). | |
| - **Audit logging** — append every interaction to the private HF Dataset. | |
| - **First GFX pass** — adopt the **Hugging Face mascot** look (recolorable vector, faithful | |
| silhouette, resting yellow ≈ neutral; color/face/hands driven by VADUGWI), more shine/depth, | |
| and a less-empty room (full polish + ambient mascot behaviors are M4). | |
| - **Surface the trace at the source** — `scorer.py` must keep `compute_vadug`'s trace, not | |
| drop it; expose it through `/say`. | |
| - *Success:* a visitor sends any message and immediately sees numbers move, the words it | |
| reacted to, and why — and that interaction lands in the audit dataset. | |
| ## M2 — Persistence ✅ DONE (2026-06-15) | |
| - **Soul survives Space rebuilds** via free **HF Dataset snapshot/restore** (chose this over | |
| paid persistent storage): on boot, pull the latest `soul.db` from a private dataset before | |
| opening it; after interactions, snapshot back — throttled (≤1/120s), background, fail-soft. | |
| Audit log already snapshots to its own dataset. (`app/persistence.py`.) | |
| - **Activation (one-time, Jerry):** create private dataset `deucebucket/clanker-soul-state` | |
| + ensure the Space has the `HF_TOKEN` secret. Until then it's a fail-soft no-op. | |
| - *Identity deferred* → see M2.5. | |
| ## M2.5 — Identity ✅ DONE (2026-06-15) — RECOGNITION-ONLY, privacy-first (`docs/PRIVACY.md`) | |
| - HF OAuth login (optional; **anonymous-first** — everything works logged-out). `hf_oauth: true` | |
| in README; authlib OIDC flow (`/login`,`/auth/callback`,`/logout`,`/me`); signed session. | |
| - On login, the OIDC `sub` is **sha256-hashed** into the session — raw username NEVER stored | |
| or shown. `RecognitionStore` (in the soul db, so it persists via M2) tracks first-seen/visits | |
| per hash; `/say` returns `recognition` only when signed in; the creature welcomes returnees. | |
| - `/me` returns only `{signed_in: bool}`. SESSION_SECRET set as a Space secret. | |
| - *Final check (Jerry):* click "sign in", authorize, confirm it recognizes you on return — | |
| the logged-in round-trip needs a human HF login to fully validate. | |
| - Foundation for M3's per-user relational memory (affinity VADUGWI + flashbulb). | |
| ## M3 — Tamagotchi care + relational memory + Moments ✅ DONE (2026-06-15) | |
| - **Care loop** (`app/care.py`): feed/play/pet fill needs (hunger/energy/attention) and each | |
| ingests a positive VADUGWI Score; needs decay over time; sustained **neglect** ingests a | |
| mild negative Score (floored — always recoverable). `POST /care`; needs in every state. | |
| - **Resilience growth (earned)** (`soul_bridge`): effective `dim_resilience_max` rises with | |
| lifetime event count (0.08 baby → ~0.5 mature), applied live; persists via M2. `maturity()`. | |
| - **Relational memory** (`app/relation.py`): per hashed-uid affinity EMA + flashbulb | |
| (vectors+mood word+ts, NO raw text); signed-in users get re-felt on return (recall once/ | |
| session); privacy-clean (no usernames). | |
| - **Moments diary** (`app/moments.py`): `notable()` flags breakdown/breach/elation/wound/ | |
| breakthrough; captured in `/say`; `GET /moments` (snapshots = vectors, no text). | |
| - UI: care buttons + needs bars + Moments panel + "remembers you" hint (no usernames). | |
| - All in the soul SQLite db → persisted by M2's snapshot. | |
| - *Community-shared "who cared for it" surfacing deferred to M5 (economy/governance).* | |
| ## M4 — Toys, world, physics, fluid animation, full GFX ✅ DONE (2026-06-15) | |
| - **Toys** (`app/toys.py`, `POST /toy`): 5 momentary VADUGWI stimuli — balloon (high-arousal | |
| delight), musicbox (positive valence at LOW arousal+urgency), mirror (self-Worth), teddy | |
| (comfort/grounding), **rattle (Urgency spike — the dimension chat/care never reach)**. Each | |
| ingests an absolute-target `Score` into the one shared soul; audit-logged like chat. | |
| - **In-browser physics + fluid animation** (`static/physics.js` pulse engine + `app.js` loop): | |
| a `requestAnimationFrame` loop drives spring-damped **squish** (impulse on every response, | |
| sized by |VADUGWI deltas|) and continuous **breathing** (rate+depth from arousal). Writes to | |
| a `#blob-anim` wrapper so it never fights `renderBlob`'s per-message transform. | |
| - **Mascot behaviors** — idle FSM `behaviorFor(mood)`: **sleep** (arousal+urgency both low → | |
| eyes close, Zzz, slow deep breath), calm, idle, **roam** (drifts across the floor at moderate | |
| arousal), **excited** (fast bounce at high arousal). All derived purely from the live mood. | |
| - **GFX**: 5 codex-generated transparent toy sprites adopted into the tray. | |
| - Shipped & verified live on `deucebucket/clanker` (`/toy` returns moving deltas; Playwright | |
| video confirms breathing/squish/sleep/roam; rattle shows U=210 in the read panel). | |
| - *Community-shared world decor / care economy deferred to M5.* | |
| ## M5 — Community economy & governance *(exploratory / eventual)* | |
| - Caring actions (cleaning up after it, feeding, play, attention) **earn a soft care | |
| currency**. | |
| - Spend it on toys, cosmetics, room decor (feeds M4's world). | |
| - **Voting / governance** — the community votes on decisions: its name, direction, what it | |
| gets, possibly moderation of cruelty. | |
| - **Default to a soft in-app currency (points), not real money** — real payments add legal, | |
| payment-processing, and regulatory weight; revisit a real economy only if explicitly | |
| wanted. | |
| - *Success:* caring is rewarded, and the community collectively steers the creature. | |
| --- | |
| ## Cross-cutting | |
| - **W-dimension seam** between clanker-lang and clanker-soul — verify W flows correctly | |
| before leaning on Worth for care/neglect mechanics (known organism-stack issue). | |
| - **GFX** improves incrementally each milestone; M4 is the final pass. Image assets | |
| (creature, room, toys — transparent PNGs, etc.) are generated via **codex** (GPT image | |
| generation), which writes them wherever needed. | |
| - **Audit-first mindset** — anything that affects VADUGWI (chat, care, toys) gets logged | |
| with its trace, so the whole creature is one big evaluation instrument. | |