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:

```text
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:

```text
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.