# 060 — Narrator prompts and AI preparation

## Request design

One pack-generation inference per Start, Play again, or explicit Retry. Use the user's existing selected provider/model, common `AIProvider.send_prompt`, JSON mode where supported, and `use_tools=False`. Assign a new transient session ID and a distinct usage category such as `story_prepare`.

Route through the existing provider layer so every successful/failed request is accounted once. Do not call `track_ai_usage` separately. Do not extend `AIHandler` with another large game block; Story's small LLM boundary belongs to `wcs/games/story/ai.py`.

No continuous chat, per-scene inference, feedback inference, question prefetch thread, or director tip is required: all content already exists in the pack. No provider/model upgrade, sampling override, pricing change, or new key check is part of this feature.

Do not set a tighter generation timeout in the game than the existing clients can support. Their existing output budget must accommodate 20 scenes and any model reasoning tokens; handle truncated output as invalid content rather than starting a partial story.

Observed real calls justify a Story-only 32000-token ceiling and 300 s timeout for OpenAI/Anthropic high/xhigh/max. Other configurations retain 16000 and client defaults. Neither ceiling guarantees completion or accuracy; there is no automatic repair/retry. Exact measurements and prompt variants are in `130-ai-experiments.md`.

## Prompt structure

Write the production prompt in Czech, consistent with the current game. Keep it direct and compact rather than repeating warnings in all caps. Build it from:

1. Role and task: concise canonical storyteller for a Czech TV viewer; prepare the whole selected plot quiz.
2. Exact subject: title/year when known, media/scope, supplied episode title/numbers, plot context explicitly labeled a short identification aid rather than a full source.
3. Difficulty: requested count, major-versus-finer plot events, all five chapters spanning the whole work.
4. Narrative constraints: presentation order, no alternative branches, no outside trivia, no later spoilers in a current setup, viewpoint selected per event.
5. Quality constraints: certain concrete canonical events, one unambiguous correct answer, three plausible wrong events/actions, no option that also occurs in the same queried moment.
6. Contract and shared length limits, including the unavailable response.

Request only the contract JSON, not chain-of-thought, a research essay, a hidden outline field, or a second transcript. The complete scenes already provide the outline needed for coverage.

## Required instruction substance

Translate these requirements naturally into the actual concise prompt:

- Retell this exact work as its audience experiences it; preserve intentional flashbacks and revelations.
- Cover the whole plot from beginning to ending. Chapter numbers are positional groups, not thematic instructions that permit reordering events.
- Each setup leads to a question about the next concrete event or action at that moment. Perspective may follow any relevant character.
- Do not state the correct action/event in setup or question. Do not reveal later outcomes in setup, option wording, or current reveal.
- Each reveal states what really happens regardless of the player's choice; the following setup continues that same reality.
- Keep options comparable in grammar and specificity; avoid jokes, absurd distractors, “all/none”, subjectively defensible interpretations, and answer-length clues.
- Prefer concrete recognizable events you reliably know over obscure visual details, quotations, scene timestamps, or invented precision.
- Separate this adaptation/version and selected installment/episode from books, remakes, sequels, and the actor's other roles.
- Narrate calmly and briefly. No TV host, greeting at every scene, score commentary, congratulatory filler, money, lifelines, or audience.
- If knowledge cannot support a complete coherent pack of the requested scope/count, return `unavailable`; do not fill missing parts with invented events.
- Fresh requests can vary questions and distractors while retaining canonical facts/order/coverage. Do not demand plot novelty; no stored history is needed or sent.

Do not claim all titles are in the model's knowledge. Standa accepts reduced accuracy for new/less-known works and chose knowledge-only generation. A good prompt reduces risk; it does not make fictional certainty measurable.

## Content lifetime and metadata

The pack lives only in the active attempt. Starting a new game sends a fresh request without previous packs or player history. Closing/replaying releases it. No SQLite table, JSON cache, stored chat, resume file, prompt-response archive, or cross-game anti-repeat memory.

This does not prohibit the approved saved mode/difficulty, authored demo files, or the existing call-accounting rows (provider, model, title/session, tokens, cost, latency, error category). Do not confuse those with reusable content memory.

Avoid logging complete generated packs in Story code. Existing dev probes can capture HTTP bodies and game transcripts; disable that content persistence for Story AI by default, retaining bounded diagnostic metadata. Persisted authored-demo traces/screenshots for requested tests are fine. Any explicit temporary AI-content diagnostic capture must be separately authorized and recorded; it must never become a gameplay cache.

## Offline prompt checks

Render the request for Matrix at all counts without executing a provider. Verify subject identity, selected count, scope, chapters, field limits, JSON shape, unavailable form, and lack of tools/moderator/lifeline instructions. Stub the provider to prove one call per preparation and no calls on answer/Continue.

A paid Matrix AI test, if later requested, is distinct from the fixed demo checks. Report provider/model before it and review the whole generated storyline manually; a successful authored Matrix demo does not establish AI accuracy.

## Future: optional online grounding

Deferred, explicitly outside initial implementation. A future user-approved phase could retrieve trustworthy plot/episode sources, pass a concise grounded outline to the same pack generator, and verify event claims with provenance. Episode/adaptation identity, incomplete sources, tool support across providers, latency/cost, and source availability would need a new decision.

Keep the current `prepare()` -> normalized pack boundary so future grounding can feed it. Do not ship a dormant retrieval framework, provider-specific web calls, dependencies, or settings for a feature not being implemented. Online access is never an automatic fallback in the first release.