Jesse.Markowitz/interactive-story
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
f011362494756774d7ced69b934485b6c8ebab94
interactive-story/planning/TECHNICAL-DESIGN.md
T

711 lines
16 KiB
Markdown
Raw Blame History

# Adventure Storyteller — Technical Design
**Status:** Provisional v0.1
**Important:** This document describes the current preferred architecture. Phase 0 research is expected to confirm, revise, or replace portions of it.
## 1. Design Objective
Implement a local-first, browser-based interactive storytelling system in which:
- Ollama provides local AI inference,
- the application owns authoritative story state,
- complete story history is persistent,
- long-running context is reconstructed from state, summaries, retrieval, and recent turns,
- users can checkpoint, restore, retry, and branch,
- imported knowledge remains local,
- future media generation can be added without redesigning the story engine.
## 2. Current Provisional Architecture
```text
Local Browser
|
v
+------------------+
| Browser UI |
+--------+---------+
|
v
+------------------+
| Story Director |
| API / Service |
+---+----------+---+
| |
+--------+ +----------------+
v v
+----------------------+ +----------------------+
| Authoritative Store | | Context / Retrieval |
| SQLite (provisional) | | local only |
+----------+-----------+ +----------+-----------+
| |
| v
| +----------------------+
| | Local embeddings / |
| | lexical retrieval |
| +----------+-----------+
| |
+-------------------+------------------+
|
v
+---------------+
| Ollama |
| localhost |
+-------+-------+
|
v
Local narrator model
```
Future:
```text
Story / Scene State
|
v
+-------------------+
| Media Coordinator |
+----+---------+----+
| |
v v
Image Video
Provider Provider
```
## 3. Base Repository Strategy
**Status: UNDECIDED**
Phase 0 will determine whether to:
1. fork Open Dungeon and add stronger state/memory/branching,
2. fork AI-DnD and remove RPG/cloud complexity,
3. use `CaoRuiming/ai-adventure` as the core and add browser/Ollama layers,
4. build a thin new application using selected reusable components,
5. choose another candidate discovered during research.
The chosen strategy must be justified with code-level evidence rather than README feature comparison alone.
## 4. Component Boundaries
### 4.1 Browser UI
Responsibilities:
- campaign selection,
- campaign creation/editing,
- transcript display,
- streaming narrator output,
- user input,
- branch/checkpoint navigation,
- state inspection/editing,
- library/source management,
- prompt/context inspection,
- settings,
- future media controls/gallery.
The browser UI must not directly own story authority.
### 4.2 Story Director
Responsibilities:
- accept user turns,
- load authoritative campaign/branch state,
- construct model context,
- invoke Ollama,
- validate and commit accepted outputs,
- trigger summarization/state extraction as needed,
- maintain branch/tree relationships,
- create scene snapshots,
- record provenance/debug metadata,
- expose state/history APIs to the browser.
### 4.3 Model Adapter
v1 target: Ollama.
Responsibilities:
- enumerate allowed local models,
- invoke chat/generation,
- support streaming,
- invoke local embedding model if selected,
- expose model metadata,
- reject unsupported remote/cloud providers.
Provisional endpoint default:
```text
http://127.0.0.1:11434
```
### 4.4 Authoritative Store
**Provisional choice:** SQLite.
Reasons:
- local,
- transactional,
- portable,
- easy backup,
- strong fit for structured story/state data,
- can support FTS,
- no external service required.
Phase 0 must validate whether the selected fork already has a suitable schema and migration system.
### 4.5 Knowledge Store
Provisional options:
- SQLite FTS,
- embeddings stored in SQLite,
- local vector library,
- hybrid lexical/vector retrieval.
Remote vector databases are out of scope for v1.
### 4.6 Media Coordinator
Not required for v1 implementation, but interface boundaries should be reserved.
Responsibilities later:
- accept scene/character/turn-range generation requests,
- transform story state into media-generation packets,
- call pluggable local media providers,
- record asset provenance,
- attach assets to campaigns/scenes/turns.
## 5. Authoritative Data Model
The exact schema is provisional.
### 5.1 Campaign
Possible fields:
- `id`
- `title`
- `profile`
- `tone`
- `style`
- `narrator_rules`
- `created_at`
- `updated_at`
- `active_branch_id`
- `model_config_id`
### 5.2 Branch
Possible fields:
- `id`
- `campaign_id`
- `name`
- `root_turn_id`
- `head_turn_id`
- `created_from_branch_id`
- `created_at`
### 5.3 Turn
Possible fields:
- `id`
- `campaign_id`
- `branch_id`
- `parent_turn_id`
- `sequence_hint`
- `user_input`
- `assistant_output`
- `created_at`
- `model_id`
- `generation_config`
- `prompt_snapshot_id`
- `state_version_id`
- `scene_snapshot_id`
The graph/tree relationship should come from parentage, not merely sequential row order.
### 5.4 Checkpoint
Possible fields:
- `id`
- `campaign_id`
- `turn_id`
- `name`
- `notes`
- `created_at`
Every accepted turn is implicitly recoverable even when not given a name.
### 5.5 Narrative Entity
A generic entity model should avoid genre-specific database design.
Possible categories:
- character,
- location,
- organization,
- item,
- vehicle,
- object,
- concept,
- other.
Possible fields:
- `id`
- `campaign_id`
- `type`
- `name`
- `canonical_description`
- `visual_description`
- `status`
- `metadata_json`
Separate normalized tables may replace a generic entity table if research shows that is cleaner.
### 5.6 Fact
Potential representation:
- subject,
- predicate,
- object/value,
- source turn,
- canonical status,
- validity interval/version,
- confidence/review state.
The design should distinguish accepted canon from merely proposed model content.
### 5.7 Relationship
Potential examples:
- character-to-character,
- character-to-organization,
- entity-to-location,
- ownership,
- allegiance,
- trust/hostility,
- family/friendship.
### 5.8 Story Thread
Possible fields:
- title,
- description,
- status,
- opened_turn_id,
- resolved_turn_id,
- importance,
- related entities.
### 5.9 Summary
Potential levels:
- full campaign summary,
- arc/chapter summary,
- branch summary,
- rolling compressed memory.
Each summary should record what source turns it represents.
### 5.10 Scene Snapshot
Provisional fields:
- `id`
- `campaign_id`
- `branch_id`
- `source_turn_start`
- `source_turn_end`
- `location_entity_id`
- `time_description`
- `mood`
- `participants_json`
- `environment_json`
- `visual_notes`
- `action_beats_json`
- `continuity_notes_json`
### 5.11 Asset / Asset Job
May exist in schema before implementation.
Potential asset fields:
- `id`
- `campaign_id`
- `scene_id`
- `type`
- `provider`
- `model`
- `prompt`
- `settings_json`
- `file_path`
- `created_at`
- `source_turn_range`
No v1 dependency should require these tables to contain data.
## 6. Turn Processing
Provisional turn pipeline:
```text
1. Receive user input
2. Resolve campaign + active branch + parent turn
3. Load authoritative state
4. Retrieve recent turns
5. Retrieve relevant older story memory
6. Retrieve relevant local canon/reference/inspiration
7. Build narrator context
8. Save prompt/context provenance
9. Invoke Ollama narrator model
10. Stream response to UI
11. Validate completion
12. Extract proposed state changes
13. Validate proposed state changes
14. Commit turn + state + scene atomically
15. Update summaries/indexes when thresholds require it
16. Expose new recoverable branch head
```
The final implementation may combine or reorder steps depending on selected repository architecture.
## 7. State Extraction
The system may use a second local model call to convert narration into proposed structured changes.
Example:
```json
{
"new_facts": [],
"changed_entities": [],
"opened_threads": [],
"resolved_threads": [],
"scene_changes": []
}
```
Rules:
- model-produced state changes are proposals,
- authoritative updates must pass application validation,
- invalid structured output must not corrupt the campaign,
- narration should remain preserved even if extraction must be retried or repaired.
A deterministic/non-LLM extraction layer may supplement this later.
## 8. Context Construction
Target conceptual structure:
```text
Narrator/system rules
+
Campaign profile
+
Authoritative canon/world rules
+
Current narrative state
+
Campaign/arc summary
+
Relevant older memories
+
Relevant imported local material
+
Recent turns
+
Current user input
```
Context must be bounded by configurable token budget.
Priority ordering should be explicit.
## 9. Memory Architecture
The application should distinguish:
1. **Authoritative transcript**
- never pruned from storage.
2. **Recent context**
- direct recent turns.
3. **Summaries**
- compressed representation of older ranges.
4. **Structured state**
- current accepted facts/entities/threads.
5. **Retrievable memories**
- indexed older story events.
6. **Imported knowledge**
- local canon/reference/inspiration.
The exact retrieval implementation is a Phase 0 decision.
## 10. Knowledge Ingestion
Initial ingestion pipeline:
```text
Local file
|
v
Parse as data
|
v
Classify source:
Canon / Reference / Inspiration
|
v
Chunk
|
+--> lexical index
|
+--> optional local embeddings
|
v
Store provenance
```
Requirements:
- imported content is not executable,
- no macros/plugins/scripts from imported content,
- no automatic URL fetching,
- original source metadata preserved,
- campaign association explicit,
- re-indexing repeatable.
## 11. Branching and Restore Model
Preferred behavior:
- accepted turns are immutable historical events,
- editing or retrying creates a new continuation unless the implementation provides an equally auditable versioning model,
- restore changes active branch/head rather than deleting historical rows,
- named checkpoints point to turn/state identities,
- abandoned branches remain navigable,
- explicit delete may be supported later.
Phase 0 should compare existing candidate implementations against this model.
## 12. Prompt and Provenance Inspection
For each narrator turn, retain enough information to answer:
- what instructions were sent,
- what story state was included,
- what old memories were retrieved,
- what knowledge chunks were retrieved,
- which model/settings were used,
- what structured updates were proposed,
- what was accepted/rejected.
Storage may use normalized tables or compressed prompt snapshots.
## 13. Security Design
### 13.1 Network
Default production mode:
- browser connects to local application,
- application connects to local Ollama,
- no required outbound Internet access.
Phase 0 must inventory all network behavior inherited from any fork.
### 13.2 Remote dependency removal
Candidate fork review must identify:
- analytics SDKs,
- telemetry,
- crash reporting,
- hosted fonts,
- CDNs,
- remote image assets,
- update checks,
- cloud auth,
- remote databases,
- cloud model providers,
- web scraping/fetch features.
Any retained remote behavior must be explicitly justified and configurable; preferred v1 state is none.
### 13.3 Imported content
Treat imports as untrusted data.
Do not:
- execute HTML/JS from imported material,
- execute scripts,
- execute plugin code,
- follow embedded URLs automatically,
- pass filesystem paths to the model unnecessarily.
### 13.4 Ollama endpoint
Default loopback.
Potential future LAN support should require explicit configuration and documented security implications.
## 14. Browser Architecture
The final frontend framework should depend partly on fork selection.
Candidate inherited stacks may include React/Next.js or other browser frameworks.
Required UI capabilities:
- streaming text,
- responsive transcript,
- branch navigation,
- state/library inspectors,
- local settings,
- future image/video display,
- no hard dependency on remote CDN resources at runtime.
## 15. Future Media Architecture
### 15.1 Scene packet
The story engine should be able to transform authoritative state into a neutral media packet.
Example:
```yaml
scene_id: scene-128
source_turns: [128, 129]
location: Crooked Lantern tavern
mood: tense
characters:
- id: aldric
visual_reference: ...
- id: mara
visual_reference: ...
important_actions:
- Aldric enters
- Mara signals from the rear table
visual_continuity:
- same green cloak as prior scene
```
### 15.2 Provider abstraction
Future conceptual interface:
```text
generate_scene_image(scene_id, options)
generate_character_portrait(character_id, options)
generate_video(turn_start, turn_end, options)
```
No story-engine component should depend on a specific media model.
### 15.3 Asset provenance
Store:
- model/provider,
- prompt,
- settings,
- scene/turn sources,
- generation date,
- local file location,
- optional seed/workflow metadata.
## 16. Genre Profiles
Profiles should be configuration.
Example hard-SF profile:
```yaml
genre: hard_scifi
rules:
- Respect established technology limits.
- Do not introduce supernatural events unless canon allows them.
- Preserve travel-time and distance continuity.
```
Example fantasy profile:
```yaml
genre: low_fantasy
rules:
- Magic exists only as established in campaign canon.
- Avoid modern technology.
- Preserve setting-specific social and technological constraints.
```
The storage and story engine should not change between these profiles.
## 17. Testing Strategy
Phase 0 should determine inherited test quality.
v1 should ultimately cover:
- story turn persistence,
- branch creation,
- checkpoint restore,
- state rollback,
- failed model call recovery,
- malformed structured extraction,
- context budgeting,
- knowledge retrieval,
- source provenance,
- export/import,
- local-only network assumptions,
- schema migration,
- media schema backward compatibility.
## 18. Open Technical Questions for Phase 0
1. Which repository should be the base?
2. Which existing story-tree implementation is safest to reuse?
3. Should state be event-sourced, snapshot-based, or hybrid?
4. Is SQLite alone sufficient for embeddings?
5. Which Ollama embedding model is appropriate?
6. How should retrieved story memories differ from imported lore?
7. How much state extraction can be deterministic?
8. Should the app use one model for narration and another for summarization/extraction?
9. How should edit/retry semantics map to branches?
10. What exact campaign export format should v1 use?
11. Which schema pieces should be introduced now solely for future media?
12. Which dependencies in candidate forks violate local-only requirements?
## 19. Technical Design v1.0 Exit Criteria
This document becomes v1.0 only after Phase 0 has:
- selected the base architecture,
- validated the candidate application locally,
- selected storage/versioning strategy,
- selected memory/retrieval design,
- selected Ollama integration approach,
- completed dependency/network/privacy review,
- documented migration/reuse strategy,
- resolved licensing questions,
- defined v1 API/component boundaries,
- defined implementation milestones.
Reference in New Issue View Git Blame Copy Permalink