interactive-story/plan/03-phase-context-insights.md

Phase 3 — Context engine + Insights

Goal: AI Dungeon-grade context management, and full visibility into every prompt.

Context assembly (context/builder.py)

Assembles the prompt each turn from AI Dungeon's plot components (per help.aidungeon.com/faq/the-memory-system):

[AI Instructions]               ← behavioral guidance for the model (always included)
[Plot Essentials]               ← key facts for constant recall — the classic "Memory" (always)
[Story Summary]                 ← running summary slot; manual in this phase, auto in Phase 6
[Triggered Story Cards]         ← "World Lore: <entry>" for each triggered card (conditional)
[Story history]                 ← as many recent actions as fit the token budget
[Author's Note]                 ← injected N lines (default 3) before the end of history
[Latest player action]          ← (+ script frontMemory right after it, Phase 4)

• AI Instructions / Plot Essentials / Story Summary / Author's Note: adventure-level free-text fields, always included, editable mid-adventure from the side panel.
• Story cards — five fields per official docs: Type (organizational, not sent to AI), Name (not sent to AI), Entry (sent when triggered), Triggers, Notes (not sent).
  • Triggers: comma-separated words/phrases; case-insensitive but space-sensitive; partial-word matching (boat triggers on boats); matched against both player input and AI output in the recent-story window.
  • Not instant: a card triggered mid-response only enters context on the next turn; once triggered, stays active while the triggering text remains in the context window.
  • Triggered entries injected once each, prefixed World Lore:; story cards are the first component dropped when context is full.
  • Editable per-adventure (copied from scenario at creation). Soft-cap sanity limit (AI Dungeon allows 5,000/adventure).
• Author's Note: inserted near the end (strongest steering position), formatted [Author's note: <text>].
• Token budgeting with tiktoken: always-included components (AI Instructions, Plot Essentials, Story Summary, Author's Note) reserved first; story cards get a capped share and are dropped first when over budget; remainder goes to story history (newest first). Budget = context_token_budget setting.
• Slots for script-provided memory overrides (Phase 4): state.memory.context (prepended), state.memory.authorsNote (replaces/augments author's note), state.memory.frontMemory (inserted immediately after the latest player action).
• Builder returns a structured ContextReport: ordered sections, each with source label, text, token count; plus totals and a list of triggered cards (and which keyword fired).

Insights

• Every AI turn stores its ContextReport on the Action row (context_snapshot).
• GET /adventures/{id}/actions/{id}/context returns it.
• Insights panel in Play UI (drawer/tab):
  • Exact final prompt text as sent, sectioned and color-coded (memory / world info / history / author's note / input), with per-section token counts and total vs budget.
  • Which story cards triggered and on which keyword; which history got cut off.
  • Viewable for the upcoming turn (dry-run endpoint: "what would be sent now") and for any past AI action.
• Adventure side panel: edit memory, author's note, story cards mid-game (AI Dungeon's right-hand panel equivalent).

Exit criteria

Create a card with key dragon; mention a dragon in play and see the card enter the context in the Insights panel (and influence the AI); verify memory and author's note appear in the snapshot in the right positions; long adventures visibly trim oldest history within budget.