interactive-story/planning/SPECIFICATION.md

Adventure Storyteller — Specification

Status: Draft v0.1
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 a local Ollama instance for v1.
   • 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.

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.

The final mechanism will be selected during Phase 0 research.

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

Production defaults must:

• bind the application to loopback unless intentionally configured otherwise,
• connect to Ollama through a local/approved endpoint,
• reject or warn on non-local 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.

A future LAN-access mode may be considered separately.

13. Browser-First Interface

The primary interface should be browser-based.

Expected areas include:

• campaign selection,
• story transcript,
• input composer,
• checkpoint/story-tree navigation,
• narrative state inspector,
• knowledge/library management,
• settings,
• prompt/context inspection,
• future media gallery.

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/voice.

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

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

Potential local media systems can be evaluated later.

16. Export and Backup

A campaign export should eventually be capable of including:

• transcript,
• branches,
• 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.

17. Explicit Non-Goals for v1

Unless Phase 0 changes the decision, v1 should 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,
• mobile-native apps,
• hosted SaaS deployment.

18. Candidate Starting Projects

Phase 0 will evaluate at minimum:

• Open Dungeon — newideas99/open-dungeon
• AI-DnD — parththakkar106/AI-DnD
• Local Adventure Engine / ai-adventure — CaoRuiming/ai-adventure
• aiMultiFool
• additional credible candidates discovered during research

Reference-only projects may include:

• SillyTavern,
• RisuAI,
• KoboldAI,
• Chronicler,
• other local interactive-fiction or long-memory systems.

19. Acceptance Criteria for Specification v1.0

Before implementation planning begins, the project must have:

• a selected base/fork strategy,
• confirmed licensing compatibility,
• confirmed local-only security approach,
• confirmed persistence/story-tree model,
• confirmed memory/retrieval strategy,
• confirmed browser architecture,
• confirmed Ollama integration model,
• confirmed campaign export/backup strategy,
• identified future media extension points,
• technical risks and tradeoffs documented.