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

This commit is contained in:
Alex (Hermes)
2026-11-10 22:52:51 -04:00
parent 49e284ff56
commit 40b42b1d40
5 changed files with 174 additions and 19 deletions

View File

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

View File

@@ -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`.

View File

@@ -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

View File

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

View File

@@ -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).