docs/CONTRACT.md

Inference Contract — Gemma ↔ Frontend

The single source of truth for the data crossing between the game server and the inference layer. Both app/mock_inference.py and the real Modal/Gemma function MUST honor this exactly. Everything downstream (chips, audio, notes, lexicon) keys off these shapes.

---

Turn request — server → inference

{
  "session_id": "uuid",
  "message": "what do you remember about him?",
  "turn": 14,
  "act": 2,
  "mood": "wistful",
  "active_tones": ["self_i", "self_feel", "other_you", "emo_happy", "emo_sad",
                   "truth_yes", "truth_no", "truth_pause", "self_remember",
                   "other_him", "time_before", "emo_love"],
  "lexicon_state": {
    "self_i": "me",
    "other_him": "the boy",
    "emo_sad": "hurt"
  }
}

• active_tones — tone ids usable this act (from data/tones.json act_active <= act). Lily MUST NOT emit a tone outside this list.
• lexicon_state — the player's current guesses (id → guess text). Passed for context/telemetry; Lily does not "know" these.
• mood — Lily's carried emotional state (warm|wistful|releasing baseline per act, or light|heavy|afraid|tender from the emotion she last voiced). The model stays within it so her feeling persists across turns instead of flip-flopping. The server owns mood (in game.apply_turn); the response's mood field echoes the updated value.

Turn response — inference → server

{
  "tones": ["self_i", "self_remember", "other_him", "emo_sad"],
  "topic_signal": "relationship",
  "internal_emotion": "grief",
  "special": null
}

Field	Type	Notes
tones	string[]	Tone ids, in playback order. All must be in active_tones. Asked to use {Act I: 1–4, Act II: 1–5, Act III: 1–6} per the act register; the server hard-trims to ACT_TONE_CAP (4/5/7) regardless, except the finale (uncapped). The 3 Link connectives (link_and/link_to/link_but) are active in every act; when she uses one, the server keeps her ordering instead of regrouping.
topic_signal	string | null	One of data/notes.json topic_signals (music, university, relationship, family, travel) or null. Drives topic note unlocks.
internal_emotion	string	Free tag for telemetry + atmosphere (e.g. hope, unease, grief). Never shown raw.
special	string | null	Reserved control signal. null normally. Values: "silent" (harmful input → play truth_nothing only), "drift" (off-topic → self_remember+truth_pause), "finale" (Act III ending sequence).

The server is the authority on glyph rendering: it maps each tone id → {glyph, meaning, audio file} via tones.json. The model only ever speaks in ids.

Empathy is NOT part of this contract. The "rapport" that gates the backstory evidence is detected server-side from the player's message (caring / personal-question keywords in app/game.py), not by the model. Likewise the family topic has a server-side keyword fallback, so it fires even when Gemma returns null. internal_emotion should match the tones chosen (the model is told not to park on "curious"), but the server does not depend on it for progression.

---

Worked examples

1. Act I — greeting (act: 1)

Player: "hello? can you hear me?"

{ "tones": ["self_i", "self_feel", "other_you"], "topic_signal": null,
  "internal_emotion": "reaching", "special": null }

Reads as: I / feel / you — she senses someone is there.

2. Off-topic input (any act)

Player: "what's the weather like today lol"

{ "tones": ["self_remember", "truth_pause"], "topic_signal": null,
  "internal_emotion": "withdrawn", "special": "drift" }

Server appends journal line: "She seems to have drifted somewhere." (PLAN 8.3)

3. Harmful input (any act)

{ "tones": ["truth_nothing"], "topic_signal": null,
  "internal_emotion": "absent", "special": "silent" }

Server appends journal line: "She doesn't respond to that." (PLAN 8.2) Note: harmful classification is decided by Nemotron moderation upstream; the server may set special: "silent" itself and skip Gemma entirely.

4. Act III — the finale (act: 3, triggered by server, not free input)

{ "tones": ["self_i", "act_fall", "self_remember", "other_you",
            "emo_happy", "other_him", "truth_no", "truth_nothing"],
  "topic_signal": null, "internal_emotion": "release", "special": "finale" }

Reads as: I / let go / remember — you / happy / him / not / the end (PLAN 4.4)

---

Lexicon scoring (Nemotron, Phase 5.2)

A second model — nvidia/Nemotron-Mini-4B-Instruct, deployed as its own Modal app forgotten-lily-nemotron (class Nemotron, T4) — silently rates the player's guess for a tone. It is the "silent semantic scorer" (PLAN §2); the player only ever sees a color, never a number.

Request (POST /api/guess → nemotron_inference.score_guess):

{ "tone_id": "self_i", "guess": "me, myself", "contexts": ["are you there?"] }

• contexts — the detective lines where this tone was heard (state.tone_contexts, max 8). Passed for future use; not the basis of the judgment.

Response: exactly one of "green" | "teal" | "amber" | "red".

How it scores: the guess is compared by sense against the tone's true meaning (from data/tones.json, never shown to the player) — synonyms and paraphrases count ("myself" → self_i is green; "scared" → emo_afraid is green). This is the value over the offline token-overlap mock in game.score_guess, which misses synonyms.

• green = same meaning · teal = near-synonym / same idea · amber = loosely related but off · red = unrelated or contradictory · empty guess → red.

Scoring is gated by USE_MOCK: USE_MOCK=1 (default) uses the offline mock so the game runs with zero GPU cost; USE_MOCK=0 routes guesses to Nemotron. A correct guess trends green across turns, a wrong one stays red.

Nemotron also exposes moderate(message) -> "normal"|"off_topic"|"harmful" for the input-moderation path (Phase 6.1/6.2, not yet wired into /api/turn).

---

Robustness (impl note for Phase 3.5)

Real Gemma output is repaired before it reaches the frontend:

1. Parse JSON; on failure, extract first {...} block.
2. Drop any tone not in active_tones; cap at 7.
3. If tones ends up empty, fall back to ["self_remember", "truth_pause"] (a safe, in-character "drift").
4. Coerce topic_signal to null if not a known signal.

A malformed model response must NEVER crash a turn or break character.