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:
@@ -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`.
|
||||
|
||||
Reference in New Issue
Block a user