interactive-story/planning/SPECIFICATION.md

Adventure Storyteller — Specification

Status: v1.0 — approved after Phase 0B architecture selection
Purpose: Define what the system must do, independent of implementation choice.

1. Product Goal

Build a local-first, browser-based interactive storytelling application that uses a locally hosted AI model to act as narrator and story collaborator.

The initial target is fantasy adventure fiction, but the system must remain genre-agnostic so the same engine can support science fiction, mystery, horror, historical fiction, westerns, and other settings through campaign configuration and imported local material.

This is primarily an interactive story, not a rules-driven role-playing game.

The application must preserve story continuity, authoritative world state, long-term memory, checkpoints, rollback, and branching without depending on the language model to remember everything correctly.

2. Core Principles

1. Local first

   • Primary operation must not require Internet access.
   • AI inference must use Ollama on user-controlled local infrastructure for v1; same-host loopback is the default, and an explicitly configured trusted-LAN Ollama host is supported.
   • Imported story/reference material must remain local.
   • No telemetry, analytics, remote fonts, remote assets, or automatic external content retrieval in the production configuration.
   • No cloud inference providers in v1.

2. Authoritative application state

   • The language model produces narration and proposed story developments.
   • The application owns the authoritative transcript, state, history, branches, checkpoints, and canon.
   • The model must not be treated as the system of record.

3. Persistent stories

   • Campaigns must survive application restarts.
   • A user must be able to leave a story and resume later.
   • The full original transcript must remain preserved even when only a subset is sent to the model.

4. Recoverability

   • Every accepted turn should be recoverable.
   • Users must be able to return to an earlier point.
   • Restoring an earlier point should preserve abandoned future history as an alternate branch rather than destructively erasing it.
   • Moving backward must move the active story head without deleting retained turns.
   • If the user continues differently from a moved-back head, the prior future becomes retained/disposable history rather than being overwritten.

5. Closed-corpus authority

   • Story canon may come from:
     • explicit campaign setup,
     • user-imported local files,
     • authoritative story state,
     • prior accepted story events,
     • newly invented material accepted into the story.
   • The model's pretrained knowledge may assist with language generation, but it must not silently override established campaign canon.

6. Genre independence

   • No fantasy-specific mechanics should be hard-coded into the core data model.
   • Generic concepts should include characters, locations, organizations, items, vehicles, events, relationships, facts, scenes, and story threads.

7. Future media support

   • v1 does not need image or video generation.
   • The architecture must preserve enough structured scene and character information to support future image, video, audio, and other media generation.

3. Primary User Experience

The user opens a local browser interface and can:

• create a new campaign,
• select or enter a genre/story profile,
• define the protagonist and initial setting,
• import local canon/reference/inspiration files,
• begin or resume a story,
• enter natural-language actions, dialogue, or narrative direction,
• read streamed narration from the local model,
• inspect story state and relevant context,
• create named checkpoints,
• move back to earlier turns,
• branch into alternate continuations,
• inspect or edit authoritative canon/state,
• export or back up a campaign.

The experience should feel like collaborative fiction with a persistent AI narrator, not a character-stat game.

4. Campaign Setup

A campaign should support:

• title,
• genre/profile,
• tone,
• writing style,
• protagonist description,
• world description,
• narrative rules,
• campaign-specific canon,
• optional imported local reference material,
• optional imported inspiration material,
• local model selection from installed Ollama models,
• generation settings.

Examples of profiles:

• low fantasy,
• high fantasy,
• hard science fiction,
• space opera,
• noir detective,
• historical adventure,
• horror.

Profiles should be data/configuration, not separate code paths.

5. Story Interaction Modes

The minimum interaction should support:

• Action / direction: user describes what the protagonist does.
• Dialogue: user specifies what the protagonist says.
• Story direction: user gives out-of-character guidance about pacing, tone, or desired developments.
• Continue: narrator continues without a new user action.
• Retry: generate an alternate response from the same parent state.
• Edit prior user or narrator text: where safe and supported by branch/state rules.

The exact UI labels may change during design.

6. Persistence and Story History

6.1 Turn preservation

Every accepted turn should record at minimum:

• unique turn ID,
• campaign ID,
• branch ID,
• parent turn ID,
• user input,
• model response,
• timestamp,
• model identifier,
• generation settings,
• exact prompt/context snapshot or reproducible equivalent,
• retrieved memory/lore references,
• associated structured state snapshot or state version,
• associated scene snapshot.

6.2 Story tree

The story history must support branching.

Conceptually:

Turn 100
   |
Turn 101
  /   \
102A  102B
 |      |
103A   103B

Alternate continuations must remain available unless the user explicitly deletes them.

6.3 Checkpoints

Support:

• automatic recoverability at every accepted turn,
• named checkpoints,
• restore/jump to prior turn,
• branch from any recoverable point,
• export/backup.

7. Narrative State

The application should maintain structured narrative continuity where useful.

Generic state categories may include:

• characters,
• locations,
• organizations/factions,
• possessions/items,
• vehicles,
• relationships,
• known facts,
• unresolved story threads,
• promises/debts/commitments,
• injuries/conditions where narratively relevant,
• timelines and chronology,
• scene participants,
• current location,
• current scene,
• established world rules.

This state is not intended to become a D&D-style stat system unless a future optional module adds one.

8. Long-Term Memory

The application must not rely on sending the entire transcript to Ollama.

Context construction should support:

• permanent campaign instructions,
• current authoritative state,
• high-level story summary,
• chapter/arc summary,
• recent turns,
• relevant older story memories,
• relevant local canon/reference/inspiration passages,
• current user input.

The full original transcript must remain preserved even if older turns are summarized or omitted from the active model context.

9. Local Knowledge Library

Users should be able to import local material.

Initial file types:

• .txt
• .md

Later candidates:

• .pdf
• .epub
• .docx
• structured JSON/TOML/YAML campaign packs.

Each source should be classified as one of:

Canon

Authoritative facts that are true in the campaign.

Reference

Supporting factual or descriptive material the narrator may use.

Inspiration

Material that may influence atmosphere, situations, and prose but must not override canon.

The application should preserve source provenance for retrieved passages.

10. Retrieval

Retrieval should be local.

Potential mechanisms:

• SQLite full-text search,
• local embeddings generated through Ollama,
• hybrid lexical/vector retrieval.

Selected v1 direction: local hybrid retrieval using a deterministic lexical index plus local Ollama semantic embeddings where enabled. Lexical retrieval must remain usable if embeddings fail or are disabled.

Requirements:

• no remote vector database,
• no external embedding service,
• source provenance retained,
• campaign-specific scoping,
• retrieval inspectable for debugging.

11. Prompt Transparency

For troubleshooting and reproducibility, the user should be able to inspect what the narrator was given for a turn.

This should include, directly or indirectly:

• system/narrator instructions,
• campaign rules,
• state,
• summaries,
• recent turns,
• retrieved memories,
• retrieved lore/reference passages,
• current user input.

12. Local-Only Security Requirements

For v1, local-only means the storyteller, storage, inference, and retrieval remain on user-controlled local infrastructure and require no Internet/cloud service. Components may run on more than one machine on a trusted LAN.

Production defaults must:

• bind the storyteller application/UI/API to loopback unless a later explicit storyteller-LAN mode is enabled,
• default Ollama to same-host loopback,
• allow an explicitly configured trusted-LAN Ollama endpoint for narration, state extraction, summarization, and local embeddings,
• make the configured inference destination visible/inspectable,
• reject or explicitly gate arbitrary public/Internet model endpoints,
• include no telemetry,
• include no analytics,
• avoid remote fonts and CDN-delivered runtime dependencies,
• avoid automatic URL retrieval,
• avoid cloud model providers,
• avoid executable imported content,
• treat imported files as untrusted data,
• document all outbound network behavior,
• allow operation with the machine disconnected from the Internet.

LAN inference is supported in v1. LAN access to the storyteller web UI/API is a separate feature and may be considered later; enabling one must not implicitly enable the other.

13. Browser-First Interface

The primary interface should be browser-based.

Expected areas include:

• campaign selection,
• story transcript,
• input composer,
• Save Point/history navigation,
• narrative state inspector,
• knowledge/library management,
• settings,
• prompt/context inspection,
• future media gallery,
• reserved local speech-to-text input affordance where appropriate.

Terminal tooling may exist for administration, migration, diagnostics, or development, but must not be the primary user experience.

14. Scene Model and Future Media

v1 should preserve enough information for future media generation.

A scene snapshot may include:

• scene ID,
• source turn range,
• location,
• time/day/lighting,
• mood,
• characters present,
• visual character descriptors,
• significant objects,
• important actions,
• environment,
• continuity notes.

Character records should allow optional visual descriptors.

Location records should allow optional visual profiles.

The system should reserve a generic media abstraction for future:

• scene images,
• character portraits,
• location art,
• storyboards,
• recap images,
• multi-turn video clips,
• audio/ambience,
• text-to-speech,
• speech-to-text draft input.

Media generation must remain optional and separable from the core story engine.

15. Future Media Provider Concept

The core application should eventually be able to call provider adapters such as:

Media Provider
├── Image Provider
├── Video Provider
├── Audio Provider
├── TTS Provider
└── STT Provider

The story engine must not depend on a specific image or video backend.

Potential local media systems can be evaluated later. Speech-to-text output must remain editable draft user input and must enter the story through the normal submission/commit path.

16. Export and Backup

A campaign export must preserve enough information to restore the exact active story position, including an active head that is behind the retained tip after Undo. The export should be capable of including:

• transcript,
• branches,
• active branch and active head position,
• retained/disposable alternate history,
• checkpoints,
• structured state,
• campaign configuration,
• summaries,
• imported knowledge metadata,
• scene snapshots,
• generated media metadata,
• optionally generated media files.

The export format should be portable and documented. Importing a campaign must not silently advance the head to the newest retained turn when the exported campaign was intentionally positioned earlier.

17. Explicit Non-Goals for v1

v1 does not require:

• D&D or other RPG rules,
• dice,
• hit points,
• combat simulation,
• multiplayer,
• cloud accounts,
• cloud inference,
• Internet search,
• automatic online content downloading,
• image generation,
• video generation,
• text-to-speech,
• speech-to-text,
• mobile-native apps,
• hosted SaaS deployment.

18. Phase 0 Candidate Outcome

Phase 0 evaluated the principal candidates and selected AI-DnD as the production base.

Disposition:

• AI-DnD — production fork/base.
• ai-adventure / Local Adventure Engine — primary implementation reference for typed authoritative state events, head/checkpoint/replay semantics, and narrow local-only behavior.
• Open Dungeon — UX and future local-media reference only.
• Chronicler, Interactive Fiction Framework, Gamentic, and other reviewed projects — concept/reference sources only as documented in the research reports.

The project will not mechanically merge candidate repositories.

19. Phase 0 Outcome and Specification v1.0 Status

Phase 0 satisfied the architecture-selection prerequisites for this specification:

• production base selected: AI-DnD at the pinned Phase 0B commit,
• licensing path confirmed as permissive for the selected base,
• local-only hardening requirements identified,
• story-history approach confirmed as non-destructive active-head movement over retained lineage,
• state authority confirmed as application-owned with validated proposals,
• narrative-state implementation direction selected: explicit typed events plus snapshots/cache,
• memory/retrieval direction confirmed as local, lineage-aware, provenance-preserving, and authority-aware,
• imported knowledge confirmed as a separate first-class subsystem,
• browser architecture confirmed as React/Vite + FastAPI from the selected base,
• Ollama integration validated locally,
• export/import requirement expanded to preserve active head position,
• future media extension points preserved without making media a v1 dependency.

The implementation details are defined in TECHNICAL-DESIGN.md. Candidate-project behavior does not override this specification.