Jesse.Markowitz/interactive-story
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Add initial planning files from ChatGPT research here

Browse Source
This commit is contained in:
JesseMarkowitz
2026-09-01 12:09:38 -04:00
commit f011362494
37 changed files with 14601 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
planning/SPECIFICATION.md
+420
View File
@@ -0,0 +1,420 @@
# 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.