project-lyra/docs/superpowers/specs/2026-06-28-poker-mode-prompts-design.md

# Poker logging service + message-type prompts

- **Date:** 2026-06-28
- **Status:** Sub-project 1 spec ready for review; sub-project 2 parked.
- **Branch:** `feat/poker-mode-prompts`

## Origin

This started as "make Lyra's poker replies less generic" (message-type-specific prompts). During design we decided to **build the logging tool first** as a standalone system of record with a clean API and a human-usable UI, then wire Lyra in as a *client* of it. Rationale:

- Brian can log and **correct** data himself, independent of whether Lyra parsed it right (she mislabeled "Dave the rock" vs "Dave the mechanic" mid-session).
- The data stops being hostage to the agent. Lyra becomes one client among potentially several.
- It's reusable: RTO (the solver) and a **fine-tuned poker model on the MI50** could consume the same hand/session data through the same contract.

## Decomposition

Two sub-projects, built and shipped in order.

### Sub-project 1 — Poker logging service *(this spec)*
Harden `lyra/poker.py` into a well-bounded store, expose a **complete REST API** over it, define a **stable, documented tool/API contract**, and build the human UI to log/edit/correct everything. Fully usable by Brian alone, zero LLM dependency.

### Sub-project 2 — Lyra wiring *(parked; summarized at the end)*
Message-type classifier + type-specific prompt fragments; Lyra's tools call the sub-project 1 service. Separately, enabling tool-calling on the MI50 backend so a fine-tuned poker model can drive the same contract.

**Why the contract is first-class:** in every design (in-process, REST, MCP) the *model* never calls the API directly — it emits a tool-call and the host app executes it. So what lets the cloud model, the MI50 fine-tune, RTO, and a human UI all interoperate is a single **stable tool/API schema** (operation names + JSON arg schemas). That contract is the training target for the fine-tune and the seam for every backend. MCP is deferred: it's a thin wrap over the same service, worth adding only when a *second host application* appears.

---

# Sub-project 1 — Poker logging service

## Goals

1. A complete API surface over the poker data model — create/read/update/delete for every entity, not just the few edit/delete endpoints exposed today.
2. A single **documented, versioned tool/API contract** that the REST API, Lyra's LLM tools, the human UI, a future MCP wrapper, and the MI50 fine-tune all share.
3. A human UI to **log** (fast capture) and **edit/correct** (fix Lyra's mistakes) every entity.
4. The 2nd input box (stack quick-capture) and the iOS-PWA bottom safe-area fix.
5. Pure data capture never touches the LLM.

## Non-goals

- Lyra's classifier / prompt fragments (sub-project 2).
- Enabling tools on the MI50 backend (sub-project 2).
- MCP wrapper (deferred until a second host app exists).
- Itemized buy-in history — buy-ins stay a single `buy_in_total` scalar.
- Rewriting the SQLite schema; we build on the existing tables.

## Current state (what exists)

- **Store & logic:** `lyra/poker.py` — schema at `poker.py:21` (tables `poker_sessions`, `poker_hands`, `poker_stack_log`, `poker_rituals`, `poker_players`, `player_reads`, `player_observations`). Functions: `start_session` (157), `add_buyin` (389), `log_stack` (407), `stack_state` (446), `update_session` (362), `end_session` (515), `log_hand` (541, flat/no-LLM), `record_hand` (770, LLM-parses shorthand), `add_read` (1010), `hud` (1245).
- **Exposed endpoints (`lyra/web/server.py`):** `GET /session/data` (hud), `PATCH /session/{id}`, `DELETE /session/entry/{kind}/{id}`, `GET/DELETE /history`, `GET /hand/{id}/data`, `POST /hand/{id}/reconstruct`, `GET /hands/data`, `GET /recap/...`. **No** direct create endpoint for stack/buyin/hand/read/session — those are reachable only through chat → tool-calling.
- **UI:** `index.html` (chat), `session.html` (live HUD: stack card + sparkline + a PATCH-based edit form via `saveEdit()` at `session.html:192`, and `del(kind,id)` at `211`), `history.html`, `hand.html`.
- **Tool specs:** `lyra/tools.py` already defines arg schemas for each operation (`_f(...)` specs, `tools.py:469-658`) — the embryo of the contract.

## Design

### 1. Store layer — harden `poker.py`

Keep the existing functions and tables; tighten the module into a clean service boundary so both the REST layer and Lyra's tools call the *same* functions. Each operation: validates input, resolves the target session (`_resolve`), writes, returns a consistent dict. No behavior change to existing callers; this is consolidation, not a rewrite.

### 2. The tool/API contract *(first-class deliverable)*

A single source-of-truth document + schema defining every operation: name, purpose, JSON arg schema, return shape, and which REST route + which LLM tool map to it. Versioned (e.g. `contract_version: 1`). Lives at `docs/POKER_API.md` (or a machine-readable `poker_contract.py` that both the REST routes and `tools.py` specs derive from — preferred, so they can't drift).

Operations (the canonical set):

| Operation | Args | Entity |
|---|---|---|
| `start_session` | venue, stakes, game, format, buy_in, mantra | session |
| `update_session` | venue, stakes, game, format, buy_in_total, cash_out, mantra, mood | session |
| `end_session` | cash_out, mood | session |
| `delete_session` | id | session |
| `log_stack` | amount, note | stack entry |
| `delete_stack` | id | stack entry |
| `add_buyin` | amount | session (increments buy_in_total) |
| `log_hand` | position, hole_cards, board, streets…, pot, result, tag, lesson | hand |
| `record_hand` | shorthand (LLM-parsed) | hand |
| `update_hand` | id, any hand field | hand |
| `delete_hand` | id | hand |
| `add_read` | note, name, seat, tendencies, adjustment, category, venue | player/read |
| `update_read` / `update_player` | id, fields | player/read |
| `delete_read` | id | player/read |
| rituals: `scar_note`, `confidence_bank`, `alligator_blood`, `reset_ritual` | … | ritual |

### 3. REST API — complete the surface (`lyra/web/server.py`)

Add the missing **create/update** routes so the human UI (and any non-LLM client) can do everything:

- `POST /session/stack` → `log_stack(amount, note?)`; server-stamped time; returns `stack_state()`.
- `POST /session/buyin` → `add_buyin(amount)`; returns `buy_in_total`.
- `POST /session` → `start_session(...)`.
- `POST /session/hand` → `log_hand(...)` (flat) and/or `record_hand(shorthand)`.
- `PATCH /hand/{id}` → `update_hand(...)`; `DELETE /hand/{id}`.
- `POST /session/read` → `add_read(...)`; `PATCH /read/{id}`; `DELETE` via existing entry-delete.
- Keep existing `PATCH /session/{id}`, `DELETE /session/entry/{kind}/{id}`, `GET /session/data`.

All return `{ok, ...}` and a clear error on "no live session." Routes are thin wrappers over the store, mirroring the contract one-to-one.

### 4. Human UI — log + edit/correct

**Fast capture:**
- **2nd input box** (`index.html`): slim row **below the message input, above the bottom nav icons**. Type a number → `POST /session/stack` → time-stamped, sparkline updates, a one-line confirmation drops into the **Live Log**. **No chat message, no LLM call.** Stack-only in v1. Tolerates `$685`/`685`.
- **HUD widget** (`session.html`, in the Stack card at `:280`, mirroring `saveEdit()` at `:192`): stack field (`POST /session/stack`), buy-in field (`POST /session/buyin`), cash-out field (existing PATCH).

**Edit / correct (fix Lyra's mistakes):**
- Edit any session field (exists via the PATCH edit form — verify coverage).
- Hands list with edit + delete (`hand.html` + new PATCH/DELETE) — fix mislabeled villains, wrong board, wrong result.
- Reads/players list with edit + delete — rename "Dave the rock" ≠ "Dave the mechanic", fix tendencies.
- Stack entries deletable (exists via `del('stack', id)`) — verify.

### 5. iOS-PWA bottom safe-area fix

The empty band below the nav icons is a safe-area issue (likely `100vh` not accounting for `env(safe-area-inset-bottom)` / the home indicator). Fix the layout container + bottom nav CSS so the app fills the viewport with the icons seated above the home indicator. Use the `building-ios-pwas` skill at implementation time.

## Testing / verification

- **Contract conformance:** a test asserting each REST route and each `tools.py` spec matches the canonical contract (names, required args) — catches drift between the human API and the LLM API.
- **Endpoint round-trips:** create → read → update → delete for stack, buyin, hand, read against a test session; assert rows written, time stamped, `stack_state()`/`hud()` reflect changes; assert clean error with no live session.
- **UI manual pass:** log a stack via the 2nd box and confirm it lands in Live Log + sparkline without a chat reply; edit a hand's villain and confirm persistence; delete a bad read.
- **PWA:** on the iOS PWA, confirm the bottom gap is gone and the 2nd input box sits above the nav with the keyboard open.

---

# Sub-project 2 — Lyra wiring *(parked)*

Detail preserved here; gets its own spec → plan after sub-project 1 is MVP'd.

## Why it exists (diagnosis from real sessions)

Evidence from `sess-dff2s91c` (2026-06-27 Meadows, 2026-06-28 Wheeling):

- **Coaching essay on every turn, including pure data** — `Stack=$685` drew 4–6 sentences of "keep that momentum rolling." (Sub-project 1's dumb capture removes these from the LLM entirely.)
- **False tilt/fatigue reads** — "table broke, it's 11:50pm" → repeated "late-night fatigue… mental reset"; Brian: *"you seem to be reading me as tilted."* Cause: the `_route` mood nudge (`mind.py:328`) firing on non-mood messages.
- **No bet-intent reasoning** — a value bet ($40, full house) that folded out 88 was praised as "the power of representing something stronger." It was value *lost*, not a successful rep.
- **Eyeballs instead of `analyze_spot`** — 77 multiway got "a disciplined fold might have been better," no math, violating the persona's "never eyeball poker math" rule.
- **Even her sharp reads leak bad logic** — the Connie read included "limp-checking in position" (contradictory).

Root cause: one broad per-turn card (`_CASH_CARD`, `modes.py:66`) describes traits; the model satisfies trait language with safe abstraction.

## Planned approach

- **Classifier** (`lyra/poker_classify.py`): `classify(message) -> HAND | STATUS | MENTAL | LOG | CHAT`. Heuristic v1 (card-token regex, position/street keywords, feeling phrases, time/venue), swappable for an LLM/MI50 classifier behind the same signature. Ambiguous → CHAT.
- **Pipeline:** a `_classify` step in `mind.PIPELINE` sets `ctx.msg_type` (poker mode only); `build_messages` injects the **type fragment** in the seat now held by `mode.card` (`mind.py:152`) instead of the whole `_CASH_CARD`.
- **Fragments** (`lyra/poker_prompts.py`, `POKER_FRAGMENTS`): concrete rules + response shape per type.
  - **HAND:** log it → `analyze_spot` if close → reason about **bet intent** (value/bluff/protection — did it work? a fold to a value bet = value lost, flag it) → name leaks (value-owning, missed value, sizing) → one opinion. No reflexive praise. Pull `player_profile` before referencing a villain. Seeded with 2 real-hand exemplars (the $40 value bet; the 77 spot).
  - **STATUS:** 1–2 sentences, no coaching, no tilt-reading.
  - **MENTAL:** full presence (already works — preserve).
  - **LOG:** one line.
  - **CHAT:** full voice, real opinion.
- **Pipeline fixes:** kill the misfiring `_route` mood nudge (`mind.py:328`); trim the always-on mode-menu note (`mind.py:77`) in poker mode.
- **MI50 tool-calling:** enable tools on the MI50 backend (`chat.py` `TOOL_BACKENDS = {"cloud"}` at `:21`) so a fine-tuned, tool-calling poker model can drive the contract. Requires the fine-tune to emit the contract's tool-call format.

## HAND exemplars (preserved for sub-project 2)

> *Brian:* "Flopped bottom set with 22, turned a full house, bet $40 on the river, he folded 88."
> *Lyra:* "That's a value bet that got no value — 88 was never folding to a smaller stab. $40 into that pot was too much; ~$20–25 gets called by the over-pair and worse two-pairs. The hand's a monster, the leak is the sizing."

> *Brian:* "77 multiway, flop 4h5c3c, HJ bets 75, BTN shoves 74, I call. Turn/river check through, HJ wins with 64."
> *Lyra:* "Against a bet and a shove on 4-5-3 you're drawing thin — sets, two pair, and the made wheel are all ahead, and you block almost none of it. The stack-depth read (he only had ~150 behind) is real, but that's a reason to fold and wait, not to call off light. This is the value-owning spot you flagged yourself."