From 40b42b1d40aa338060e7de3207245e47046dc54a Mon Sep 17 00:00:00 2001 From: "Alex (Hermes)" Date: Tue, 10 Nov 2026 22:52:51 -0400 Subject: [PATCH] docs: freeze Phase 3 contract - sections (25), second looks with rounds, match points + tank gauge, agent pass; UI-SPEC v3 + DESIGN/RANKING/DATA-MODEL/PLAN additions --- docs/DATA-MODEL.md | 61 +++++++++++++++++++++++++++++++++++++++++++ docs/DESIGN.md | 16 ++++++++++++ docs/PLAN.md | 22 ++++++++++------ docs/RANKING.md | 30 ++++++++++++++-------- docs/UI-SPEC.md | 64 +++++++++++++++++++++++++++++++++++++++++++++- 5 files changed, 174 insertions(+), 19 deletions(-) diff --git a/docs/DATA-MODEL.md b/docs/DATA-MODEL.md index c1274f2..a6207e6 100644 --- a/docs/DATA-MODEL.md +++ b/docs/DATA-MODEL.md @@ -105,3 +105,64 @@ LIMIT :deck_size; - **Badge:** `prefs['badge_seen_at']` (ISO). `new` = active rows with `first_seen` > COALESCE(badge_seen_at,'0'); `POST /api/badge/seen` stamps now. - **Media mirror:** files at `data/img/{listing_id}.webp`; `GET /img/{id}` → file (200) → `img_url` (302) → 404 (UI placeholder). Downloads via `app/imgfetch.py` (polite: ~1 req/s, skip-existing, resumable). `img_url` enrichment happens upstream in the hunt state (`motorcycle-hunt-img.py`; atomic writes; rescans keep curated imgs) and lands via import. - **Dedupe refinement (stretch, targeted):** for cross-province groups with >2 members, replace collapse-to-one with `min(ns,nb)` completeness pairing; surplus siblings stay active. Expected dup ≈ 77 (vs 80). Verify counts and report. + +## P3 additions — frozen 2026-11-10 (personalization) + +New tables (guarded, idempotent creation; fresh AND existing DBs migrate in place): + +```sql +swipe_events ( -- append-only strike log; the learning source of truth + id INTEGER PRIMARY KEY AUTOINCREMENT, + listing_id INTEGER NOT NULL REFERENCES listings(id) ON DELETE CASCADE, + action TEXT NOT NULL CHECK (action IN ('like','nope','maybe')), + round INTEGER NOT NULL DEFAULT 1, -- 1 = first verdict; 2+ = second look (engine caps influence at round 2) + section_id INTEGER, -- section it happened in (NULL for list edits / legacy) + created_at TEXT DEFAULT (datetime('now')) +); +CREATE INDEX idx_events_listing ON swipe_events (listing_id, round); +CREATE INDEX idx_events_time ON swipe_events (created_at); + +sections ( + id INTEGER PRIMARY KEY AUTOINCREMENT, + status TEXT NOT NULL DEFAULT 'open' CHECK (status IN ('open','report','closed')), + size INTEGER NOT NULL, + profile_version INTEGER, -- taste_profile.version used at compose + recipe TEXT, -- JSON summary {new, return, wildcard, caps_applied, note} + created_at TEXT DEFAULT (datetime('now')), + closed_at TEXT +); + +section_items ( + section_id INTEGER NOT NULL REFERENCES sections(id) ON DELETE CASCADE, + listing_id INTEGER NOT NULL REFERENCES listings(id) ON DELETE CASCADE, + slot TEXT NOT NULL CHECK (slot IN ('new','return','wildcard')), + position INTEGER NOT NULL, + PRIMARY KEY (section_id, listing_id) +); + +taste_profile ( + version INTEGER PRIMARY KEY AUTOINCREMENT, + created_at TEXT DEFAULT (datetime('now')), + source TEXT NOT NULL CHECK (source IN ('agent','mock','fallback')), + payload TEXT NOT NULL -- JSON: lead, leanings, changes, chips, adjustments, wildcards +); + +agent_runs ( + id INTEGER PRIMARY KEY AUTOINCREMENT, + started_at TEXT, finished_at TEXT, + ok INTEGER NOT NULL DEFAULT 0, + source TEXT, model TEXT, cost_note TEXT, error TEXT, + profile_version INTEGER +); +``` + +Semantics: + +- **Learning = `swipe_events` only** (append-only). A cleared swipe keeps its history — clearing removes the *UI verdict*, not the record. **UI truth = `swipes`** (latest verdict / cleared), unchanged from P1–P2. +- Round = prior events for that listing + 1, assigned at write time. Rounds cap at 2 for engine influence (any later events weigh as round 2; v1 returns never produce rounds >2 by design). +- **Migration seeding:** when `swipe_events` is empty and `swipes` has rows → insert one round-1 event per swipe row (created_at copied). Only-when-empty, hence idempotent. +- **Sections:** at most ONE `open` section at a time. The deck = that section's `section_items` in `position` order, filtered to items undecided at read. Exhausted = no item undecided → `status='report'`. Forge = close current + open new. First-ever read composes a cold section (rubric-weighted, w=0). +- **Returns eligibility (v1 contract):** a verdict exists (like/maybe/nope in `swipes`); listing `active`; NOT in either of the previous two sections; no round≥2 `nope` ever (rested); not already returned once (round cap). Selection prefers maybe > like > nope; nope candidates must be "surprising" (points ≥55 or net-positive family). Max 5 returns per section, ≤2 of them nopes. +- **`points` is computed, not stored** (deterministic from events + profile; a cache is allowed only if it never changes semantics). +- **prefs:** `forge_mode` ('ondemand' default | 'strict'). Existing keys unchanged. +- **Legacy deck semantics:** `/api/deck` (cursor paging; 7-day maybe re-admit) stays as a read-only fallback for debugging; sections are the production flow. diff --git a/docs/DESIGN.md b/docs/DESIGN.md index 32cab09..6ec034a 100644 --- a/docs/DESIGN.md +++ b/docs/DESIGN.md @@ -62,6 +62,22 @@ The nightly import is triggered by its own Hermes cron job — `bike-tinder-impo No-build SPA — vanilla JS + CSS, pointer-events drag, keyboard arrows on desktop (~300 lines). A small service worker caches the shell; the API is always live. Screens, gestures, and visual anatomy: see `UI-SPEC.md`. +## Personalization architecture (Phase 3) — frozen 2026-11-10 + +| piece | what | where | +|---|---|---| +| Taste engine | deterministic points + breakdown from `swipe_events` + rubric | `app/taste.py` | +| Section engine | compose/forge/read sections, returns, wildcards, modes | `app/sections.py` | +| Agent pass | the ONLY LLM step — reads strikes, writes the profile; never in a request path | `app/agentpass.py` | + +**The law:** no LLM in the swipe path, ever. The deck renders and the engine scores with zero network; the agent pass runs between sections (forge) or on schedule (P4 nightly), and can fail without breaking anything — compose falls back to the last profile. + +**Forge flow (on-demand):** section exhausted → `POST /api/section/forge` → agent pass (mock/fallback when unconfigured; live when the key exists) writes `taste_profile` → section engine composes the next 25. **Strict mode:** forge refuses (409) until a fresh pass exists post-exhaustion — the nightly cron provides it at P4. + +**API additions:** `GET /api/section` · `POST /api/section/forge` · `GET /api/trends` · `POST /api/agent/run`. Listing payloads gain `points`, `points_breakdown`, `tank`, `slot`, `round_next` (see UI-SPEC §10 and DATA-MODEL P3). + +**Cost & keys:** each pass ≈ pennies (one compact prompt; house model default via `OPENROUTER_API_KEY`). The key lives in the host/stack env only — never the repo, never logs. "Pause" stops passes with all other spend. + ## Deployment (house constraints) - **Stack dir:** `/var/mnt/DATA/podman-stacks/bike-tinder/` — `docker-compose.yml` + `Dockerfile` (`python:3.14-slim` + fastapi/uvicorn/requests), volume `./data:/data`, `restart: unless-stopped`. diff --git a/docs/PLAN.md b/docs/PLAN.md index 22e2120..7186e6b 100644 --- a/docs/PLAN.md +++ b/docs/PLAN.md @@ -34,20 +34,26 @@ A single-source, single-user, tailnet-only Tinder-style PWA on the Rotarran: nig ## Phase 2 — The swipe app (core) -**Status: built by Torres + verified by Alex (2026-11-10) on `dev`; awaiting Glenn's phone pass.** Contract frozen: `UI-SPEC.md` v2 + `reference/mockup-001-fidelity.html` (Variant A "Pure", approved by Glenn; 5-deep live stack, no-lock commit, dossier sheet). Image backfill + app-side mirror (`app/imgfetch.py`) done: 619/620 listings enriched, 559 local webp. +**Status: built by Torres + verified by Alex (2026-11-10) on `dev`; phone pass LIVE (swiping over the tailnet).** Contract frozen: `UI-SPEC.md` v2 + `reference/mockup-001-fidelity.html` (Variant A "Pure", approved by Glenn; 5-deep live stack, no-lock commit, dossier sheet). Image backfill + app-side mirror (`app/imgfetch.py`) done: 619/620 listings enriched, 559 local webp. - [x] 2–3 UI mock variants → Glenn picked **Variant A "Pure"** (approved 2026-11-10 after two fix rounds) - [x] API (deck cursor, swipe upsert/clear, list + filters, stats, media, import) + PWA frontend (faithful mockup port: stack engine, drag, Like / Nope / Maybe, dossier, empty/undo) — no match overlay (removed by Glenn's call) - [x] Full list view with inline edit; basic filters (decision + sort + search) -- [ ] Proof: runs locally on :9453 (systemd dev unit) + tailnet `http://rotarran.tailf35a34.ts.net:9453`; phone-viewport browser pass green — **Glenn's phone pass pending** -- **Exit criteria:** Glenn can swipe a real deck on his phone and edit results in the list. +- [x] Proof: runs locally on :9453 (systemd dev unit) + tailnet `http://rotarran.tailf35a34.ts.net:9453`; phone-viewport browser pass green; **phone pass live 2026-11-10** — Glenn swiping the real deck over the tailnet (24 swipes recorded + verified from the DB; list-edit tap still unexercised by Glenn — automation-covered) +- **Exit criteria:** Glenn can swipe a real deck on his phone and edit results in the list — swiping proven; edit-tap pending. -## Phase 3 — Personalization +## Phase 3 — Personalization ("Trends") -- Swipe history → nightly retrain of explainable ranking -- Trends panel ("you lean: …"); "because you liked X" chips -- Deck ordering by learned taste with cold-start guardrails -- **Exit criteria:** after ~30 swipes, deck order visibly reflects taste; explainability shown in UI. +**Status: contract frozen 2026-11-10 (docs + brief); build started (Torres).** Glenn's approved design (2026-11-10): + +- **Sections of 25:** the deck is a finite batch; the agent always runs between sections (learning segmentation + anti-doom-scroll). Modes: forge-on-demand (default) / strict (nightly read only). Fallback to the last profile if the agent fails. +- **Section lead:** on open/refresh the best suggestions lead; the 5-card live stack is unchanged. +- **Wildcards (~1-in-10):** labeled "maybe you'll like this one instead"; plausible stretches; never hard-noped families; their answers teach the model. +- **Second looks:** likes + maybes + nopes return (chosen; ≤5/section, ≤2 nopes); Round 2 weighs ×2; flips are the loudest signal; a re-nope rests the item; rounds cap at 2. Returning maybes can bring their variants. +- **Match points:** taste + agent adjustments; drive ordering, the section recipe (family caps, price mix), and returns. Explainable in the dossier; tank gauge (non-numeric) in the List. +- **Hits objective:** order = expected-like; Trends reports the hit rate (likes; likes+maybes). +- **Agent pass:** nightly/on-demand read (mock + live + fallback); **no LLM in the swipe path — ever.** +- **Exit criteria:** after ≥30 swipes the deck order visibly reflects taste; explainability visible (dossier breakdown + Trends); the section loop works end-to-end; the agent kill-switch test passes (app fully functional on the last profile with the pass disabled). ## Phase 4 — Deploy + automate diff --git a/docs/RANKING.md b/docs/RANKING.md index bfae225..95425de 100644 --- a/docs/RANKING.md +++ b/docs/RANKING.md @@ -3,7 +3,7 @@ The deck is ordered by predicted taste. Three rungs, in order: the hunt's existing rubric (v1), a cheap explainable boost from swipe clusters (v1.x), then a small learned model (Phase 3). Nothing ever becomes a black box. ## Signals -- Like = strong positive (+1). Maybe = weak positive (+0.25, kept in its own bucket). Nope = negative (−1). List-view edits count identically to in-deck swipes; the latest call wins. +- Like = strong positive (+1). Maybe = weak positive (+0.4) on the *direction* — "right lane, wrong trim" (Glenn's read): the family/silhouette reads positive, the specific build is uncertain; maybes replenish via second looks + variant hunts. Nope = negative (−1). List-view edits count identically; the latest call wins (full history lives in `swipe_events`). - Planned v2 signals: dwell time on card, "open listing" click-outs. ## Features (v1) @@ -16,22 +16,32 @@ Order by the hunt's existing rubric score (family tiers + MVI / whitewalls / win ## Stage 1.5 — Cheap swipe boost (v1.x, post-launch) Before any model exists, the importer can nudge `score` with plain swarm signals — e.g. +N when recent likes cluster in a family, small time-decay otherwise — recomputed each import, zero ML, fully explainable. Ships as v1.x if Glenn wants it; v1 itself stays pure rubric. -## Stage 2 — Learned order (Phase 3 roadmap) -- Model: logistic regression on the features above; target = like vs nope (maybes contribute softly positive). Trained on all swipe history including edits. -- Pure-Python or numpy implementation (tiny data — no heavy ML dependency). Params + training metadata live in the DB; versioned. -- Retrain nightly right after import; on-demand retrain available from the app. -- Guardrails: - - Blend: until 100 swipes, deck order = 50% rubric rank + 50% model rank; after, model order with an exploration slice (roughly every 8th card = top-rubric card not yet shown). - - Never hide: everything stays in List; ranking only reorders the deck. - - Sanity: if model like-rate underperforms the rubric baseline (tracked weekly), it reverts to rubric order silently. +## Stage 2 — P3 taste engine (frozen 2026-11-10) + +Deterministic, explainable, pure-Python. Learning reads `swipe_events` only. + +**Event weights.** action: like +1.0 · maybe +0.4 · nope −1.0; round multiplier: round 1 ×1, round ≥2 **×2** (second strikes hit twice as hard — reaffirmations and flips both); recency: ×0.5^(age_days / 21). Event weight = product. + +**Feature weights.** Feature set per listing: family · price band (`<3k, 3–5k, 5–8k, 8–12k, 12k+`) · displacement band (from title/desc) · year band · km band (when present) · each extras flag · seller type · silhouette keywords (bobber/custom/classic/cruiser) · color words · region. For each (feature, value): `raw = Σ event weights`; `shrunk = raw × n/(n+3)` — no single strike taboos a family. + +**Score.** `taste_raw` = Σ shrunk weights over the listing's values; `taste_norm` = percentile rank among active listings (0–100). Blend: `w = min(0.85, N/60)` where N = total events; `points = clip( round( (1−w)·rubric + w·taste_norm + agent_adj ), 0, 100 )`. `agent_adj` = Σ profile adjustments (clamped ±10 per listing). Breakdown for the dossier: rubric share · top 3 ± taste features · agent lines — all source-labeled. + +**Section recipe.** 25 cards = 2 wildcards + ≤5 returns + remainder new (points DESC). Constraints: ≤4 per family per section; ≥3 price bands when the pool allows; shortfalls fill from new. + +**Wildcards.** Candidates: active, unseen, not in the last two sections. Exclusions: families with ≥3 cumulative nopes and net-negative weight. Prefer: different family AND different price band than the section's top new items. Score = `0.5·points + 0.5·novelty` (novelty = distance from the liked-profile centroid). Picks: 2 per section. + +**Returns ("second looks").** Pool + caps per DATA-MODEL. Order: maybe > like > surprising nope (points ≥55 or net-positive family); rank within role by points DESC. A re-nope (round≥2 nope) rests the item permanently in v1. + +**Guardrails.** Never hide (List untouched; ranking only reorders). The ramp keeps cold start on rubric; the engine must run with zero profile (w=0). Agent offline → compose on the last profile (source-labeled). **No LLM inside any request path or computed score** — the pass only writes the profile. ## Explainability Each card can show up to 2 chips: top positive contributions for that bike ("low km for the money", "Vulcan family", "red", "MVI"). Chips derive from the live feature contributions; during cold start they come from the rubric's existing reasons. ## Evaluation - Track: swipes/session, like-rate trend, maybe-rate, undo rate, and "liked-item rank" (how deep liked items sat — should trend shallow). +- P3 adds: hit rate (likes/decided · likes+maybes), returns re-strike rate, wildcard hit rate, flip count — surfaced in the Trends tab. - Notifications (decided 2026-11-10): in-app "new since last visit" badge only — no Conduit pushes. A weekly digest remains possible later if asked for. ## Open decisions -- Maybe-handling: weak positive + separate bucket (proposed) vs pure third bucket — confirm with Glenn at Phase 2. +- Maybe-handling — **resolved 2026-11-10 (Glenn):** weak positive on the direction ("right lane, wrong trim"); maybes replenish via second looks + variant hunts. - Distance feature (map-based proximity) — likely v2. diff --git a/docs/UI-SPEC.md b/docs/UI-SPEC.md index e68be46..b95bac1 100644 --- a/docs/UI-SPEC.md +++ b/docs/UI-SPEC.md @@ -81,7 +81,7 @@ Opened from deck ⓘ (or tap) AND list row tap. iOS-sheet geometry: top gap 26px ## 6. Trends -- Stub (Phase 3): "Trends — Phase 3" / "The deck learns your taste as you swipe." +- **Real (P3):** see §10.6. ## 7. Production deltas (the ONLY changes from the mockup) @@ -110,3 +110,65 @@ Machine-checkable: - Selfcheck: all P1 checks green + new API checks green. Human (parent-run after build): Glenn swipes a real deck from his phone and edits results in the list — the Phase 2 exit criterion. + +## 10. P3 additions (v3) — Personalization UI + +**Frozen 2026-11-10 (Glenn approved).** Everything in §1–§7 remains in force; all of this is additive. The card face gains only the two system bands (§10.3); everything else lives in the list, the report screen, the dossier, and Trends. + +### 10.1 Sections — the deck becomes a finite batch + +- The deck serves ONE section at a time: 25 cards (default). A section is the unit of a swipe burst; when it is exhausted, the next one is forged (with an agent pass in between — §10.2). +- Header right side, next to the stats: section progress "7/25" (12px/650, muted; turns `--accent1` at 25/25; fits within the existing header, no layout shift). +- Section composition (engine side — RANKING.md): ≤5 SECOND LOOK cards + 2 WILDCARD cards + the remainder new. +- ALL §2 mechanics apply unchanged inside a section: 5-deep stack, `.topcard` invariant, no-lock commit, stamps, undo; the buffer refills from the pinned section order. + +### 10.2 Section report + forge + +- When no undecided item remains, the deck shows the report card (replaces the §2 empty state when a section exists; same visual language): + - Title: **"Section complete."** + - Counts row: "♥ {likes} · ★ {maybes} · ✕ {nopes}" + - Sub: "The file is digesting your strikes." + - Line 2 (only when >0): "Second looks re-struck: {n} · Wildcards that hit: {n}" +- Actions: + - **Forge mode `ondemand` (default):** primary button **"Forge next 25"**. Tap → inline status "The agent is reading your strikes…" → new section hydrates. If the pass fails: "Agent offline — forging on the last read." and the forge still lands (fallback profile). + - **Forge mode `strict`:** button disabled; caption "Waiting for the nightly read — next section after the agent runs." + - Both modes: small toggle row under the actions — "Forge: on demand ⇄ strict" (persists `prefs['forge_mode']`). +- Undo from the report screen re-opens the section with the last card (§2 undo semantics). + +### 10.3 Card bands (the ONLY card-face additions) + +- Position: top-left inset (12px); `pointer-events:none`; no layout shift; no effect on stack metrics or drag. 11px/650, letter-spacing .4px, radius 999px, padding 4px 9px, max-width 78%; may wrap to 2 lines. +- **WILDCARD — maybe you'll like this one instead** — color `#ffb43a`; bg `rgba(255,180,58,.14)`; border `1px solid rgba(255,180,58,.35)`. +- **SECOND LOOK — you {liked|maybed|noped} this** — color `rgba(255,255,255,.85)`; bg `rgba(255,255,255,.10)`; border `1px solid rgba(255,255,255,.22)`. +- No other text may sit on the card face in v3. + +### 10.4 Tank gauge (match points, non-numeric) + +- Small fuel-tank glyph; fill = match points (0–100). List rows: 18×22px in the trailing cluster, immediately left of the price, vertically centered. Dossier: 28×34px. +- Fill band colors: `<30` → `--nope`; `30–70` → `--maybe`; `>70` → `--like`. Track: `rgba(255,255,255,.12)`, radius 4px. Fill animates `.25s ease` on update. +- The List view NEVER shows raw numbers. + +### 10.5 Dossier — "Why this rank" + +- New block after chips, before "The machine": + - Gauge + "{points}/100" (17px/700). + - Up to 4 breakdown lines, strongest first, muted: "· {feature} {±n}"; agent contributions render as "· agent: {why} {±n}". + - Footer: "from {N} strikes · read {relative}" (N = events count; time = profile version time). +- This is the only numeric display in the app (accepted — it exists for audit). + +### 10.6 Trends tab (real) + +Top→bottom: + +1. **Your read** — lead line (18px/700) + "updated {rel}" muted; cold start copy: "Swipe ~10 more and the read sharpens." +2. **Leanings** — up to 8 bullets (14px). +3. **Stats** — three mini blocks: "Hit rate" ({likes}/{decided}) · "Returns re-struck" ({n}) · "Wildcards hit" ({n}). +4. **Since last read** — one muted line (hidden when null). +5. **Actions** — "Run agent now" (POST /api/agent/run; inline status) · forge-mode toggle · muted "Last read {time} · {model}". + +- No LLM call at view time; the tab renders the stored profile only. + +### 10.7 Wiring deltas + +- Deck buffer source becomes `GET /api/section` (pinned order). All P2 wiring (optimistic swipe + retry queue, badge, SW) unchanged; bump the `sw.js` cache version. +- Card payload additions the FE reads: `slot` ('new'|'return'|'wildcard'), `points`, `tank` {value, band}, `round_next` (1|2, for the SECOND LOOK band copy when needed).