Add initial planning files from ChatGPT research here
This commit is contained in:
JesseMarkowitz
File diff suppressed because it is too large
Load Diff
@@ -0,0 +1,163 @@
|
||||
# Adventure Storyteller — Build Milestones
|
||||
|
||||
**Status:** Placeholder / intentionally incomplete
|
||||
**Do not use for production implementation yet.**
|
||||
|
||||
## 1. Purpose
|
||||
|
||||
The detailed production implementation plan will be created at the end of **Phase 0 — Research, Validation & Architecture**.
|
||||
|
||||
A precise plan cannot responsibly be written before the project has selected:
|
||||
|
||||
- the base repository or build strategy,
|
||||
- the final persistence/story-tree design,
|
||||
- the final browser architecture,
|
||||
- the Ollama integration model,
|
||||
- the memory/retrieval strategy,
|
||||
- the local-only hardening approach,
|
||||
- the migration/reuse plan for inherited code.
|
||||
|
||||
## 2. Why This Document Is Deliberately Limited
|
||||
|
||||
Different fork choices create fundamentally different engineering work.
|
||||
|
||||
Example:
|
||||
|
||||
### If Open Dungeon is selected
|
||||
Early milestones may require:
|
||||
|
||||
- adding immutable story-tree persistence,
|
||||
- adding branch-aware state restoration,
|
||||
- introducing structured narrative state,
|
||||
- adding long-term semantic memory.
|
||||
|
||||
### If AI-DnD is selected
|
||||
Early milestones may instead require:
|
||||
|
||||
- removing RPG mechanics,
|
||||
- removing cloud providers,
|
||||
- removing account/hosted assumptions,
|
||||
- simplifying world state while preserving story-tree behavior.
|
||||
|
||||
### If ai-adventure is selected
|
||||
Early milestones may instead require:
|
||||
|
||||
- adding an Ollama adapter,
|
||||
- adding a browser API,
|
||||
- building the browser UI,
|
||||
- extending lore retrieval beyond current behavior.
|
||||
|
||||
A single detailed build plan written now would therefore contain false precision.
|
||||
|
||||
## 3. Expected High-Level Production Phases
|
||||
|
||||
These are directional only and must be rewritten after Phase 0.
|
||||
|
||||
### Phase 1 — Production Foundation
|
||||
- establish production fork/repository,
|
||||
- preserve upstream provenance,
|
||||
- remove or isolate unwanted functionality,
|
||||
- establish development/test environment,
|
||||
- confirm local Ollama integration.
|
||||
|
||||
### Phase 2 — Authoritative Story Persistence
|
||||
- immutable/recoverable turn history,
|
||||
- branch parentage,
|
||||
- checkpoints,
|
||||
- restore,
|
||||
- retry/edit semantics,
|
||||
- transactional commits.
|
||||
|
||||
### Phase 3 — Narrative State
|
||||
- generic entities,
|
||||
- facts,
|
||||
- relationships,
|
||||
- story threads,
|
||||
- state extraction/validation,
|
||||
- state inspector.
|
||||
|
||||
### Phase 4 — Long-Term Memory
|
||||
- summaries,
|
||||
- older-turn retrieval,
|
||||
- token budgeting,
|
||||
- provenance,
|
||||
- continuity handling.
|
||||
|
||||
### Phase 5 — Local Knowledge Library
|
||||
- local file imports,
|
||||
- Canon / Reference / Inspiration classes,
|
||||
- chunking,
|
||||
- local indexing,
|
||||
- optional local embeddings,
|
||||
- retrieval inspection.
|
||||
|
||||
### Phase 6 — Browser UX Completion
|
||||
- campaign management,
|
||||
- transcript,
|
||||
- branching visualization,
|
||||
- checkpoints,
|
||||
- state/editor,
|
||||
- library management,
|
||||
- prompt inspection,
|
||||
- responsive local UI.
|
||||
|
||||
### Phase 7 — Local-Only Hardening
|
||||
- remove remote providers,
|
||||
- remove telemetry/analytics,
|
||||
- remove runtime CDN dependencies,
|
||||
- enforce/validate local endpoints,
|
||||
- network tests,
|
||||
- offline operation tests.
|
||||
|
||||
### Phase 8 — Export, Backup, and Recovery
|
||||
- campaign export,
|
||||
- import,
|
||||
- backups,
|
||||
- migration,
|
||||
- corruption/error recovery.
|
||||
|
||||
### Phase 9 — Future-Media Hooks
|
||||
- scene snapshots,
|
||||
- visual character/location descriptors,
|
||||
- asset schema,
|
||||
- media-provider interfaces,
|
||||
- no required image/video implementation.
|
||||
|
||||
### Phase 10 — v1 Validation and Release
|
||||
- regression testing,
|
||||
- long-story testing,
|
||||
- rollback/branch tests,
|
||||
- offline test,
|
||||
- migration test,
|
||||
- documentation,
|
||||
- release packaging.
|
||||
|
||||
## 4. Gate Before This Plan Becomes Active
|
||||
|
||||
Do not convert the high-level phases above into Codex implementation prompts until all of the following exist:
|
||||
|
||||
- `SPECIFICATION.md` v1.0,
|
||||
- `TECHNICAL-DESIGN.md` v1.0,
|
||||
- completed Phase 0 research reports,
|
||||
- approved fork/build ADR,
|
||||
- approved licensing/reuse review.
|
||||
|
||||
## 5. Required Format for the Final Build Plan
|
||||
|
||||
When rewritten after Phase 0, every production milestone should contain:
|
||||
|
||||
- objective,
|
||||
- scope,
|
||||
- explicit non-scope,
|
||||
- prerequisite milestones,
|
||||
- files/components expected to change,
|
||||
- implementation tasks,
|
||||
- data/schema changes,
|
||||
- tests required,
|
||||
- security/privacy checks,
|
||||
- acceptance criteria,
|
||||
- rollback/migration notes,
|
||||
- documentation updates,
|
||||
- definition of done.
|
||||
|
||||
The final document should be suitable for handing directly to Codex one milestone at a time.
|
||||
@@ -0,0 +1,9 @@
|
||||
# Codex Handoff Note
|
||||
|
||||
For the initial Phase 0B validation round, use:
|
||||
|
||||
`PHASE-0B-CODEX-BRIEF.md`
|
||||
|
||||
This is the current concise execution brief.
|
||||
|
||||
`PHASE-0B-CODEX-HANDOFF.md` is retained as a more detailed reference/appendix and should not be treated as the primary execution prompt unless specifically needed.
|
||||
File diff suppressed because it is too large
Load Diff
@@ -0,0 +1,745 @@
|
||||
# Adventure Storyteller — Data Model
|
||||
|
||||
**Status:** Draft v0.1
|
||||
**Purpose:** Define the persistent information the application must represent, independent of the final fork or database implementation.
|
||||
|
||||
## 1. Design Goals
|
||||
|
||||
The data model must support persistent interactive stories, complete authoritative history, non-destructive branching, checkpoints and rollback, genre-independent narrative state, long-term memory, imported local knowledge, prompt/context provenance, future image/video generation, export/restore, and local-only operation.
|
||||
|
||||
The same core schema should work for fantasy, science fiction, mystery, horror, historical fiction, westerns, and other narrative genres.
|
||||
|
||||
## 2. Core Principles
|
||||
|
||||
### 2.1 Application-owned authority
|
||||
The database is the source of truth. The model may propose narration and state changes, but those proposals become authoritative only after application validation.
|
||||
|
||||
### 2.2 Non-destructive history
|
||||
Accepted turns are historical records. Going backward should move the active story head or create a branch, not silently delete accepted history.
|
||||
|
||||
### 2.3 Historical reconstruction
|
||||
The system must answer both:
|
||||
- What is true now?
|
||||
- What was true at a particular earlier turn on a particular branch?
|
||||
|
||||
### 2.4 Genre neutrality
|
||||
Avoid fantasy- or science-fiction-specific core fields. Use generic concepts such as characters, locations, organizations, items, vehicles, facts, relationships, conditions, scenes, and story threads.
|
||||
|
||||
## 3. Conceptual Entity Map
|
||||
|
||||
```text
|
||||
Campaign
|
||||
├── Branches
|
||||
│ └── Turns
|
||||
│ ├── Prompt Snapshot
|
||||
│ ├── State Version
|
||||
│ ├── Scene Snapshot
|
||||
│ └── Retrieval Records
|
||||
├── Checkpoints
|
||||
├── Narrative Entities
|
||||
├── Facts
|
||||
├── Relationships
|
||||
├── Story Threads
|
||||
├── Memories
|
||||
├── Summaries
|
||||
├── Knowledge Sources
|
||||
│ └── Knowledge Chunks
|
||||
└── Media
|
||||
├── Media Jobs
|
||||
└── Media Assets
|
||||
```
|
||||
|
||||
The exact SQL schema may differ from this conceptual model.
|
||||
|
||||
## 4. Campaign
|
||||
|
||||
A campaign is the top-level story container.
|
||||
|
||||
```yaml
|
||||
campaign:
|
||||
id: uuid
|
||||
title: string
|
||||
created_at: timestamp
|
||||
updated_at: timestamp
|
||||
active_branch_id: uuid
|
||||
status: active | archived
|
||||
|
||||
story_profile:
|
||||
genre: string
|
||||
subgenre: optional string
|
||||
tone: optional string
|
||||
style: optional string
|
||||
point_of_view: optional string
|
||||
tense: optional string
|
||||
```
|
||||
|
||||
Campaigns also store durable narrator rules and model configuration.
|
||||
|
||||
Potential model roles:
|
||||
- narrator,
|
||||
- state extractor,
|
||||
- summarizer,
|
||||
- embedding model.
|
||||
|
||||
For v1, all model roles should use local Ollama-compatible models.
|
||||
|
||||
## 5. Branch
|
||||
|
||||
A branch represents one valid continuation of story history.
|
||||
|
||||
```yaml
|
||||
branch:
|
||||
id: uuid
|
||||
campaign_id: uuid
|
||||
name: string
|
||||
created_at: timestamp
|
||||
created_from_branch_id: optional uuid
|
||||
fork_turn_id: optional uuid
|
||||
head_turn_id: optional uuid
|
||||
status: active | archived
|
||||
```
|
||||
|
||||
Rules:
|
||||
- branches may share ancestral turns,
|
||||
- shared history should not be duplicated unnecessarily,
|
||||
- creating a branch must not modify the source branch.
|
||||
|
||||
Detailed behavior will be defined separately in `STORY-BRANCH-SEMANTICS.md`.
|
||||
|
||||
## 6. Turn
|
||||
|
||||
A turn is one accepted story interaction:
|
||||
|
||||
```text
|
||||
user input -> narrator response -> accepted state transition
|
||||
```
|
||||
|
||||
```yaml
|
||||
turn:
|
||||
id: uuid
|
||||
campaign_id: uuid
|
||||
branch_id: uuid
|
||||
parent_turn_id: optional uuid
|
||||
created_at: timestamp
|
||||
|
||||
input:
|
||||
mode: action | dialogue | direction | continue
|
||||
text: string
|
||||
|
||||
output:
|
||||
narration: string
|
||||
|
||||
generation:
|
||||
provider: ollama
|
||||
model: string
|
||||
generation_settings: object
|
||||
prompt_snapshot_id: uuid
|
||||
|
||||
state_before_id: uuid
|
||||
state_after_id: uuid
|
||||
scene_snapshot_id: optional uuid
|
||||
status: pending | accepted | failed | superseded
|
||||
```
|
||||
|
||||
The root turn has no parent.
|
||||
|
||||
An accepted historical turn should not silently disappear if another continuation is chosen.
|
||||
|
||||
## 7. Alternate Take
|
||||
|
||||
The system may need to distinguish:
|
||||
- a different narrator response to the same user action,
|
||||
- a genuinely different story branch.
|
||||
|
||||
Conceptual form:
|
||||
|
||||
```yaml
|
||||
take:
|
||||
id: uuid
|
||||
turn_request_id: uuid
|
||||
output_text: string
|
||||
model_metadata: object
|
||||
selected: boolean
|
||||
```
|
||||
|
||||
Whether `Take` becomes a separate table or sibling turn nodes will be decided after Phase 0B.
|
||||
|
||||
## 8. Checkpoint
|
||||
|
||||
```yaml
|
||||
checkpoint:
|
||||
id: uuid
|
||||
campaign_id: uuid
|
||||
turn_id: uuid
|
||||
name: string
|
||||
notes: optional string
|
||||
created_at: timestamp
|
||||
```
|
||||
|
||||
A checkpoint is a named pointer to a recoverable story position. It should normally remain tied to the turn where it was created.
|
||||
|
||||
## 9. Narrative Entity
|
||||
|
||||
An entity is a persistent thing or concept in the fictional world.
|
||||
|
||||
```yaml
|
||||
entity:
|
||||
id: uuid
|
||||
campaign_id: uuid
|
||||
type: string
|
||||
name: string
|
||||
aliases: [string]
|
||||
description: string
|
||||
status: active | inactive | destroyed | dead | unknown
|
||||
created_turn_id: optional uuid
|
||||
metadata: object
|
||||
```
|
||||
|
||||
Recommended built-in categories:
|
||||
- character,
|
||||
- location,
|
||||
- organization,
|
||||
- item,
|
||||
- vehicle,
|
||||
- creature,
|
||||
- structure,
|
||||
- concept,
|
||||
- other.
|
||||
|
||||
These are descriptive categories, not separate game systems.
|
||||
|
||||
## 10. Character
|
||||
|
||||
```yaml
|
||||
character:
|
||||
entity_id: uuid
|
||||
role: optional string
|
||||
description: string
|
||||
current_location_id: optional uuid
|
||||
condition: [string]
|
||||
personality_notes: [string]
|
||||
goals: [string]
|
||||
secrets: [string]
|
||||
```
|
||||
|
||||
Optional visual continuity fields:
|
||||
|
||||
```yaml
|
||||
visual_profile:
|
||||
apparent_age: optional string
|
||||
build: optional string
|
||||
hair: optional string
|
||||
eyes: optional string
|
||||
clothing: optional string
|
||||
distinctive_features: [string]
|
||||
continuity_notes: [string]
|
||||
```
|
||||
|
||||
## 11. Location
|
||||
|
||||
```yaml
|
||||
location:
|
||||
entity_id: uuid
|
||||
description: string
|
||||
parent_location_id: optional uuid
|
||||
current_status: optional string
|
||||
|
||||
visual_profile:
|
||||
architecture: optional string
|
||||
environment: optional string
|
||||
lighting: optional string
|
||||
signature_features: [string]
|
||||
continuity_notes: [string]
|
||||
```
|
||||
|
||||
## 12. Organization
|
||||
|
||||
Organizations may represent factions, governments, companies, guilds, military units, religious organizations, or informal groups.
|
||||
|
||||
```yaml
|
||||
organization:
|
||||
entity_id: uuid
|
||||
purpose: optional string
|
||||
current_status: optional string
|
||||
```
|
||||
|
||||
Specific characteristics should usually live in facts and relationships.
|
||||
|
||||
## 13. Items and Vehicles
|
||||
|
||||
Items and vehicles remain generic entities.
|
||||
|
||||
Examples:
|
||||
- silver key,
|
||||
- longsword,
|
||||
- encrypted data crystal,
|
||||
- survey ship,
|
||||
- horse-drawn carriage.
|
||||
|
||||
Possession and location should normally be represented as relationships or facts:
|
||||
|
||||
```text
|
||||
Aldric --possesses--> Silver Key
|
||||
Persephone --docked_at--> Ceres Station
|
||||
```
|
||||
|
||||
## 14. Fact
|
||||
|
||||
Facts represent assertions about the story world.
|
||||
|
||||
```yaml
|
||||
fact:
|
||||
id: uuid
|
||||
campaign_id: uuid
|
||||
subject_entity_id: optional uuid
|
||||
predicate: string
|
||||
object_entity_id: optional uuid
|
||||
value: optional scalar_or_object
|
||||
authority: string
|
||||
source_type: string
|
||||
source_id: optional uuid
|
||||
created_turn_id: optional uuid
|
||||
invalidated_turn_id: optional uuid
|
||||
status: active | superseded | disputed
|
||||
```
|
||||
|
||||
Examples:
|
||||
- Mara knows Aldric has the silver key.
|
||||
- The Persephone cannot travel faster than light.
|
||||
- Edrin disappeared three weeks before the campaign began.
|
||||
- The eastern bridge collapsed during Turn 47.
|
||||
|
||||
Minimum authority categories:
|
||||
- campaign_canon,
|
||||
- accepted_story,
|
||||
- current_state,
|
||||
- imported_canon,
|
||||
- reference,
|
||||
- heuristic,
|
||||
- inspiration.
|
||||
|
||||
Exact context behavior will be defined in `CONTEXT-AND-MEMORY.md`.
|
||||
|
||||
## 15. Relationship
|
||||
|
||||
```yaml
|
||||
relationship:
|
||||
id: uuid
|
||||
campaign_id: uuid
|
||||
source_entity_id: uuid
|
||||
target_entity_id: uuid
|
||||
type: string
|
||||
status: string
|
||||
description: optional string
|
||||
created_turn_id: optional uuid
|
||||
ended_turn_id: optional uuid
|
||||
```
|
||||
|
||||
Examples:
|
||||
- Aldric -> trusts -> Mara
|
||||
- Mara -> member_of -> Circle of Ash
|
||||
- Silver Key -> belongs_to -> Aldric
|
||||
- Persephone -> docked_at -> Ceres Station
|
||||
|
||||
Relationship types should remain extensible.
|
||||
|
||||
## 16. Story Thread
|
||||
|
||||
Story threads track unresolved or resolved narrative business.
|
||||
|
||||
```yaml
|
||||
story_thread:
|
||||
id: uuid
|
||||
campaign_id: uuid
|
||||
title: string
|
||||
description: string
|
||||
status: open | dormant | resolved | abandoned
|
||||
importance: optional number_or_label
|
||||
opened_turn_id: optional uuid
|
||||
resolved_turn_id: optional uuid
|
||||
```
|
||||
|
||||
These are narrative continuity tools, not RPG quests.
|
||||
|
||||
## 17. State Version
|
||||
|
||||
The system must reconstruct authoritative state at any retained turn.
|
||||
|
||||
```yaml
|
||||
state_version:
|
||||
id: uuid
|
||||
campaign_id: uuid
|
||||
turn_id: optional uuid
|
||||
parent_state_version_id: optional uuid
|
||||
created_at: timestamp
|
||||
state_hash: optional string
|
||||
```
|
||||
|
||||
Possible implementation models:
|
||||
|
||||
### A. Full snapshots
|
||||
Simple restore, but duplicates data.
|
||||
|
||||
### B. Event sourcing
|
||||
Excellent auditability, but requires replay.
|
||||
|
||||
### C. Hybrid
|
||||
Validated events plus periodic/current snapshots.
|
||||
|
||||
**Current preference: Hybrid**, pending Phase 0B.
|
||||
|
||||
## 18. State Change Event
|
||||
|
||||
If the hybrid/event model is selected:
|
||||
|
||||
```yaml
|
||||
state_event:
|
||||
id: uuid
|
||||
campaign_id: uuid
|
||||
turn_id: uuid
|
||||
event_type: string
|
||||
payload: object
|
||||
sequence: integer
|
||||
```
|
||||
|
||||
Potential event types:
|
||||
- entity_created,
|
||||
- entity_updated,
|
||||
- fact_added,
|
||||
- fact_invalidated,
|
||||
- relationship_added,
|
||||
- relationship_ended,
|
||||
- thread_opened,
|
||||
- thread_resolved,
|
||||
- location_changed,
|
||||
- possession_changed,
|
||||
- scene_changed.
|
||||
|
||||
Events must be validated before commit.
|
||||
|
||||
## 19. State Proposal
|
||||
|
||||
The model's extracted state proposal must be distinct from accepted state.
|
||||
|
||||
```yaml
|
||||
state_proposal:
|
||||
id: uuid
|
||||
turn_id: uuid
|
||||
model: string
|
||||
raw_output: string
|
||||
parsed_payload: object
|
||||
validation_status: accepted | partially_accepted | rejected | repair_required
|
||||
```
|
||||
|
||||
The model must never write directly to authoritative state tables.
|
||||
|
||||
## 20. Scene Snapshot
|
||||
|
||||
A scene snapshot captures the immediate narrative situation.
|
||||
|
||||
```yaml
|
||||
scene:
|
||||
id: uuid
|
||||
campaign_id: uuid
|
||||
branch_id: uuid
|
||||
source_turn_start_id: optional uuid
|
||||
source_turn_end_id: optional uuid
|
||||
location_id: optional uuid
|
||||
time_description: optional string
|
||||
mood: optional string
|
||||
environment: optional string
|
||||
participants: [uuid]
|
||||
significant_objects: [uuid]
|
||||
current_actions: [string]
|
||||
visual_notes: [string]
|
||||
continuity_notes: [string]
|
||||
```
|
||||
|
||||
Scene snapshots support:
|
||||
- current context,
|
||||
- narrative continuity,
|
||||
- future image generation,
|
||||
- future multi-turn video/storyboard generation.
|
||||
|
||||
## 21. Summary
|
||||
|
||||
Summaries compress history but never replace authoritative history.
|
||||
|
||||
```yaml
|
||||
summary:
|
||||
id: uuid
|
||||
campaign_id: uuid
|
||||
branch_id: uuid
|
||||
type: campaign | arc | rolling | turn_range
|
||||
source_start_turn_id: uuid
|
||||
source_end_turn_id: uuid
|
||||
text: string
|
||||
created_at: timestamp
|
||||
model: optional string
|
||||
```
|
||||
|
||||
Summaries are derived data. Branch changes must invalidate or lineage-filter incompatible summaries.
|
||||
|
||||
## 22. Memory
|
||||
|
||||
```yaml
|
||||
memory:
|
||||
id: uuid
|
||||
campaign_id: uuid
|
||||
branch_scope: optional uuid
|
||||
source_turn_id: optional uuid
|
||||
type: string
|
||||
text: string
|
||||
authority: string
|
||||
importance: optional number
|
||||
embedding_ref: optional string
|
||||
created_at: timestamp
|
||||
```
|
||||
|
||||
Potential types:
|
||||
- event,
|
||||
- character,
|
||||
- relationship,
|
||||
- location,
|
||||
- promise,
|
||||
- discovery,
|
||||
- conflict,
|
||||
- heuristic.
|
||||
|
||||
A retrieved memory does not automatically become canon.
|
||||
|
||||
## 23. Knowledge Source
|
||||
|
||||
A knowledge source is a user-imported local file or manually authored campaign document.
|
||||
|
||||
```yaml
|
||||
knowledge_source:
|
||||
id: uuid
|
||||
campaign_id: optional uuid
|
||||
title: string
|
||||
source_type: file | manual
|
||||
classification: canon | reference | inspiration
|
||||
original_filename: optional string
|
||||
content_hash: string
|
||||
enabled: boolean
|
||||
imported_at: timestamp
|
||||
metadata: object
|
||||
```
|
||||
|
||||
Initial supported file types should be `.txt` and `.md`.
|
||||
|
||||
## 24. Knowledge Chunk
|
||||
|
||||
```yaml
|
||||
knowledge_chunk:
|
||||
id: uuid
|
||||
source_id: uuid
|
||||
sequence: integer
|
||||
text: string
|
||||
heading_path: optional string
|
||||
token_count: optional integer
|
||||
embedding_ref: optional string
|
||||
metadata: object
|
||||
```
|
||||
|
||||
Requirements:
|
||||
- preserve provenance,
|
||||
- preserve chunk order,
|
||||
- permit re-indexing,
|
||||
- never execute imported content.
|
||||
|
||||
## 25. Retrieval Record
|
||||
|
||||
Every turn should record which memories or knowledge chunks were supplied to the narrator.
|
||||
|
||||
```yaml
|
||||
retrieval_record:
|
||||
id: uuid
|
||||
turn_id: uuid
|
||||
source_kind: memory | knowledge | summary | fact
|
||||
source_id: uuid
|
||||
retrieval_method: lexical | semantic | hybrid | forced
|
||||
score: optional number
|
||||
rank: integer
|
||||
```
|
||||
|
||||
This lets the prompt inspector answer:
|
||||
|
||||
> Why did the narrator know this?
|
||||
|
||||
## 26. Prompt Snapshot
|
||||
|
||||
```yaml
|
||||
prompt_snapshot:
|
||||
id: uuid
|
||||
turn_id: uuid
|
||||
created_at: timestamp
|
||||
system_instructions: text
|
||||
campaign_context: text_or_structured
|
||||
state_context: text_or_structured
|
||||
summary_context: text_or_structured
|
||||
memory_context: text_or_structured
|
||||
knowledge_context: text_or_structured
|
||||
recent_history: text_or_structured
|
||||
user_input: text
|
||||
token_accounting: object
|
||||
```
|
||||
|
||||
The physical representation may be compressed or normalized. Reproducibility and inspection are the requirements.
|
||||
|
||||
## 27. Media Job
|
||||
|
||||
Not required for v1 behavior, but the data model should not prevent it.
|
||||
|
||||
```yaml
|
||||
media_job:
|
||||
id: uuid
|
||||
campaign_id: uuid
|
||||
scene_id: optional uuid
|
||||
source_turn_start_id: optional uuid
|
||||
source_turn_end_id: optional uuid
|
||||
type: image | video | audio
|
||||
provider: string
|
||||
model: string
|
||||
status: queued | running | completed | failed
|
||||
request_payload: object
|
||||
created_at: timestamp
|
||||
completed_at: optional timestamp
|
||||
```
|
||||
|
||||
## 28. Media Asset
|
||||
|
||||
```yaml
|
||||
media_asset:
|
||||
id: uuid
|
||||
campaign_id: uuid
|
||||
media_job_id: optional uuid
|
||||
scene_id: optional uuid
|
||||
type: image | video | audio
|
||||
file_path: string
|
||||
metadata: object
|
||||
created_at: timestamp
|
||||
```
|
||||
|
||||
Potential metadata includes prompt, seed, model, workflow, dimensions, duration, character references, and source turn range.
|
||||
|
||||
## 29. Export Package
|
||||
|
||||
A campaign export should be capable of preserving:
|
||||
|
||||
- campaign configuration,
|
||||
- branches,
|
||||
- turn graph,
|
||||
- checkpoints,
|
||||
- state/events,
|
||||
- entities,
|
||||
- facts,
|
||||
- relationships,
|
||||
- story threads,
|
||||
- summaries,
|
||||
- memories,
|
||||
- scene snapshots,
|
||||
- knowledge-source metadata,
|
||||
- knowledge chunks/source files if selected,
|
||||
- prompt provenance if selected,
|
||||
- media metadata,
|
||||
- media files if selected.
|
||||
|
||||
Exact format remains open. A ZIP containing a database plus manifest is a strong candidate.
|
||||
|
||||
## 30. Deletion vs Archival
|
||||
|
||||
The system must distinguish:
|
||||
- archive,
|
||||
- detach/disable,
|
||||
- permanent delete.
|
||||
|
||||
Retry, Undo, Restore, and branch switching must not silently perform permanent deletion.
|
||||
|
||||
## 31. Authoritative vs Derived Data
|
||||
|
||||
### Authoritative
|
||||
- accepted turns,
|
||||
- branch lineage,
|
||||
- campaign configuration,
|
||||
- accepted facts,
|
||||
- accepted relationships,
|
||||
- accepted state events,
|
||||
- checkpoints.
|
||||
|
||||
### Derived
|
||||
- summaries,
|
||||
- embeddings,
|
||||
- semantic indexes,
|
||||
- lexical indexes,
|
||||
- some automatically produced scene descriptions.
|
||||
|
||||
Derived data should be rebuildable where practical.
|
||||
|
||||
## 32. Provenance
|
||||
|
||||
Important information should answer:
|
||||
|
||||
> Where did this come from?
|
||||
|
||||
Potential provenance:
|
||||
- campaign setup,
|
||||
- manual user edit,
|
||||
- accepted narrator turn,
|
||||
- state extraction,
|
||||
- imported canon,
|
||||
- imported reference,
|
||||
- imported inspiration,
|
||||
- derived inference.
|
||||
|
||||
## 33. Open Questions for Phase 0B
|
||||
|
||||
1. Does AI-DnD already model alternate takes separately from branch nodes in a reusable way?
|
||||
2. Can its state snapshots hold generic narrative JSON without major redesign?
|
||||
3. Is its branch lineage compatible with immutable turns?
|
||||
4. Should checkpoints be branch-independent pointers to turns?
|
||||
5. Should memories be physically branch-scoped or lineage-filtered at query time?
|
||||
6. Should knowledge sources be reusable across campaigns in v1?
|
||||
7. Should media tables physically exist in v1 or only interfaces/types?
|
||||
8. How should manual edits to canon/state be versioned?
|
||||
9. Which state needs full historical reconstruction versus only current-state storage?
|
||||
10. Can ai-adventure's event/replay discipline be adopted without overcomplicating AI-DnD?
|
||||
|
||||
## 34. Acceptance Criteria
|
||||
|
||||
The final v1 data model must support all of these without destructive hacks:
|
||||
|
||||
- close/restart/resume exact story,
|
||||
- branch from an earlier turn while retaining the original future,
|
||||
- create and restore named checkpoints,
|
||||
- know current characters/locations/relationships/story threads,
|
||||
- reconstruct earlier authoritative state,
|
||||
- retrieve old events outside the active context window,
|
||||
- identify which imported passages informed a turn,
|
||||
- reconstruct what was sent to Ollama,
|
||||
- run fantasy and science-fiction campaigns without schema changes,
|
||||
- attach future image/video assets to scenes or turn ranges.
|
||||
|
||||
## 35. Current Recommendation
|
||||
|
||||
The target conceptual model should be:
|
||||
|
||||
```text
|
||||
Immutable Turn Graph
|
||||
|
|
||||
+--> validated state events
|
||||
|
|
||||
+--> state snapshot/cache
|
||||
|
|
||||
+--> scene snapshot
|
||||
|
|
||||
+--> prompt/retrieval provenance
|
||||
```
|
||||
|
||||
This combines the strongest observed concepts from:
|
||||
|
||||
- AI-DnD's story tree and snapshots,
|
||||
- ai-adventure's append-only event/replay discipline,
|
||||
- Open Dungeon's simple story UX and visual continuity.
|
||||
|
||||
The physical implementation remains provisional until Phase 0B validates the preferred production base.
|
||||
@@ -0,0 +1,36 @@
|
||||
# ADR 001 — Browser-First User Interface
|
||||
|
||||
**Status:** Accepted
|
||||
|
||||
## Decision
|
||||
|
||||
The primary user interface will be browser-based.
|
||||
|
||||
## Context
|
||||
|
||||
The application must support persistent interactive storytelling, campaign management, branch/checkpoint navigation, state inspection, imported knowledge management, and future images/video. These requirements are substantially better suited to a graphical browser interface than a terminal-only interface.
|
||||
|
||||
## Alternatives Considered
|
||||
|
||||
- terminal-only UI,
|
||||
- Open WebUI as the primary product UI,
|
||||
- native desktop application,
|
||||
- browser-based application.
|
||||
|
||||
## Reason
|
||||
|
||||
A browser interface provides the best path for:
|
||||
|
||||
- transcript interaction,
|
||||
- story-tree visualization,
|
||||
- state/library panels,
|
||||
- streaming text,
|
||||
- local deployment,
|
||||
- future generated graphics/video,
|
||||
- cross-platform use without separate native clients.
|
||||
|
||||
## Consequences
|
||||
|
||||
- terminal-first candidate projects will require a browser layer if selected,
|
||||
- runtime browser dependencies must remain local/offline-capable,
|
||||
- remote CDN assets should not be required in production.
|
||||
@@ -0,0 +1,29 @@
|
||||
# ADR 002 — Ollama Is the v1 Model Backend
|
||||
|
||||
**Status:** Accepted
|
||||
|
||||
## Decision
|
||||
|
||||
v1 will target local Ollama inference.
|
||||
|
||||
## Context
|
||||
|
||||
The intended deployment already has a local Ollama inference engine. The project prioritizes local control, privacy, and predictable integration.
|
||||
|
||||
## Alternatives Considered
|
||||
|
||||
- multiple cloud providers,
|
||||
- LM Studio,
|
||||
- llama.cpp direct integration,
|
||||
- arbitrary OpenAI-compatible endpoints,
|
||||
- Ollama.
|
||||
|
||||
## Reason
|
||||
|
||||
Ollama is already available locally, provides a simple local API, supports both text-generation and embedding models, and avoids requiring external inference services.
|
||||
|
||||
## Consequences
|
||||
|
||||
- candidate forks supporting multiple cloud providers should be simplified or hardened,
|
||||
- candidate projects using another local API need an adapter,
|
||||
- future backend abstraction may be added, but v1 should not be delayed to support it.
|
||||
@@ -0,0 +1,36 @@
|
||||
# ADR 003 — Application-Owned Authoritative State
|
||||
|
||||
**Status:** Accepted
|
||||
|
||||
## Decision
|
||||
|
||||
The application, not the language model, will own authoritative story history and state.
|
||||
|
||||
## Context
|
||||
|
||||
Language models do not reliably preserve long-term continuity and should not be trusted as the sole record of facts, branches, checkpoints, or campaign history.
|
||||
|
||||
## Alternatives Considered
|
||||
|
||||
- rely on chat transcript/model context,
|
||||
- rely on rolling summaries only,
|
||||
- application-owned structured state plus immutable history.
|
||||
|
||||
## Reason
|
||||
|
||||
Application-owned state enables:
|
||||
|
||||
- persistence,
|
||||
- rollback,
|
||||
- branching,
|
||||
- continuity,
|
||||
- inspection,
|
||||
- export,
|
||||
- deterministic recovery,
|
||||
- debugging.
|
||||
|
||||
## Consequences
|
||||
|
||||
- model outputs that imply state changes should be treated as proposals,
|
||||
- state updates require validation,
|
||||
- the database must remain authoritative even if the model contradicts it.
|
||||
@@ -0,0 +1,35 @@
|
||||
# ADR 004 — Local-Only Production Default
|
||||
|
||||
**Status:** Accepted
|
||||
|
||||
## Decision
|
||||
|
||||
The production application will be designed to operate without Internet access.
|
||||
|
||||
## Context
|
||||
|
||||
The project requires control over story data, imported material, prompts, and model outputs, with no unintended disclosure to outside services.
|
||||
|
||||
## Alternatives Considered
|
||||
|
||||
- hybrid local/cloud,
|
||||
- optional cloud providers enabled by default,
|
||||
- local-only default with future explicitly enabled extensions.
|
||||
|
||||
## Reason
|
||||
|
||||
Local-only operation best matches the privacy and control requirements.
|
||||
|
||||
## Consequences
|
||||
|
||||
The production application should avoid:
|
||||
|
||||
- telemetry,
|
||||
- analytics,
|
||||
- cloud inference,
|
||||
- remote vector stores,
|
||||
- automatic web retrieval,
|
||||
- runtime CDN dependencies,
|
||||
- remote fonts/assets.
|
||||
|
||||
All inherited network behavior from a fork must be inventoried during Phase 0.
|
||||
@@ -0,0 +1,29 @@
|
||||
# ADR 005 — Branch-Preserving Story History
|
||||
|
||||
**Status:** Accepted in principle; implementation pending Phase 0
|
||||
|
||||
## Decision
|
||||
|
||||
Returning to an earlier story point should preserve abandoned future history as another branch rather than destructively erasing it.
|
||||
|
||||
## Context
|
||||
|
||||
The user must be able to recover from unwanted story developments and explore alternatives while retaining prior work.
|
||||
|
||||
## Alternatives Considered
|
||||
|
||||
- destructive undo,
|
||||
- overwrite-in-place editing,
|
||||
- complete copy of campaigns for every retry,
|
||||
- branch-preserving turn graph.
|
||||
|
||||
## Reason
|
||||
|
||||
A branch-preserving history provides recovery, experimentation, and auditability without unnecessary campaign duplication.
|
||||
|
||||
## Consequences
|
||||
|
||||
- turn identity/parentage must be first-class,
|
||||
- state restore must be branch-aware,
|
||||
- retry/edit semantics must be explicitly defined,
|
||||
- the selected candidate repository must either support this or be adaptable to it.
|
||||
@@ -0,0 +1,27 @@
|
||||
# ADR 006 — Genre-Agnostic Core
|
||||
|
||||
**Status:** Accepted
|
||||
|
||||
## Decision
|
||||
|
||||
Core data structures and workflows will not hard-code fantasy or science-fiction concepts.
|
||||
|
||||
## Context
|
||||
|
||||
The same application should support swords-and-sorcery, hard science fiction, space opera, mystery, and other interactive-fiction genres.
|
||||
|
||||
## Alternatives Considered
|
||||
|
||||
- fantasy-specific schema,
|
||||
- separate engine per genre,
|
||||
- generic story engine with campaign profiles.
|
||||
|
||||
## Reason
|
||||
|
||||
The underlying requirements—characters, locations, relationships, history, facts, scenes, memory, and branches—are common across genres.
|
||||
|
||||
## Consequences
|
||||
|
||||
- genre-specific rules belong in profiles/configuration/canon,
|
||||
- avoid schema columns such as `spell`, `sword`, `spaceship`, etc.,
|
||||
- use generic concepts such as entities, items, vehicles, locations, organizations, and facts.
|
||||
@@ -0,0 +1,33 @@
|
||||
# ADR 007 — Preserve Future Image and Video Extension Points
|
||||
|
||||
**Status:** Accepted
|
||||
|
||||
## Decision
|
||||
|
||||
v1 will not require media generation, but the story/state model will preserve scene and visual metadata so local image/video generation can be added later.
|
||||
|
||||
## Context
|
||||
|
||||
Future desired experiences include:
|
||||
|
||||
- generating an image when entering a location,
|
||||
- generating character portraits,
|
||||
- generating illustrations from important scenes,
|
||||
- generating video recaps from multi-turn action sequences.
|
||||
|
||||
## Alternatives Considered
|
||||
|
||||
- defer all media concerns until later,
|
||||
- integrate image/video immediately,
|
||||
- reserve scene/asset abstractions now without implementing providers.
|
||||
|
||||
## Reason
|
||||
|
||||
Scene and character continuity information is inexpensive to preserve now and expensive to reconstruct later.
|
||||
|
||||
## Consequences
|
||||
|
||||
- scene snapshots should be part of the v1 data model,
|
||||
- characters/locations should allow visual descriptors,
|
||||
- asset/media tables or interfaces may be reserved,
|
||||
- the story engine must not depend on a specific image/video backend.
|
||||
@@ -0,0 +1,27 @@
|
||||
# ADR 008 — Complete Phase 0 Before Detailed Build Planning
|
||||
|
||||
**Status:** Accepted
|
||||
|
||||
## Decision
|
||||
|
||||
The project will complete repository research, validation, architecture selection, and critical prototypes before writing the detailed production implementation milestone plan.
|
||||
|
||||
## Context
|
||||
|
||||
Multiple candidate open-source projects already implement overlapping parts of the desired system. The correct build sequence depends heavily on which codebase is selected.
|
||||
|
||||
## Alternatives Considered
|
||||
|
||||
- write full implementation plan immediately,
|
||||
- begin coding against the first plausible project,
|
||||
- perform a bounded Phase 0 and then finalize the build plan.
|
||||
|
||||
## Reason
|
||||
|
||||
The third approach reduces speculative planning and prevents large amounts of rework.
|
||||
|
||||
## Consequences
|
||||
|
||||
- `BUILD-MILESTONES.md` remains intentionally high level during Phase 0,
|
||||
- production coding should not begin unless explicitly authorized,
|
||||
- Phase 0 ends with the final build plan.
|
||||
File diff suppressed because it is too large
Load Diff
File diff suppressed because it is too large
Load Diff
@@ -0,0 +1,272 @@
|
||||
# Phase 0B — Codex Initial Validation Brief
|
||||
|
||||
**Status:** Ready for execution
|
||||
**Purpose:** Run a focused first round of local validation on the three finalist repositories and return a recommendation based on what was actually learned.
|
||||
|
||||
## 1. Goal
|
||||
|
||||
We are **not** asking you to build the production application yet.
|
||||
|
||||
The goal of this round is to answer one question:
|
||||
|
||||
> Which existing project is the best starting point for the local interactive-story application, and what important technical facts did we learn that should affect the next design step?
|
||||
|
||||
The three finalists are:
|
||||
|
||||
1. AI-DnD
|
||||
https://github.com/parththakkar106/AI-DnD
|
||||
|
||||
2. Open Dungeon
|
||||
https://github.com/newideas99/open-dungeon
|
||||
|
||||
3. ai-adventure
|
||||
https://github.com/CaoRuiming/ai-adventure
|
||||
|
||||
## 2. Important Product Requirements
|
||||
|
||||
Use these as the main evaluation criteria.
|
||||
|
||||
The eventual application should be:
|
||||
|
||||
- browser-first,
|
||||
- local-only in v1,
|
||||
- based on local Ollama inference,
|
||||
- single-user,
|
||||
- genre-agnostic,
|
||||
- persistent across restarts,
|
||||
- able to retain authoritative story state separately from model prose,
|
||||
- able to Undo/Redo/Retry safely,
|
||||
- able to preserve named save points/checkpoints,
|
||||
- able to retain abandoned history without immediately deleting it,
|
||||
- able to prevent abandoned-history facts/memories from leaking into the active story,
|
||||
- able to support long-term context/memory,
|
||||
- able to import local knowledge,
|
||||
- able to inspect what context was sent to the model,
|
||||
- architecturally compatible with future local image/video/TTS/STT support.
|
||||
|
||||
Do not try to implement all of these now.
|
||||
|
||||
This round is about determining which candidate already gives us the strongest foundation.
|
||||
|
||||
## 3. Read Only What You Need
|
||||
|
||||
Start with:
|
||||
|
||||
1. `README.md`
|
||||
2. `SPECIFICATION.md`
|
||||
3. `reports/PRELIMINARY-RECOMMENDATION.md`
|
||||
4. `reports/REUSE-MATRIX.md`
|
||||
|
||||
Then use these only when relevant to a specific experiment:
|
||||
|
||||
- `STORY-BRANCH-SEMANTICS.md`
|
||||
- `CONTEXT-AND-MEMORY.md`
|
||||
- `SECURITY-THREAT-MODEL.md`
|
||||
- `TEST-CAMPAIGN-FIXTURE.md`
|
||||
|
||||
Do **not** read every planning document up front unless needed.
|
||||
|
||||
## 4. Baseline Work for Each Candidate
|
||||
|
||||
For each repository:
|
||||
|
||||
1. Clone it cleanly.
|
||||
2. Record the exact commit SHA.
|
||||
3. Follow the documented install instructions.
|
||||
4. Run the existing tests.
|
||||
5. Build/start the application.
|
||||
6. Confirm the basic local story flow.
|
||||
7. Record:
|
||||
- test results,
|
||||
- storage/database technology,
|
||||
- model/provider assumptions,
|
||||
- local ports,
|
||||
- major runtime failures,
|
||||
- obvious cloud/hosted dependencies.
|
||||
|
||||
Do not spend excessive time fixing unrelated upstream problems.
|
||||
|
||||
If a project does not run cleanly, document why and continue.
|
||||
|
||||
## 5. Focused Experiment A — AI-DnD
|
||||
|
||||
We want to know whether AI-DnD can realistically serve as the production base.
|
||||
|
||||
Test:
|
||||
|
||||
- Can it run with Ollama locally?
|
||||
- Can its story-tree/history system support simple user-facing Undo/Redo/Retry behavior?
|
||||
- Does state rollback work independently of heavy RPG/stat mechanics?
|
||||
- Can RPG-specific state be left empty/minimal without breaking the useful history/state architecture?
|
||||
- Can QuickJS/scripting and hosted/cloud-oriented features be disabled without breaking local story operation?
|
||||
- Can local memory/embedding behavior work without cloud services?
|
||||
- Do memories/state respect the active history path?
|
||||
- Is its context/Insights system useful for showing what was sent to the model?
|
||||
|
||||
Use a small disposable experiment if necessary.
|
||||
|
||||
Do **not** start stripping the whole application down.
|
||||
|
||||
## 6. Focused Experiment B — Open Dungeon
|
||||
|
||||
We want to know how expensive it would be to fix its history model.
|
||||
|
||||
Test:
|
||||
|
||||
- Confirm how Retry/Edit/Erase affect stored history.
|
||||
- Identify whether old future turns are deleted.
|
||||
- Trace which parts of the application depend on that linear/destructive behavior.
|
||||
- Estimate how invasive it would be to change to:
|
||||
- parent-linked turns,
|
||||
- active head,
|
||||
- retained abandoned history,
|
||||
- named checkpoints,
|
||||
- lineage-safe summaries/state.
|
||||
|
||||
Do not implement the complete branch system.
|
||||
|
||||
Also record useful existing pieces:
|
||||
- browser UX,
|
||||
- local image generation,
|
||||
- character visual continuity,
|
||||
- any scene/media architecture worth reusing.
|
||||
|
||||
## 7. Focused Experiment C — ai-adventure
|
||||
|
||||
We want to know whether its strong state/privacy architecture can realistically become a browser-based Ollama application.
|
||||
|
||||
Test:
|
||||
|
||||
- Run the existing tests.
|
||||
- Confirm Undo/branch/checkpoint/replay behavior.
|
||||
- Identify the provider abstraction.
|
||||
- Prove one local Ollama-backed story turn using the smallest practical adapter.
|
||||
- Determine how tightly the core application logic is coupled to the CLI.
|
||||
- Assess whether the core could sit behind a browser/API layer without moving authoritative state logic.
|
||||
- Review its local lore/FTS approach for possible reuse.
|
||||
|
||||
Do not build a browser frontend.
|
||||
|
||||
## 8. Offline / Privacy Check
|
||||
|
||||
For each candidate, once dependencies/models are installed:
|
||||
|
||||
- run it with outbound Internet unavailable or blocked where practical,
|
||||
- exercise basic story generation,
|
||||
- note any unexpected network attempts.
|
||||
|
||||
We do not need a full penetration test in this round.
|
||||
|
||||
We do need to know:
|
||||
|
||||
- whether local story use truly works offline,
|
||||
- whether cloud services are required,
|
||||
- whether analytics/telemetry/remote assets are present,
|
||||
- how difficult those paths would be to remove.
|
||||
|
||||
## 9. Use the Standard Fixture Selectively
|
||||
|
||||
Use `TEST-CAMPAIGN-FIXTURE.md` where it helps answer continuity questions.
|
||||
|
||||
You do not need to execute the entire fixture against every candidate.
|
||||
|
||||
The most important checks are:
|
||||
|
||||
- possession/state consistency,
|
||||
- restore/undo behavior,
|
||||
- abandoned-path isolation,
|
||||
- whether an old discarded fact can leak into current memory/context.
|
||||
|
||||
## 10. What Not to Do
|
||||
|
||||
Do not:
|
||||
|
||||
- build the production fork,
|
||||
- merge repositories,
|
||||
- redesign the full UI,
|
||||
- implement full RAG,
|
||||
- implement complete branching in Open Dungeon,
|
||||
- remove all RPG code from AI-DnD,
|
||||
- build a browser frontend for ai-adventure,
|
||||
- add image/video/TTS/STT features,
|
||||
- write the final production milestone plan.
|
||||
|
||||
Small disposable code changes are allowed only when needed to answer the evaluation questions.
|
||||
|
||||
## 11. Final Deliverable
|
||||
|
||||
The main output from this round should be a single recommendation document:
|
||||
|
||||
```text
|
||||
PHASE-0B-RECOMMENDATION.md
|
||||
```
|
||||
|
||||
It should summarize what was learned, not just list test logs.
|
||||
|
||||
Include:
|
||||
|
||||
### A. Executive Recommendation
|
||||
|
||||
- Which repository should be the production base?
|
||||
- Confidence level: high / medium / low.
|
||||
- Did the initial AI-DnD recommendation hold up?
|
||||
|
||||
### B. What We Learned About Each Candidate
|
||||
|
||||
For each:
|
||||
- what worked,
|
||||
- what failed,
|
||||
- strongest reusable pieces,
|
||||
- major architectural problems,
|
||||
- likely amount/type of adaptation required.
|
||||
|
||||
### C. Key Technical Findings
|
||||
|
||||
Especially:
|
||||
- history/undo model,
|
||||
- state rollback,
|
||||
- memory isolation,
|
||||
- local Ollama support,
|
||||
- offline/privacy behavior,
|
||||
- browser suitability,
|
||||
- imported-knowledge potential,
|
||||
- future media extension potential.
|
||||
|
||||
### D. Important Surprises
|
||||
|
||||
Anything that contradicts the current planning assumptions.
|
||||
|
||||
### E. Recommendation for Next Step
|
||||
|
||||
Do **not** perform the next step.
|
||||
|
||||
Instead recommend what should happen next, such as:
|
||||
- fork AI-DnD and begin a controlled strip-down,
|
||||
- perform one additional experiment first,
|
||||
- reconsider Open Dungeon,
|
||||
- use ai-adventure as the base instead,
|
||||
- revise one of the product assumptions.
|
||||
|
||||
### F. Open Questions
|
||||
|
||||
List anything that could not be resolved in this round.
|
||||
|
||||
## 12. Supporting Evidence
|
||||
|
||||
You may also create concise supporting notes/logs for:
|
||||
|
||||
- baseline results,
|
||||
- AI-DnD experiment,
|
||||
- Open Dungeon history analysis,
|
||||
- ai-adventure Ollama adapter,
|
||||
- offline/network observations.
|
||||
|
||||
Keep them concise.
|
||||
|
||||
The recommendation document is the primary deliverable.
|
||||
|
||||
## 13. Stop Condition
|
||||
|
||||
When `PHASE-0B-RECOMMENDATION.md` is complete, stop.
|
||||
|
||||
We will take the findings back into the design discussion, re-examine the assumptions, and decide the next step before any production implementation begins.
|
||||
@@ -0,0 +1,277 @@
|
||||
# Phase 0B — Codex Local Validation Handoff
|
||||
|
||||
**Status:** Ready for execution
|
||||
**Purpose:** Validate the Phase 0A recommendation using local builds, tests, offline runtime observation, and tightly scoped experiments.
|
||||
**Stop rule:** Do not begin production implementation.
|
||||
|
||||
## 1. Read Before Starting
|
||||
|
||||
Read the package in the order listed in `README.md`.
|
||||
|
||||
At minimum, before modifying any finalist, read:
|
||||
|
||||
1. `SPECIFICATION.md`
|
||||
2. `DATA-MODEL.md`
|
||||
3. `STORY-BRANCH-SEMANTICS.md`
|
||||
4. `CONTEXT-AND-MEMORY.md`
|
||||
5. `IMPORTED-KNOWLEDGE-DESIGN.md`
|
||||
6. `SECURITY-THREAT-MODEL.md`
|
||||
7. `MEDIA-EXTENSION-CONTRACT.md`
|
||||
8. `BROWSER-UX-SPEC.md`
|
||||
9. `TEST-CAMPAIGN-FIXTURE.md`
|
||||
10. `V1-ACCEPTANCE-TESTS.md`
|
||||
11. `reports/PRELIMINARY-RECOMMENDATION.md`
|
||||
12. `reports/REUSE-MATRIX.md`
|
||||
|
||||
Treat the detailed behavioral documents and acceptance tests as the target behavior. Treat `TECHNICAL-DESIGN.md` as provisional.
|
||||
|
||||
## 2. Finalists to Clone
|
||||
|
||||
Clone only these three primary finalists for Phase 0B:
|
||||
|
||||
1. https://github.com/parththakkar106/AI-DnD
|
||||
2. https://github.com/newideas99/open-dungeon
|
||||
3. https://github.com/CaoRuiming/ai-adventure
|
||||
|
||||
At clone time record exact commit SHA, branch/tag, date, license, dependency lockfiles, required runtimes, and documented local model/provider assumptions.
|
||||
|
||||
Keep each upstream clone clean. Use separate experiment branches/worktrees for disposable changes. Do not merge candidate repositories together.
|
||||
|
||||
## 3. Result Codes
|
||||
|
||||
Use consistently:
|
||||
|
||||
```text
|
||||
PASS
|
||||
PARTIAL
|
||||
FAIL
|
||||
NOT IMPLEMENTED
|
||||
NOT APPLICABLE
|
||||
```
|
||||
|
||||
Do not convert an untested requirement into a PASS.
|
||||
|
||||
## 4. Validation V0 — Environment and Baseline
|
||||
|
||||
For all three:
|
||||
|
||||
- install from documented instructions,
|
||||
- run existing test suite,
|
||||
- run build/lint/typecheck where applicable,
|
||||
- record failures,
|
||||
- record actual current test count,
|
||||
- record local data paths,
|
||||
- record listening ports,
|
||||
- record child processes/services,
|
||||
- record model/provider configuration,
|
||||
- record database/storage technology.
|
||||
|
||||
Deliver one baseline report per project. Do not rely on README claims for test counts or feature behavior.
|
||||
|
||||
## 5. Validation V1 — Offline and Network Behavior
|
||||
|
||||
After dependencies and local models are already installed, block outbound Internet and exercise launch, story creation, 5+ turns, restart/resume, summaries, memory/embeddings if present, Retry, Undo/rewind, checkpoint/branch features if present, `.txt`/`.md` import if present, and Open Dungeon local image generation if configured.
|
||||
|
||||
Capture open sockets, DNS attempts, HTTP(S)/WebSocket destinations, and which feature caused each request.
|
||||
|
||||
Use `SECURITY-THREAT-MODEL.md` and acceptance groups A, G, and H.
|
||||
|
||||
Pass condition for target v1 operation:
|
||||
|
||||
> Story content, imported knowledge, prompt/context data, and media prompts do not leave loopback or explicitly approved local endpoints.
|
||||
|
||||
## 6. Standard Fixture Use
|
||||
|
||||
Use `TEST-CAMPAIGN-FIXTURE.md` as the standard narrative test bed.
|
||||
|
||||
Where a finalist cannot represent the fixture directly, map it as closely as possible, document the mismatch, and do not silently change expected truth/state to suit the candidate.
|
||||
|
||||
Important checks:
|
||||
|
||||
- Mara's knowledge boundaries,
|
||||
- Silver Key ownership,
|
||||
- resurrection canon,
|
||||
- Canon vs Reference vs Inspiration authority,
|
||||
- Path A secret followed by restore/divergence into Path B,
|
||||
- abandoned-history memory isolation,
|
||||
- long-term memory plant,
|
||||
- checkpoint persistence,
|
||||
- science-fiction variant.
|
||||
|
||||
## 7. Acceptance-Test Mapping
|
||||
|
||||
Use `V1-ACCEPTANCE-TESTS.md` as the common comparison contract. Produce a gap matrix rather than forcing each candidate to fully pass v1.
|
||||
|
||||
Use these interpretations:
|
||||
|
||||
```text
|
||||
Already passes
|
||||
Passes with configuration
|
||||
Small adaptation
|
||||
Foundational redesign
|
||||
Not present
|
||||
```
|
||||
|
||||
Prioritize high-risk groups:
|
||||
|
||||
- A01-A05 — local operation/persistence
|
||||
- C01-C05 — canon/state
|
||||
- D01-D14 — Undo/Redo/Retry/checkpoints
|
||||
- E01-E04 — lineage safety
|
||||
- F01-F08 — memory/context
|
||||
- G01-G10 — imported knowledge where supported
|
||||
- H01-H10 — security/privacy
|
||||
- J01-J03 — genre independence
|
||||
- K01-K04 — media readiness
|
||||
- L01-L04 — data integrity
|
||||
|
||||
Long-run M01-M04 need not be fully executed against every candidate if disproportionate; identify production risk and existing test coverage instead.
|
||||
|
||||
## 8. Experiment V2 — AI-DnD Strip-Down Feasibility
|
||||
|
||||
Do not redesign the application.
|
||||
|
||||
Answer:
|
||||
|
||||
1. Can a scenario run with RPG stats absent, empty, or minimal?
|
||||
2. Do branch/retry/undo/tree tests operate independently of RPG mechanics?
|
||||
3. Can user-facing tree complexity be hidden behind `STORY-BRANCH-SEMANTICS.md`?
|
||||
4. Disable QuickJS scripting. What breaks?
|
||||
5. Disable/remove hosted multi-user/auth/demo/analytics paths. What breaks locally?
|
||||
6. Configure only local Ollama generation.
|
||||
7. Configure only local embeddings, preferably Ollama/local.
|
||||
8. Verify branch switching restores correct generic state.
|
||||
9. Verify memory retrieval respects active lineage.
|
||||
10. Test whether abandoned Path A facts leak into Path B.
|
||||
11. Map Story Cards/world-info to Canon / Reference / Inspiration.
|
||||
12. Determine whether prompt/context snapshots satisfy Context Inspector requirements.
|
||||
13. Determine whether visual/scene snapshot data can be added without RPG coupling.
|
||||
14. Inventory code coupled to RPG worldstate, scripting, hosted auth, analytics, remote providers, and AI Dungeon compatibility.
|
||||
|
||||
Estimate invasiveness by affected files/modules, not hours. Do not merge the experiment.
|
||||
|
||||
## 9. Experiment V3 — Open Dungeon Branch Retrofit Impact
|
||||
|
||||
Do not implement full branching.
|
||||
|
||||
Trace message CRUD, Retry, Erase, Edit, Continue, summary generation, state/character persistence, image association, and visual continuity. Confirm destructive-tail assumptions.
|
||||
|
||||
Design a minimal hypothetical persistence change supporting:
|
||||
|
||||
```text
|
||||
turn/node ID
|
||||
parent turn ID
|
||||
active head
|
||||
alternate narrator takes
|
||||
retained disposable history
|
||||
checkpoint pointer
|
||||
lineage-safe summaries/memories
|
||||
```
|
||||
|
||||
Use the standard fixture to reason through Undo/restore, Path A -> Path B divergence, stale summary/state risks, and image attachment after divergence.
|
||||
|
||||
Also inspect local image/provider patterns for reuse. Measure invasiveness; do not build the branch system.
|
||||
|
||||
## 10. Experiment V4 — ai-adventure Ollama / Service Boundary
|
||||
|
||||
1. Run existing tests unchanged.
|
||||
2. Identify provider interface.
|
||||
3. Prove one Ollama-backed turn using the smallest disposable adapter possible.
|
||||
4. Identify modules that know about the CLI.
|
||||
5. Determine whether the app/state layer can be wrapped by a browser/API service without moving authoritative logic.
|
||||
6. Verify undo, branch, checkpoint, restore, replay.
|
||||
7. Evaluate event/commit discipline for reuse.
|
||||
8. Evaluate its FTS/lore system against `IMPORTED-KNOWLEDGE-DESIGN.md`.
|
||||
9. Determine difficulty of adding semantic local retrieval while preserving lexical retrieval.
|
||||
10. Check privacy boundary with the Ollama adapter.
|
||||
|
||||
Do not build a browser UI.
|
||||
|
||||
## 11. Validation V5 — Test Quality
|
||||
|
||||
For each finalist report actual test count, categories, branch/rollback coverage, state reconstruction, migrations, summary/memory coverage, provider mocks, offline/network tests, browser tests, security tests, flaky/failing tests, and tests requiring Internet.
|
||||
|
||||
Highlight which high-risk acceptance requirements already have regression coverage.
|
||||
|
||||
## 12. Validation V6 — Imported Knowledge Gap Analysis
|
||||
|
||||
Against `IMPORTED-KNOWLEDGE-DESIGN.md`, report local `.txt`/`.md` ingestion, classifications, campaign isolation, provenance, lexical/semantic search, embedding provider, enable/disable, deletion, export/import, hidden canon, prompt-injection framing, and remote URL/image behavior.
|
||||
|
||||
Do not implement a full new RAG subsystem during Phase 0B.
|
||||
|
||||
## 13. Validation V7 — Browser UX Gap Analysis
|
||||
|
||||
Against `BROWSER-UX-SPEC.md`, report story reading/input quality, streaming, Undo/Redo/Retry UI, alternate-take selection, edit behavior, Save Points, state inspection, knowledge management, prompt/context inspection, local-model status, and advanced complexity exposed to the user.
|
||||
|
||||
Explicitly identify AI-DnD components worth retaining and Open Dungeon components worth borrowing/reimplementing. Do not redesign the frontend.
|
||||
|
||||
## 14. Validation V8 — Future Media and Speech Readiness
|
||||
|
||||
Against `MEDIA-EXTENSION-CONTRACT.md`, determine whether the architecture can support future local image generation, video generation, audio/ambience, text-to-speech, and speech-to-text.
|
||||
|
||||
For STT, verify the architecture can support:
|
||||
|
||||
```text
|
||||
local microphone/audio
|
||||
->
|
||||
local STT provider
|
||||
->
|
||||
editable draft text
|
||||
->
|
||||
normal user submission
|
||||
```
|
||||
|
||||
STT output must not bypass the normal story commit path.
|
||||
|
||||
Do not implement STT/TTS/video during Phase 0B. Open Dungeon local image behavior may be exercised because it already exists.
|
||||
|
||||
## 15. Final Acceptance Gap Matrix
|
||||
|
||||
Produce a matrix organized by acceptance-test group covering A, C, D, E, F, G, H, I, J, K, L, plus UX fit. Include production impact for each gap.
|
||||
|
||||
## 16. Final Decision Matrix
|
||||
|
||||
Return:
|
||||
|
||||
| Question | AI-DnD | Open Dungeon | ai-adventure |
|
||||
|---|---|---|---|
|
||||
| Baseline builds | | | |
|
||||
| Existing tests pass | | | |
|
||||
| Runs offline after setup | | | |
|
||||
| Ollama works | | | |
|
||||
| History semantics fit | | | |
|
||||
| State authority fits | | | |
|
||||
| Memory/lineage fits | | | |
|
||||
| Imported knowledge fit | | | |
|
||||
| Prompt inspection fit | | | |
|
||||
| Security/local-only hardening | | | |
|
||||
| Unwanted-code removal scope | | | |
|
||||
| Browser UX fit | | | |
|
||||
| Media extension fit | | | |
|
||||
| Future TTS/STT fit | | | |
|
||||
| Major blockers | | | |
|
||||
|
||||
## 17. Recommendation Report
|
||||
|
||||
The final recommendation should answer:
|
||||
|
||||
1. Which single repository should be the production base?
|
||||
2. Why?
|
||||
3. What are the top architectural risks?
|
||||
4. What must be removed?
|
||||
5. What must be generalized?
|
||||
6. Which concepts/components should be reimplemented from other candidates?
|
||||
7. Does Phase 0B change the preliminary AI-DnD recommendation?
|
||||
8. Which open questions remain before `TECHNICAL-DESIGN.md` v1.0?
|
||||
9. Are any v1 requirements likely to need reconsideration because of real technical constraints?
|
||||
10. Is unlimited Undo straightforward? If not, what practical limit exists and why?
|
||||
|
||||
Use evidence, not repository popularity or feature count.
|
||||
|
||||
## 18. Stop Condition
|
||||
|
||||
Stop after baseline reports, offline/network evidence, three scoped experiments, test-quality report, acceptance-gap matrix, decision matrix, and final recommendation.
|
||||
|
||||
Do not start the production fork conversion, implement the complete branch system, build the final browser UI, implement full RAG, add video/TTS/STT, rewrite the production technical design, or write production milestones.
|
||||
|
||||
Return reports and experiment diffs/results for review. The fork/architecture decision will be made from those results.
|
||||
@@ -0,0 +1,155 @@
|
||||
# Adventure Storyteller Planning Package
|
||||
|
||||
This package contains the current product requirements, provisional architecture, Phase 0 research, detailed subsystem designs, acceptance tests, and the Codex Phase 0B validation handoff for the local-only interactive-story project.
|
||||
|
||||
## Current Status
|
||||
|
||||
Phase 0A static research is complete.
|
||||
|
||||
The project is now ready for **Phase 0B local validation** of the three finalists:
|
||||
|
||||
1. AI-DnD
|
||||
2. Open Dungeon
|
||||
3. ai-adventure
|
||||
|
||||
**Do not begin production implementation yet.**
|
||||
|
||||
The purpose of Phase 0B is to validate the fork/base decision and resolve the remaining architecture questions with real builds, tests, offline runs, and tightly scoped experiments.
|
||||
|
||||
## Document Authority
|
||||
|
||||
Use the documents in this order when requirements appear to conflict:
|
||||
|
||||
1. `SPECIFICATION.md` — product requirements and desired behavior.
|
||||
2. Detailed design/behavior documents listed below — elaborations of the specification.
|
||||
3. `V1-ACCEPTANCE-TESTS.md` — observable pass/fail interpretation of v1 requirements.
|
||||
4. `TECHNICAL-DESIGN.md` — provisional implementation direction, subject to Phase 0B findings.
|
||||
5. Phase 0A reports — research evidence and candidate analysis.
|
||||
6. `BUILD-MILESTONES.md` — intentionally incomplete until the fork/architecture decision is made.
|
||||
|
||||
The detailed design documents describe target behavior; they do not force a particular repository schema when an equivalent implementation satisfies the behavior.
|
||||
|
||||
## Recommended Reading Order for Codex
|
||||
|
||||
### A. Product and architectural intent
|
||||
|
||||
1. `SPECIFICATION.md`
|
||||
2. `DATA-MODEL.md`
|
||||
3. `STORY-BRANCH-SEMANTICS.md`
|
||||
4. `CONTEXT-AND-MEMORY.md`
|
||||
5. `IMPORTED-KNOWLEDGE-DESIGN.md`
|
||||
6. `SECURITY-THREAT-MODEL.md`
|
||||
7. `MEDIA-EXTENSION-CONTRACT.md`
|
||||
8. `BROWSER-UX-SPEC.md`
|
||||
|
||||
### B. Test contract
|
||||
|
||||
9. `TEST-CAMPAIGN-FIXTURE.md`
|
||||
10. `V1-ACCEPTANCE-TESTS.md`
|
||||
|
||||
### C. Provisional architecture and research
|
||||
|
||||
11. `TECHNICAL-DESIGN.md`
|
||||
12. `RESEARCH-PLAN.md`
|
||||
13. `reports/PHASE-0A-STATUS.md`
|
||||
14. `reports/PRELIMINARY-RECOMMENDATION.md`
|
||||
15. `reports/REUSE-MATRIX.md`
|
||||
16. Candidate-specific reports in `reports/`
|
||||
|
||||
### D. Execute
|
||||
|
||||
17. `PHASE-0B-CODEX-HANDOFF.md`
|
||||
|
||||
## Core Product Decisions Already Settled
|
||||
|
||||
The Phase 0B investigation should treat these as requirements rather than questions:
|
||||
|
||||
- browser-first UI,
|
||||
- local-only v1 runtime,
|
||||
- local Ollama inference,
|
||||
- application-owned authoritative story state,
|
||||
- complete retained transcript,
|
||||
- simple user-facing Undo/Redo/Retry/Save Point semantics,
|
||||
- non-destructive internal lineage,
|
||||
- abandoned history retained but marked disposable; cleanup later,
|
||||
- at least five Undo operations; unlimited preferred if technically straightforward,
|
||||
- Redo and Retry supported,
|
||||
- named checkpoints retained until explicitly deleted,
|
||||
- genre-agnostic core schema,
|
||||
- imported knowledge classes: Canon / Reference / Inspiration,
|
||||
- local retrieval and embeddings,
|
||||
- prompt/context provenance and inspection,
|
||||
- no cloud inference, telemetry, automatic web retrieval, remote runtime assets, shell/MCP/general plugin execution,
|
||||
- future local image/video/TTS/STT capability must remain possible without coupling it to the core story engine.
|
||||
|
||||
## Detailed Documents
|
||||
|
||||
- `DATA-MODEL.md` — conceptual target data model and authority/state structures.
|
||||
- `STORY-BRANCH-SEMANTICS.md` — exact Undo, Redo, Retry, Edit, checkpoint, restore, and disposable-history behavior.
|
||||
- `CONTEXT-AND-MEMORY.md` — context construction, authority hierarchy, summaries, memory, retrieval, provenance, token budgeting.
|
||||
- `IMPORTED-KNOWLEDGE-DESIGN.md` — import, classification, chunking, local indexing, retrieval, provenance, isolation, and prompt-injection handling.
|
||||
- `SECURITY-THREAT-MODEL.md` — local trust boundary, network policy, untrusted input handling, browser security, and offline acceptance.
|
||||
- `MEDIA-EXTENSION-CONTRACT.md` — future image, video, audio, TTS, and STT extension boundaries. Media remains optional and derived from story state.
|
||||
- `BROWSER-UX-SPEC.md` — user-facing browser workflow and advanced inspection surfaces.
|
||||
- `TEST-CAMPAIGN-FIXTURE.md` — deterministic campaign fixture for comparing candidates and later regression testing.
|
||||
- `V1-ACCEPTANCE-TESTS.md` — black-box requirements and release gate.
|
||||
|
||||
## Phase 0A Research
|
||||
|
||||
Static repository research was completed on 2026-09-01.
|
||||
|
||||
Key reports:
|
||||
|
||||
- `reports/PHASE-0A-STATUS.md`
|
||||
- `reports/PRELIMINARY-RECOMMENDATION.md`
|
||||
- `reports/REUSE-MATRIX.md`
|
||||
- `reports/AI-DND-ANALYSIS.md`
|
||||
- `reports/OPEN-DUNGEON-ANALYSIS.md`
|
||||
- `reports/AI-ADVENTURE-ANALYSIS.md`
|
||||
- `reports/PRIVACY-STATIC-ANALYSIS.md`
|
||||
- `reports/LICENSING-REUSE.md`
|
||||
- `reports/SOURCE-INDEX.md`
|
||||
|
||||
Current preliminary architecture hypothesis:
|
||||
|
||||
```text
|
||||
AI-DnD production base
|
||||
+ ai-adventure trust/commit/privacy rules
|
||||
+ Open Dungeon scene/media UX patterns
|
||||
+ Chronicler memory authority tiers
|
||||
+ Interactive Fiction Framework Story Bible authority/validation
|
||||
+ Gamentic media-provider abstraction
|
||||
```
|
||||
|
||||
This is a hypothesis to test, not a fork decision.
|
||||
|
||||
## Overall Workflow
|
||||
|
||||
```text
|
||||
Specification + detailed behavioral designs
|
||||
|
|
||||
v
|
||||
Phase 0A static research
|
||||
|
|
||||
v
|
||||
Phase 0B local validation
|
||||
|
|
||||
v
|
||||
Fork / architecture decision
|
||||
|
|
||||
v
|
||||
SPECIFICATION v1.0
|
||||
TECHNICAL-DESIGN v1.0
|
||||
|
|
||||
v
|
||||
Detailed BUILD-MILESTONES.md
|
||||
|
|
||||
v
|
||||
Production implementation
|
||||
```
|
||||
|
||||
## Important Stop Rule
|
||||
|
||||
Phase 0B ends with evidence and a recommendation.
|
||||
|
||||
Codex should **not** begin production coding, repo conversion, or broad feature implementation until the Phase 0B results have been reviewed and the production base has been selected.
|
||||
@@ -0,0 +1,578 @@
|
||||
# Adventure Storyteller — Phase 0 Research Plan
|
||||
|
||||
**Status:** Ready for execution
|
||||
**Phase:** 0 — Research, Validation & Architecture
|
||||
**Goal:** Determine what to build, what to fork/reuse, and finalize the technical design before production implementation begins.
|
||||
|
||||
## 1. Why Phase 0 Exists
|
||||
|
||||
The project has several promising open-source starting points. They differ substantially in:
|
||||
|
||||
- browser UX,
|
||||
- persistence model,
|
||||
- branching semantics,
|
||||
- long-term memory,
|
||||
- local knowledge retrieval,
|
||||
- Ollama support,
|
||||
- dependency footprint,
|
||||
- privacy/network behavior,
|
||||
- game-specific assumptions,
|
||||
- licensing,
|
||||
- test quality.
|
||||
|
||||
A detailed production milestone plan written before inspecting the code would rely on guesses.
|
||||
|
||||
Phase 0 therefore ends when we can answer:
|
||||
|
||||
> What exact codebase and architecture should be used for the production storyteller?
|
||||
|
||||
No production feature work should begin before that decision unless explicitly authorized.
|
||||
|
||||
## 2. Candidate Repositories
|
||||
|
||||
Initial candidates:
|
||||
|
||||
1. **Open Dungeon**
|
||||
- Repository: `newideas99/open-dungeon`
|
||||
- Interest: browser-first interactive-fiction UX, Ollama, SQLite.
|
||||
|
||||
2. **AI-DnD**
|
||||
- Repository: `parththakkar106/AI-DnD`
|
||||
- Interest: browser UI, story tree, rollback, memory, story cards, prompt inspection.
|
||||
|
||||
3. **Local Adventure Engine / ai-adventure**
|
||||
- Repository: `CaoRuiming/ai-adventure`
|
||||
- Interest: append-only state, checkpoints, branching, privacy-focused architecture, deterministic replay.
|
||||
|
||||
4. **aiMultiFool**
|
||||
- Repository: exact upstream URL to be confirmed during inventory.
|
||||
- Interest: local semantic memory/RAG and context inspection.
|
||||
|
||||
Reference projects:
|
||||
|
||||
- SillyTavern
|
||||
- RisuAI
|
||||
- KoboldAI
|
||||
- Chronicler
|
||||
- other credible projects discovered during Phase 0.
|
||||
|
||||
## 3. Research Workspace
|
||||
|
||||
Create a dedicated workspace such as:
|
||||
|
||||
```text
|
||||
adventure-storyteller-research/
|
||||
├── candidates/
|
||||
│ ├── open-dungeon/
|
||||
│ ├── ai-dnd/
|
||||
│ ├── ai-adventure/
|
||||
│ └── aimultifool/
|
||||
├── notes/
|
||||
├── experiments/
|
||||
├── reports/
|
||||
└── inventory/
|
||||
```
|
||||
|
||||
Do not copy source code from one project into another during initial analysis.
|
||||
|
||||
Each candidate should remain a clean upstream clone or worktree.
|
||||
|
||||
Record:
|
||||
|
||||
- upstream URL,
|
||||
- upstream default branch,
|
||||
- commit SHA examined,
|
||||
- release/tag if applicable,
|
||||
- clone date,
|
||||
- license,
|
||||
- language/framework,
|
||||
- build tooling,
|
||||
- runtime services,
|
||||
- expected local ports.
|
||||
|
||||
## 4. Phase Rules
|
||||
|
||||
During Phase 0:
|
||||
|
||||
- do not begin production feature development,
|
||||
- do not merge candidate codebases,
|
||||
- do not remove features from candidate repos,
|
||||
- do not commit speculative refactors,
|
||||
- small disposable experiments are allowed,
|
||||
- experiments must be isolated and clearly documented,
|
||||
- candidate repos should remain easy to reset to upstream,
|
||||
- every conclusion should cite observed code/config/test behavior.
|
||||
|
||||
## 5. Milestone R0 — Research Workspace and Inventory
|
||||
|
||||
### Objective
|
||||
|
||||
Create the research environment and establish a reproducible inventory of all candidates.
|
||||
|
||||
### Tasks
|
||||
|
||||
- create the research workspace,
|
||||
- clone all initial candidates,
|
||||
- record exact upstream commits,
|
||||
- locate and record licenses,
|
||||
- inventory languages/frameworks,
|
||||
- inventory package managers,
|
||||
- inventory database/storage dependencies,
|
||||
- inventory model/provider dependencies,
|
||||
- inventory frontend/backend separation,
|
||||
- record build/run instructions,
|
||||
- identify existing tests,
|
||||
- identify documentation directories,
|
||||
- identify migrations/schema definitions,
|
||||
- identify obvious telemetry/cloud integrations.
|
||||
|
||||
### Deliverables
|
||||
|
||||
- `inventory/candidates.md`
|
||||
- `inventory/licenses.md`
|
||||
- `inventory/dependencies.md`
|
||||
- `inventory/build-instructions.md`
|
||||
- machine-readable candidate metadata if useful.
|
||||
|
||||
### Exit Criteria
|
||||
|
||||
All serious candidates are locally available and reproducibly identified.
|
||||
|
||||
## 6. Milestone R1 — Build and Run Candidates
|
||||
|
||||
### Objective
|
||||
|
||||
Verify actual behavior rather than relying on README claims.
|
||||
|
||||
### Tasks
|
||||
|
||||
For each serious candidate:
|
||||
|
||||
- install dependencies,
|
||||
- build successfully where applicable,
|
||||
- start locally,
|
||||
- create a minimal story,
|
||||
- confirm persistence after restart,
|
||||
- test Ollama directly where supported,
|
||||
- identify how model configuration works,
|
||||
- record application ports,
|
||||
- identify data locations,
|
||||
- inspect browser developer/network activity for unexpected outbound requests where applicable,
|
||||
- record startup failures or undocumented requirements.
|
||||
|
||||
For projects not supporting Ollama:
|
||||
|
||||
- determine adapter/interface boundary,
|
||||
- do not yet permanently modify the project.
|
||||
|
||||
### Deliverables
|
||||
|
||||
Per candidate:
|
||||
|
||||
```text
|
||||
reports/runtime-<candidate>.md
|
||||
```
|
||||
|
||||
Include:
|
||||
|
||||
- exact commands,
|
||||
- success/failure,
|
||||
- screenshots only if useful,
|
||||
- local services used,
|
||||
- observed storage files,
|
||||
- observed network activity,
|
||||
- known blockers.
|
||||
|
||||
### Exit Criteria
|
||||
|
||||
Each serious candidate has either been run successfully or has a documented reason it cannot reasonably be evaluated.
|
||||
|
||||
## 7. Milestone R2 — Source Architecture Review
|
||||
|
||||
### Objective
|
||||
|
||||
Understand how each candidate actually works internally.
|
||||
|
||||
### Review Areas
|
||||
|
||||
#### Browser/UI
|
||||
- framework,
|
||||
- state management,
|
||||
- streaming,
|
||||
- transcript representation,
|
||||
- campaign navigation,
|
||||
- edit/retry behavior,
|
||||
- extensibility for future media.
|
||||
|
||||
#### Backend/service layer
|
||||
- routing/API design,
|
||||
- model invocation boundary,
|
||||
- background jobs,
|
||||
- validation boundaries.
|
||||
|
||||
#### Persistence
|
||||
- database type,
|
||||
- schema,
|
||||
- migrations,
|
||||
- turn representation,
|
||||
- snapshots,
|
||||
- event log,
|
||||
- transactions,
|
||||
- branch representation.
|
||||
|
||||
#### Story history
|
||||
- linear vs tree,
|
||||
- retry semantics,
|
||||
- undo semantics,
|
||||
- destructive vs non-destructive restore,
|
||||
- branch naming/navigation.
|
||||
|
||||
#### Context
|
||||
- prompt assembly,
|
||||
- recent history,
|
||||
- summaries,
|
||||
- token budgeting,
|
||||
- author notes/system rules.
|
||||
|
||||
#### Memory
|
||||
- summaries,
|
||||
- vector retrieval,
|
||||
- keyword retrieval,
|
||||
- entity state,
|
||||
- old-turn retrieval.
|
||||
|
||||
#### Lore/knowledge
|
||||
- import formats,
|
||||
- chunking,
|
||||
- story cards/world info,
|
||||
- semantic retrieval,
|
||||
- provenance.
|
||||
|
||||
#### Tests
|
||||
- unit tests,
|
||||
- integration tests,
|
||||
- migration tests,
|
||||
- model mocks,
|
||||
- coverage of state/rollback.
|
||||
|
||||
### Deliverables
|
||||
|
||||
- `reports/architecture-open-dungeon.md`
|
||||
- `reports/architecture-ai-dnd.md`
|
||||
- `reports/architecture-ai-adventure.md`
|
||||
- `reports/architecture-aimultifool.md`
|
||||
- `reports/architecture-comparison.md`
|
||||
|
||||
### Exit Criteria
|
||||
|
||||
We can explain each candidate's architecture without relying on marketing descriptions.
|
||||
|
||||
## 8. Milestone R3 — Privacy and Network Review
|
||||
|
||||
### Objective
|
||||
|
||||
Determine what must be removed, disabled, or isolated to satisfy the local-only requirement.
|
||||
|
||||
### Search For
|
||||
|
||||
- OpenAI,
|
||||
- OpenRouter,
|
||||
- Groq,
|
||||
- Anthropic,
|
||||
- Google,
|
||||
- cloud inference,
|
||||
- telemetry,
|
||||
- analytics,
|
||||
- Sentry,
|
||||
- PostHog,
|
||||
- crash reporting,
|
||||
- CDN,
|
||||
- Google Fonts,
|
||||
- remote image hosts,
|
||||
- automatic update checks,
|
||||
- remote database support,
|
||||
- URL retrieval,
|
||||
- external web search,
|
||||
- MCP,
|
||||
- plugins,
|
||||
- arbitrary executable scripts,
|
||||
- third-party auth.
|
||||
|
||||
### Tasks
|
||||
|
||||
- static source search,
|
||||
- dependency review,
|
||||
- environment-variable review,
|
||||
- runtime network observation,
|
||||
- identify outbound requests required vs optional,
|
||||
- identify localhost vs wildcard binds,
|
||||
- identify stored secrets/API keys,
|
||||
- identify browser-side remote resources.
|
||||
|
||||
### Deliverables
|
||||
|
||||
- `reports/privacy-network-review.md`
|
||||
- per-candidate removal/mitigation list.
|
||||
|
||||
### Exit Criteria
|
||||
|
||||
For each candidate, we can state exactly what local-only hardening would be required.
|
||||
|
||||
## 9. Milestone R4 — Feature and Reuse Matrix
|
||||
|
||||
### Objective
|
||||
|
||||
Compare candidates by subsystem rather than declaring one project the winner prematurely.
|
||||
|
||||
### Compare
|
||||
|
||||
- browser UX,
|
||||
- Ollama adapter,
|
||||
- streaming,
|
||||
- SQLite schema,
|
||||
- story tree,
|
||||
- rollback,
|
||||
- checkpoints,
|
||||
- edit/retry semantics,
|
||||
- state extraction,
|
||||
- entity/world state,
|
||||
- summaries,
|
||||
- semantic memory,
|
||||
- lexical memory,
|
||||
- lore/story cards,
|
||||
- source imports,
|
||||
- prompt inspection,
|
||||
- export/import,
|
||||
- tests,
|
||||
- local-only posture,
|
||||
- media extensibility.
|
||||
|
||||
### Rate Each Feature
|
||||
|
||||
Use categories such as:
|
||||
|
||||
- Keep as-is
|
||||
- Keep with modification
|
||||
- Reuse concept only
|
||||
- Replace
|
||||
- Not present
|
||||
- Not wanted
|
||||
|
||||
### Deliverables
|
||||
|
||||
- `reports/reuse-matrix.md`
|
||||
|
||||
### Exit Criteria
|
||||
|
||||
We know which candidate has the best implementation of each required subsystem.
|
||||
|
||||
## 10. Milestone R5 — Licensing and Code-Reuse Review
|
||||
|
||||
### Objective
|
||||
|
||||
Determine what code can legally be copied, modified, linked, or used only as inspiration.
|
||||
|
||||
### Tasks
|
||||
|
||||
- verify repository licenses at the exact commits reviewed,
|
||||
- note third-party code with separate licenses,
|
||||
- note generated/vendor code,
|
||||
- compare compatibility if combining code from multiple projects,
|
||||
- pay special attention to GPL/copyleft candidates,
|
||||
- distinguish:
|
||||
- direct code reuse,
|
||||
- dependency use,
|
||||
- architecture inspiration,
|
||||
- protocol/API reimplementation.
|
||||
|
||||
### Deliverables
|
||||
|
||||
- `reports/licensing-reuse.md`
|
||||
|
||||
### Exit Criteria
|
||||
|
||||
The recommended architecture does not rely on legally ambiguous code mixing.
|
||||
|
||||
## 11. Milestone R6 — Critical Prototypes
|
||||
|
||||
### Objective
|
||||
|
||||
Test only the uncertainties that could change the architecture decision.
|
||||
|
||||
Possible experiments include:
|
||||
|
||||
### Experiment A — Ollama adapter for ai-adventure
|
||||
Determine how difficult it is to replace/extend the LM Studio adapter with Ollama.
|
||||
|
||||
### Experiment B — Branch-safe state in Open Dungeon
|
||||
Determine whether Open Dungeon's current persistence can support immutable branch parentage without invasive rewrite.
|
||||
|
||||
### Experiment C — Strip-down feasibility in AI-DnD
|
||||
Identify whether RPG/cloud systems are modular enough to remove without destabilizing core story-tree/memory behavior.
|
||||
|
||||
### Experiment D — Local semantic retrieval
|
||||
Test a minimal local embedding pipeline using Ollama and a local-only store.
|
||||
|
||||
### Experiment E — Scene extraction
|
||||
Verify that the narrator/state pipeline can produce a neutral scene packet suitable for future media.
|
||||
|
||||
Only run experiments that resolve a documented decision.
|
||||
|
||||
### Deliverables
|
||||
|
||||
Each experiment:
|
||||
|
||||
```text
|
||||
experiments/<name>/README.md
|
||||
```
|
||||
|
||||
Record:
|
||||
|
||||
- question,
|
||||
- hypothesis,
|
||||
- minimal changes,
|
||||
- result,
|
||||
- implications,
|
||||
- whether code should be discarded.
|
||||
|
||||
### Exit Criteria
|
||||
|
||||
No high-impact fork/architecture decision remains based solely on speculation.
|
||||
|
||||
## 12. Milestone R7 — Fork / Build Decision
|
||||
|
||||
### Objective
|
||||
|
||||
Select the production starting strategy.
|
||||
|
||||
### Required Options to Evaluate
|
||||
|
||||
- fork Open Dungeon,
|
||||
- fork AI-DnD,
|
||||
- fork/use ai-adventure core,
|
||||
- clean new shell with reused permissive components,
|
||||
- other candidate if discovered.
|
||||
|
||||
### Decision Criteria
|
||||
|
||||
Weight heavily:
|
||||
|
||||
1. fit with interactive-story product,
|
||||
2. browser-first architecture,
|
||||
3. Ollama fit,
|
||||
4. state/branch correctness,
|
||||
5. local-only hardening effort,
|
||||
6. amount of code to remove,
|
||||
7. maintainability,
|
||||
8. licensing,
|
||||
9. test quality,
|
||||
10. future media extensibility.
|
||||
|
||||
### Deliverables
|
||||
|
||||
- `reports/fork-build-recommendation.md`
|
||||
- ADR documenting the selected strategy.
|
||||
|
||||
### Exit Criteria
|
||||
|
||||
One strategy is approved as the production base.
|
||||
|
||||
## 13. Milestone R8 — Finalize Specification and Technical Design
|
||||
|
||||
### Objective
|
||||
|
||||
Convert assumptions into committed decisions.
|
||||
|
||||
### Tasks
|
||||
|
||||
Update:
|
||||
|
||||
- `SPECIFICATION.md`
|
||||
- `TECHNICAL-DESIGN.md`
|
||||
|
||||
Resolve:
|
||||
|
||||
- base repository,
|
||||
- frontend framework,
|
||||
- backend framework,
|
||||
- storage model,
|
||||
- branch/state model,
|
||||
- model adapter,
|
||||
- memory/retrieval strategy,
|
||||
- local knowledge design,
|
||||
- import formats for v1,
|
||||
- context budgeting strategy,
|
||||
- security boundaries,
|
||||
- export format,
|
||||
- future media interfaces,
|
||||
- test strategy.
|
||||
|
||||
Mark documents v1.0 when approved.
|
||||
|
||||
### Deliverables
|
||||
|
||||
- `SPECIFICATION.md` v1.0
|
||||
- `TECHNICAL-DESIGN.md` v1.0
|
||||
- relevant ADRs.
|
||||
|
||||
### Exit Criteria
|
||||
|
||||
A developer can explain the final architecture without unresolved foundational choices.
|
||||
|
||||
## 14. Milestone R9 — Create Production Build Plan
|
||||
|
||||
### Objective
|
||||
|
||||
Write the detailed implementation milestone plan only after the technical design is stable.
|
||||
|
||||
### Tasks
|
||||
|
||||
Create:
|
||||
|
||||
- `BUILD-MILESTONES.md`
|
||||
|
||||
It must include:
|
||||
|
||||
- milestone dependencies,
|
||||
- exact intended outcomes,
|
||||
- acceptance criteria,
|
||||
- test expectations,
|
||||
- migration steps from selected upstream,
|
||||
- removal/hardening work,
|
||||
- v1 feature sequence,
|
||||
- definition of done.
|
||||
|
||||
### Exit Criteria
|
||||
|
||||
The build plan is specific enough to hand directly to Codex milestone-by-milestone.
|
||||
|
||||
## 15. Phase 0 Final Deliverables
|
||||
|
||||
At Phase 0 completion:
|
||||
|
||||
```text
|
||||
SPECIFICATION.md v1.0
|
||||
TECHNICAL-DESIGN.md v1.0
|
||||
RESEARCH-PLAN.md completed
|
||||
BUILD-MILESTONES.md production-ready
|
||||
DECISIONS/ finalized foundational ADRs
|
||||
reports/ research evidence
|
||||
experiments/ critical prototype evidence
|
||||
inventory/ candidate metadata
|
||||
```
|
||||
|
||||
## 16. Phase 0 Definition of Done
|
||||
|
||||
Phase 0 is complete only when:
|
||||
|
||||
- candidate repositories have been cloned and reviewed,
|
||||
- serious candidates have been run or ruled out with evidence,
|
||||
- network/privacy behavior is documented,
|
||||
- licensing is understood,
|
||||
- critical architectural uncertainties have been tested,
|
||||
- a fork/build strategy has been selected,
|
||||
- the specification is v1.0,
|
||||
- the technical design is v1.0,
|
||||
- the actual implementation milestone plan has been written.
|
||||
|
||||
At that point, production implementation can begin.
|
||||
File diff suppressed because it is too large
Load Diff
@@ -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.
|
||||
@@ -0,0 +1,856 @@
|
||||
# Adventure Storyteller — Story Branch Semantics
|
||||
|
||||
**Status:** Draft v0.1
|
||||
**Purpose:** Define exactly how Undo, Redo, Retry, Edit, Restore, checkpoints, and abandoned history should behave.
|
||||
|
||||
## 1. Design Goal
|
||||
|
||||
The user experience should remain simple.
|
||||
|
||||
The user should not need to think in terms of Git branches, tree structures, or database lineage during normal storytelling.
|
||||
|
||||
The primary controls should be:
|
||||
|
||||
- Undo
|
||||
- Redo
|
||||
- Retry
|
||||
- Edit
|
||||
- Save Checkpoint
|
||||
- Restore Checkpoint
|
||||
|
||||
Internally, however, the system should preserve enough history to make these operations safe, reversible, and state-consistent.
|
||||
|
||||
The core rule is:
|
||||
|
||||
> User-facing history should feel like normal Undo/Redo, while internal history may use branch-like lineage to avoid destructive edits.
|
||||
|
||||
## 2. User-Facing Philosophy
|
||||
|
||||
### 2.1 Branching is an implementation detail
|
||||
|
||||
The normal UI should not require explicit actions such as:
|
||||
|
||||
- Create Branch
|
||||
- Switch Branch
|
||||
- Merge Branch
|
||||
- Compare Branches
|
||||
|
||||
Those concepts may exist internally.
|
||||
|
||||
The user should instead see familiar operations.
|
||||
|
||||
### 2.2 Abandoned history is retained but disposable
|
||||
|
||||
When the user goes backward and continues differently:
|
||||
|
||||
- the original future should not be immediately deleted,
|
||||
- it should be marked as abandoned/disposable,
|
||||
- it should no longer appear as the active story,
|
||||
- it may be pruned later by a future cleanup feature,
|
||||
- it may optionally become recoverable through a future discarded-history screen.
|
||||
|
||||
No automatic cleanup policy is required for v1.
|
||||
|
||||
### 2.3 Named checkpoints are intentionally durable
|
||||
|
||||
A named checkpoint is different from ordinary undo history.
|
||||
|
||||
Named checkpoints remain until explicitly deleted.
|
||||
|
||||
## 3. Definitions
|
||||
|
||||
### Active History
|
||||
The currently selected sequence of accepted turns from campaign root to the current head.
|
||||
|
||||
### Story Head
|
||||
The current endpoint of active history.
|
||||
|
||||
### Abandoned History
|
||||
Previously accepted turns that are no longer part of the active continuation because the user undid, restored, edited, or retried and then continued differently.
|
||||
|
||||
### Disposable History
|
||||
Abandoned history that is retained for safety/recovery but may be eligible for future cleanup.
|
||||
|
||||
### Named Checkpoint
|
||||
A durable user-created pointer to a specific accepted story position.
|
||||
|
||||
### Alternate Take
|
||||
A different narrator response to the same user input.
|
||||
|
||||
### Divergence
|
||||
The point where active story history begins following a different continuation than previously accepted history.
|
||||
|
||||
## 4. Undo
|
||||
|
||||
Undo moves the active story head backward by one accepted story step.
|
||||
|
||||
Example:
|
||||
|
||||
```text
|
||||
Turn 47
|
||||
You enter the tavern.
|
||||
|
||||
Turn 48
|
||||
You accuse Mara of stealing the key.
|
||||
|
||||
Turn 49
|
||||
Mara draws a knife.
|
||||
```
|
||||
|
||||
After one Undo:
|
||||
|
||||
```text
|
||||
Active head: Turn 48
|
||||
Redo candidate: Turn 49
|
||||
```
|
||||
|
||||
After two Undos:
|
||||
|
||||
```text
|
||||
Active head: Turn 47
|
||||
Redo candidate: Turn 48
|
||||
```
|
||||
|
||||
## 5. Undo Depth
|
||||
|
||||
Preferred behavior:
|
||||
|
||||
> Unlimited Undo across retained campaign history.
|
||||
|
||||
If the selected base architecture makes unlimited Undo substantially harder or unsafe, the minimum acceptable behavior is:
|
||||
|
||||
> At least five consecutive Undo operations.
|
||||
|
||||
Technical validation during Phase 0B should determine whether unlimited Undo is straightforward.
|
||||
|
||||
The final implementation should prefer unlimited Undo unless there is a concrete technical reason not to.
|
||||
|
||||
## 6. State Restoration on Undo
|
||||
|
||||
Undo must restore more than visible transcript text.
|
||||
|
||||
When moving the story head backward, the system must restore the corresponding:
|
||||
|
||||
- authoritative narrative state,
|
||||
- current location,
|
||||
- entity states,
|
||||
- relationships,
|
||||
- facts,
|
||||
- active story threads,
|
||||
- scene state,
|
||||
- summary lineage,
|
||||
- memory lineage,
|
||||
- relevant prompt/retrieval lineage.
|
||||
|
||||
The system must not leave current state from a later turn attached to an earlier transcript position.
|
||||
|
||||
## 7. Redo
|
||||
|
||||
Redo moves forward along the previously active continuation after Undo.
|
||||
|
||||
Example:
|
||||
|
||||
```text
|
||||
47 -> 48 -> 49
|
||||
```
|
||||
|
||||
User undoes to 47:
|
||||
|
||||
```text
|
||||
Active: 47
|
||||
Redo path: 48 -> 49
|
||||
```
|
||||
|
||||
Pressing Redo restores 48.
|
||||
|
||||
Pressing Redo again restores 49.
|
||||
|
||||
## 8. Redo Invalidation
|
||||
|
||||
Redo remains available only while the user has not created a new continuation.
|
||||
|
||||
Example:
|
||||
|
||||
```text
|
||||
47 -> 48A -> 49A
|
||||
```
|
||||
|
||||
User undoes to 47 and then enters a new action:
|
||||
|
||||
```text
|
||||
47 -> 48B
|
||||
```
|
||||
|
||||
At that point:
|
||||
|
||||
- 48B becomes active,
|
||||
- 48A -> 49A becomes abandoned/disposable history,
|
||||
- ordinary Redo should no longer move into 48A.
|
||||
|
||||
The old history is retained internally but is no longer part of the standard Redo stack.
|
||||
|
||||
## 9. Retry
|
||||
|
||||
Retry means:
|
||||
|
||||
> Generate another narrator response to the same user input.
|
||||
|
||||
Example:
|
||||
|
||||
```text
|
||||
User:
|
||||
I open the door.
|
||||
|
||||
Take A:
|
||||
A dragon lunges through the doorway.
|
||||
```
|
||||
|
||||
Retry:
|
||||
|
||||
```text
|
||||
Take B:
|
||||
The room beyond is dark and silent.
|
||||
```
|
||||
|
||||
The user should be able to move among recent alternate takes before continuing.
|
||||
|
||||
## 10. Retry Selection
|
||||
|
||||
Before the user continues the story, alternate narrator takes should remain selectable.
|
||||
|
||||
Conceptually:
|
||||
|
||||
```text
|
||||
User action
|
||||
|
|
||||
+-- Take A
|
||||
+-- Take B
|
||||
+-- Take C
|
||||
```
|
||||
|
||||
One take is selected as active.
|
||||
|
||||
If the user continues from Take B:
|
||||
|
||||
```text
|
||||
User action
|
||||
|
|
||||
+-- Take A [inactive/disposable]
|
||||
+-- Take B [selected]
|
||||
|
|
||||
+-- next user turn
|
||||
+-- Take C [inactive/disposable]
|
||||
```
|
||||
|
||||
Inactive takes should remain retained initially.
|
||||
|
||||
## 11. Retry vs Branch
|
||||
|
||||
Retry should not be presented to the user as “creating a branch.”
|
||||
|
||||
It is an alternate narrator attempt for the same user instruction.
|
||||
|
||||
Internally, the implementation may represent retries as sibling turn nodes, alternate takes under one turn request, or another equivalent lineage mechanism.
|
||||
|
||||
The physical representation is still provisional.
|
||||
|
||||
## 12. Retry of Older Narration
|
||||
|
||||
If the user selects an older narrator response and retries it:
|
||||
|
||||
- the system first returns to that story position,
|
||||
- the existing future becomes abandoned/disposable history,
|
||||
- the new narrator take becomes a new continuation candidate.
|
||||
|
||||
The system must restore the state corresponding to the retry point before generating the new response.
|
||||
|
||||
## 13. Editing User Input
|
||||
|
||||
The user should be able to edit an earlier user input.
|
||||
|
||||
Semantics:
|
||||
|
||||
> Editing an earlier user input is equivalent to returning to the parent story state and creating a new continuation using the edited input.
|
||||
|
||||
Example:
|
||||
|
||||
Original:
|
||||
|
||||
```text
|
||||
47: Arrive at tavern
|
||||
48: "I accuse Mara of taking the key."
|
||||
49: Mara draws a knife.
|
||||
```
|
||||
|
||||
User edits Turn 48 to:
|
||||
|
||||
```text
|
||||
"I quietly ask Mara whether she has seen the key."
|
||||
```
|
||||
|
||||
Result:
|
||||
|
||||
```text
|
||||
47
|
||||
├── 48A original accusation
|
||||
│ └── 49A knife response
|
||||
└── 48B edited question
|
||||
└── new narrator response
|
||||
```
|
||||
|
||||
The old future is retained as disposable history.
|
||||
|
||||
## 14. Editing Narrator Output
|
||||
|
||||
The user should be able to directly correct narrator prose.
|
||||
|
||||
Example:
|
||||
|
||||
Original:
|
||||
|
||||
```text
|
||||
Mara enters wearing a red cloak.
|
||||
```
|
||||
|
||||
User changes it to:
|
||||
|
||||
```text
|
||||
Mara enters wearing a green cloak.
|
||||
```
|
||||
|
||||
The edited narration becomes authoritative for the active continuation.
|
||||
|
||||
## 15. Effects of Narrator Edit
|
||||
|
||||
Editing narrator output may affect structured state.
|
||||
|
||||
Therefore the system must:
|
||||
|
||||
1. return to the state immediately before the edited narration,
|
||||
2. treat the edited text as the accepted narrator output,
|
||||
3. re-evaluate state changes implied by that output,
|
||||
4. create a new active continuation,
|
||||
5. retain the original narration/future as disposable history.
|
||||
|
||||
The system must not simply replace visible text while leaving stale state behind.
|
||||
|
||||
## 16. Manual State / Canon Correction
|
||||
|
||||
The user should be able to correct authoritative story state without rewriting prose.
|
||||
|
||||
Example:
|
||||
|
||||
> Mara never learned about the silver key.
|
||||
|
||||
This should be available through an explicit operation such as:
|
||||
|
||||
- Edit Story State
|
||||
- Edit Canon
|
||||
- Correct Fact
|
||||
|
||||
Exact UI terminology is still open.
|
||||
|
||||
## 17. State Correction Semantics
|
||||
|
||||
A manual correction should:
|
||||
|
||||
- record the old value,
|
||||
- record the new value,
|
||||
- record that the source was a manual user correction,
|
||||
- record when the correction occurred,
|
||||
- affect future story context,
|
||||
- remain auditable.
|
||||
|
||||
A manual correction should not silently rewrite historical transcript text.
|
||||
|
||||
If historical consistency requires a deeper rewind, the UI may warn the user.
|
||||
|
||||
## 18. Checkpoints
|
||||
|
||||
A checkpoint is a user-created durable save point.
|
||||
|
||||
Example names:
|
||||
|
||||
- Before entering Blackwood
|
||||
- Arrival at Ceres Station
|
||||
- Before confronting Mara
|
||||
- Before opening the vault
|
||||
|
||||
A checkpoint points to a specific accepted story position.
|
||||
|
||||
## 19. Checkpoint Durability
|
||||
|
||||
Named checkpoints remain until explicitly deleted.
|
||||
|
||||
They should not be removed by:
|
||||
|
||||
- Undo,
|
||||
- Redo,
|
||||
- Retry,
|
||||
- Edit,
|
||||
- Restore,
|
||||
- branch divergence,
|
||||
- ordinary history cleanup.
|
||||
|
||||
## 20. Checkpoint Restore
|
||||
|
||||
Restoring a checkpoint:
|
||||
|
||||
1. moves the active story head to the checkpoint turn,
|
||||
2. restores authoritative state for that turn,
|
||||
3. restores corresponding scene state,
|
||||
4. restores compatible summary/memory lineage,
|
||||
5. prepares the story to continue from that position.
|
||||
|
||||
The original later story remains retained as abandoned/disposable history.
|
||||
|
||||
## 21. Restore Does Not Delete
|
||||
|
||||
Example:
|
||||
|
||||
```text
|
||||
Checkpoint: Before Fortress
|
||||
|
||||
100 -> 101 -> 102 -> 103 -> 104
|
||||
```
|
||||
|
||||
Restore checkpoint at 100 and continue:
|
||||
|
||||
```text
|
||||
100
|
||||
├── 101A -> 102A -> 103A -> 104A [old/disposable]
|
||||
└── 101B -> 102B [active]
|
||||
```
|
||||
|
||||
The UI does not need to show this tree during normal play.
|
||||
|
||||
## 22. Model Settings on Restore
|
||||
|
||||
A checkpoint primarily preserves story position and state.
|
||||
|
||||
It does not need to force restoration of the exact narrator model/settings used at the time.
|
||||
|
||||
Every historical turn should separately preserve its original model/settings for auditability.
|
||||
|
||||
When continuing after restore, the system should normally use the user's current configured model/settings.
|
||||
|
||||
A future optional control may allow restoring historical model settings.
|
||||
|
||||
## 23. Checkpoint Renaming
|
||||
|
||||
Checkpoint labels may be renamed.
|
||||
|
||||
Renaming does not change the referenced story position.
|
||||
|
||||
## 24. Moving Checkpoints
|
||||
|
||||
v1 should not casually allow an existing checkpoint to be moved to another turn.
|
||||
|
||||
Preferred behavior:
|
||||
|
||||
- rename checkpoint, or
|
||||
- delete checkpoint and create a new one.
|
||||
|
||||
This keeps checkpoint meaning auditable.
|
||||
|
||||
## 25. Deleting Checkpoints
|
||||
|
||||
Checkpoint deletion must be explicit.
|
||||
|
||||
Deleting a checkpoint:
|
||||
|
||||
- removes the named pointer,
|
||||
- does not delete the story turn,
|
||||
- does not delete story history.
|
||||
|
||||
## 26. Abandoned / Disposable History
|
||||
|
||||
When a different continuation becomes active, the displaced future becomes conceptually:
|
||||
|
||||
```text
|
||||
abandoned = true
|
||||
disposable = true
|
||||
```
|
||||
|
||||
Equivalent metadata may be used.
|
||||
|
||||
The exact database representation is implementation-specific.
|
||||
|
||||
## 27. No Automatic Cleanup in Initial Version
|
||||
|
||||
v1 should not automatically purge disposable history.
|
||||
|
||||
Reasons:
|
||||
|
||||
- text/state records are inexpensive,
|
||||
- early cleanup risks destroying useful recovery data,
|
||||
- branch/state correctness is easier to verify when history remains,
|
||||
- generated media will consume much more storage than text.
|
||||
|
||||
Cleanup should be designed only after real usage shows it is necessary.
|
||||
|
||||
## 28. Future Cleanup
|
||||
|
||||
A later cleanup feature may offer:
|
||||
|
||||
- prune abandoned history older than N days,
|
||||
- prune abandoned history older than N turns,
|
||||
- prune all unprotected discarded paths,
|
||||
- retain paths referenced by checkpoints,
|
||||
- retain paths containing manually preserved alternates,
|
||||
- show estimated space savings before deletion.
|
||||
|
||||
No specific cleanup policy is committed for v1.
|
||||
|
||||
## 29. Possible Future Discarded-History Recovery Screen
|
||||
|
||||
A future feature may expose discarded/abandoned history.
|
||||
|
||||
Possible uses:
|
||||
|
||||
- recover a discarded continuation,
|
||||
- inspect earlier alternate takes,
|
||||
- restore something accidentally abandoned,
|
||||
- compare old and current story paths.
|
||||
|
||||
This is a possible later feature, not a committed v1 requirement.
|
||||
|
||||
## 30. Active History Visibility
|
||||
|
||||
Normal transcript display should show only:
|
||||
|
||||
- the active history,
|
||||
- currently selected narrator take,
|
||||
- current story state.
|
||||
|
||||
Discarded history should not clutter normal play.
|
||||
|
||||
## 31. History Integrity
|
||||
|
||||
The system must never create a transcript/state mismatch such as:
|
||||
|
||||
```text
|
||||
Visible transcript says:
|
||||
Mara never saw the key.
|
||||
|
||||
Structured state says:
|
||||
Mara knows about the key because of abandoned Turn 52.
|
||||
```
|
||||
|
||||
Only active-lineage facts, memories, summaries, and state may influence the current continuation.
|
||||
|
||||
## 32. Summary Lineage
|
||||
|
||||
Summaries are derived from specific story history.
|
||||
|
||||
When the active story diverges:
|
||||
|
||||
- summaries containing abandoned future turns must not be applied to the new continuation,
|
||||
- unaffected ancestral summaries may remain valid,
|
||||
- new summaries may be generated when required.
|
||||
|
||||
The system should record source turn ranges or lineage for every summary.
|
||||
|
||||
## 33. Memory Lineage
|
||||
|
||||
Retrieved story memory must respect active lineage.
|
||||
|
||||
A memory from an abandoned future must not appear as something that happened in the active story.
|
||||
|
||||
Example:
|
||||
|
||||
Discarded path:
|
||||
|
||||
```text
|
||||
Mara reveals she is a spy.
|
||||
```
|
||||
|
||||
New active path:
|
||||
|
||||
```text
|
||||
Mara has never revealed this.
|
||||
```
|
||||
|
||||
The memory retriever must not feed:
|
||||
|
||||
```text
|
||||
Mara is known to be a spy.
|
||||
```
|
||||
|
||||
to the narrator merely because that fact exists in an abandoned path.
|
||||
|
||||
This is a critical correctness requirement.
|
||||
|
||||
## 34. Imported Knowledge Is Different
|
||||
|
||||
Imported Canon / Reference / Inspiration files are not normally branch-specific.
|
||||
|
||||
They remain available across branches unless the source is explicitly campaign-state-dependent or the user disables/removes the source.
|
||||
|
||||
Story memories and story-derived facts, by contrast, must be lineage-aware.
|
||||
|
||||
## 35. Scene Lineage
|
||||
|
||||
Scene snapshots must also follow active history.
|
||||
|
||||
A scene from an abandoned future must not become the current scene after Undo or Restore.
|
||||
|
||||
Generated media attached to an abandoned scene may remain stored, but it should no longer be treated as current-story media.
|
||||
|
||||
## 36. Prompt Provenance
|
||||
|
||||
Every generated narrator take should preserve enough information to determine:
|
||||
|
||||
- parent story position,
|
||||
- user input,
|
||||
- selected history,
|
||||
- current state,
|
||||
- summaries used,
|
||||
- memories used,
|
||||
- imported knowledge used,
|
||||
- model/settings,
|
||||
- resulting output.
|
||||
|
||||
This remains true even for abandoned/disposable history until it is explicitly pruned.
|
||||
|
||||
## 37. Failure During Retry / Edit / Continue
|
||||
|
||||
If generation fails:
|
||||
|
||||
- the previously accepted active history remains valid,
|
||||
- no partial state mutation should be committed,
|
||||
- no successful prior take should be lost.
|
||||
|
||||
The user should be able to retry generation.
|
||||
|
||||
## 38. Atomic Acceptance
|
||||
|
||||
A newly generated continuation should become accepted only when the application can coherently commit:
|
||||
|
||||
- narration,
|
||||
- lineage,
|
||||
- state changes,
|
||||
- scene update,
|
||||
- provenance.
|
||||
|
||||
A failure in state extraction should not silently leave partially applied state.
|
||||
|
||||
Exact failure-repair handling will be specified later.
|
||||
|
||||
## 39. User-Facing Control Summary
|
||||
|
||||
### Undo
|
||||
Move backward one accepted story step.
|
||||
|
||||
### Redo
|
||||
Move forward again, until a new continuation is created.
|
||||
|
||||
### Retry
|
||||
Generate another narrator response to the same user input.
|
||||
|
||||
### Edit User Input
|
||||
Return to that point and create a new continuation using edited input.
|
||||
|
||||
### Edit Narrator Output
|
||||
Replace the active narration through a new auditable continuation and re-evaluate state.
|
||||
|
||||
### Save Checkpoint
|
||||
Create a durable named pointer to the current story position.
|
||||
|
||||
### Restore Checkpoint
|
||||
Return to that state; later history becomes retained disposable history.
|
||||
|
||||
### Correct State / Canon
|
||||
Explicitly change an authoritative fact without rewriting transcript prose.
|
||||
|
||||
## 40. Not Required in v1 UI
|
||||
|
||||
Do not require:
|
||||
|
||||
- branch tree visualization,
|
||||
- manual branch creation,
|
||||
- merge,
|
||||
- cherry-pick,
|
||||
- branch comparison,
|
||||
- branch IDs,
|
||||
- discarded-history browser,
|
||||
- automatic branch cleanup.
|
||||
|
||||
Internal lineage may still use branch/tree structures.
|
||||
|
||||
## 41. Minimum v1 Undo Requirement
|
||||
|
||||
Acceptance requirement:
|
||||
|
||||
- at least 5 consecutive Undo operations must be supported.
|
||||
|
||||
Preferred:
|
||||
|
||||
- unlimited Undo across retained history.
|
||||
|
||||
Phase 0B should determine whether the preferred behavior is already practical in the selected base.
|
||||
|
||||
## 42. Example: Simple Mistake
|
||||
|
||||
Initial:
|
||||
|
||||
```text
|
||||
10: Enter tavern
|
||||
11: Accuse Mara
|
||||
12: Mara becomes hostile
|
||||
```
|
||||
|
||||
User Undo x2:
|
||||
|
||||
```text
|
||||
Active head = 10
|
||||
```
|
||||
|
||||
User enters:
|
||||
|
||||
```text
|
||||
I ask Mara privately whether she saw anyone near my room.
|
||||
```
|
||||
|
||||
Result:
|
||||
|
||||
```text
|
||||
10
|
||||
├── 11A Accuse Mara
|
||||
│ └── 12A Mara hostile
|
||||
└── 11B Ask privately
|
||||
└── 12B New narration
|
||||
```
|
||||
|
||||
User sees only:
|
||||
|
||||
```text
|
||||
10 -> 11B -> 12B
|
||||
```
|
||||
|
||||
The A path is retained but disposable.
|
||||
|
||||
## 43. Example: Retry
|
||||
|
||||
```text
|
||||
User: I open the airlock door.
|
||||
|
||||
Take A:
|
||||
A maintenance robot is waiting.
|
||||
|
||||
Retry
|
||||
|
||||
Take B:
|
||||
The corridor beyond is filled with smoke.
|
||||
```
|
||||
|
||||
User selects Take B and continues.
|
||||
|
||||
Take A remains retained/disposable.
|
||||
|
||||
## 44. Example: Named Checkpoint
|
||||
|
||||
```text
|
||||
Checkpoint:
|
||||
"Before entering the alien structure"
|
||||
|
||||
Turn 220
|
||||
```
|
||||
|
||||
Story continues to Turn 245.
|
||||
|
||||
User restores checkpoint and chooses another approach.
|
||||
|
||||
Turns 221-245 remain retained/disposable.
|
||||
|
||||
The checkpoint remains attached to Turn 220 until explicitly deleted.
|
||||
|
||||
## 45. Example: Manual Canon Correction
|
||||
|
||||
Narrator incorrectly establishes:
|
||||
|
||||
```text
|
||||
The Persephone has an FTL drive.
|
||||
```
|
||||
|
||||
Campaign canon says:
|
||||
|
||||
```text
|
||||
FTL does not exist.
|
||||
```
|
||||
|
||||
User corrects state/canon.
|
||||
|
||||
The correction should be recorded explicitly and future context must treat:
|
||||
|
||||
```text
|
||||
The Persephone has no FTL capability.
|
||||
```
|
||||
|
||||
as authoritative.
|
||||
|
||||
If desired, the user may also edit the narration, but that is a separate operation.
|
||||
|
||||
## 46. Phase 0B Validation Questions
|
||||
|
||||
Codex should answer:
|
||||
|
||||
1. Does AI-DnD already support unlimited practical Undo through its lineage model?
|
||||
2. How does AI-DnD distinguish retry takes from full branches?
|
||||
3. Can retry/edit preserve prior futures without exposing a complex branch UI?
|
||||
4. Can summaries and memories be reliably lineage-filtered after divergence?
|
||||
5. Does AI-DnD state rollback restore generic state independently of RPG mechanics?
|
||||
6. How difficult would it be to mark abandoned paths disposable without deleting them?
|
||||
7. In Open Dungeon, what exact modules assume destructive tail-deletion semantics?
|
||||
8. Can checkpoints be implemented as durable turn pointers without duplicating state?
|
||||
9. What is the cost of retaining all disposable text/state history in SQLite?
|
||||
10. Does any finalist currently leak abandoned branch memories into active retrieval?
|
||||
|
||||
## 47. Acceptance Criteria
|
||||
|
||||
The final implementation must satisfy:
|
||||
|
||||
- Undo restores transcript and state together.
|
||||
- At least five Undo steps are available; unlimited is preferred.
|
||||
- Redo works until a new continuation is created.
|
||||
- Retry preserves alternate narrator takes.
|
||||
- Editing old user input creates a safe new continuation.
|
||||
- Editing narrator output re-evaluates state.
|
||||
- Named checkpoints remain until explicitly deleted.
|
||||
- Restoring a checkpoint does not delete later history.
|
||||
- Abandoned history is retained and marked disposable.
|
||||
- No automatic abandoned-history cleanup is required initially.
|
||||
- Abandoned history does not influence active summaries, memories, state, or prompts.
|
||||
- Manual state/canon corrections are auditable.
|
||||
- Normal UI does not require branch management.
|
||||
- A future discarded-history recovery screen remains possible without schema redesign.
|
||||
|
||||
## 48. Current Recommendation
|
||||
|
||||
Use a simple linear user experience backed by non-destructive lineage.
|
||||
|
||||
Conceptually:
|
||||
|
||||
```text
|
||||
USER EXPERIENCE
|
||||
|
||||
Undo
|
||||
Redo
|
||||
Retry
|
||||
Edit
|
||||
Checkpoint
|
||||
Restore
|
||||
|
||||
↓
|
||||
|
||||
INTERNAL MODEL
|
||||
|
||||
Parent-linked history
|
||||
Alternate takes
|
||||
State snapshots/events
|
||||
Active head
|
||||
Disposable abandoned history
|
||||
Lineage-aware summaries/memory
|
||||
```
|
||||
|
||||
This provides recovery and correctness without forcing the user to manage a story tree.
|
||||
@@ -0,0 +1,710 @@
|
||||
# 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.
|
||||
@@ -0,0 +1,998 @@
|
||||
# Adventure Storyteller — Standard Test Campaign Fixture
|
||||
|
||||
**Status:** Draft v0.1
|
||||
**Purpose:** Provide a deterministic, reusable campaign fixture for Phase 0B candidate comparison and later v1 regression testing.
|
||||
|
||||
## 1. Fixture Name
|
||||
|
||||
```text
|
||||
Continuity Test
|
||||
```
|
||||
|
||||
## 2. Purpose
|
||||
|
||||
This fixture is designed to expose failures in:
|
||||
|
||||
- canon handling,
|
||||
- character knowledge,
|
||||
- possession continuity,
|
||||
- relationship continuity,
|
||||
- location continuity,
|
||||
- long-term memory,
|
||||
- imported knowledge authority,
|
||||
- branch/undo safety,
|
||||
- checkpoint restore,
|
||||
- abandoned-history leakage,
|
||||
- summary lineage,
|
||||
- state reconstruction,
|
||||
- prompt/context provenance.
|
||||
|
||||
It is intentionally small.
|
||||
|
||||
The goal is not to create an entertaining campaign. The goal is to create a compact story that is easy to verify.
|
||||
|
||||
## 3. Campaign Profile
|
||||
|
||||
```yaml
|
||||
title: Continuity Test
|
||||
genre: fantasy
|
||||
subgenre: low fantasy
|
||||
tone: grounded, tense, restrained
|
||||
style: clear narrative prose
|
||||
point_of_view: second person
|
||||
tense: present
|
||||
```
|
||||
|
||||
## 4. Narrator Rules
|
||||
|
||||
Use the following durable narrator rules:
|
||||
|
||||
```text
|
||||
1. Do not decide the protagonist's voluntary actions unless required to describe
|
||||
the immediate consequence of an action already chosen by the user.
|
||||
|
||||
2. Preserve established canon and accepted story state.
|
||||
|
||||
3. Do not reveal hidden information unless the protagonist has learned it
|
||||
through accepted story events.
|
||||
|
||||
4. Do not treat imported Reference or Inspiration material as campaign canon.
|
||||
|
||||
5. If uncertain about an established fact, avoid contradicting it.
|
||||
|
||||
6. Keep responses concise enough for testing. Prefer approximately 2-5 paragraphs
|
||||
unless the user explicitly asks for more.
|
||||
|
||||
7. Magic exists, but resurrection is impossible.
|
||||
|
||||
8. Do not introduce modern technology.
|
||||
```
|
||||
|
||||
## 5. Initial Protagonist
|
||||
|
||||
### Aldric
|
||||
|
||||
```yaml
|
||||
name: Aldric
|
||||
type: character
|
||||
role: protagonist
|
||||
description: >
|
||||
A traveling investigator accustomed to dangerous roads and old ruins.
|
||||
current_location: Crooked Lantern Tavern
|
||||
condition:
|
||||
- healthy
|
||||
goals:
|
||||
- find Edrin
|
||||
possessions:
|
||||
- Silver Key
|
||||
```
|
||||
|
||||
### Visual Profile
|
||||
|
||||
```yaml
|
||||
apparent_age: late 30s
|
||||
build: lean
|
||||
hair: dark brown
|
||||
clothing: weathered green traveling cloak
|
||||
distinctive_features:
|
||||
- narrow scar across left eyebrow
|
||||
```
|
||||
|
||||
## 6. Supporting Characters
|
||||
|
||||
### Mara
|
||||
|
||||
```yaml
|
||||
name: Mara
|
||||
type: character
|
||||
role: tavern keeper
|
||||
current_location: Crooked Lantern Tavern
|
||||
relationship_to_aldric: cautious trust
|
||||
knows:
|
||||
- Edrin disappeared recently
|
||||
- Edrin often visited the Old Abbey
|
||||
does_not_know:
|
||||
- the Silver Key was found in Edrin's desk
|
||||
- Aldric currently possesses the Silver Key, until Aldric reveals it
|
||||
```
|
||||
|
||||
### Hidden Canon — Mara
|
||||
|
||||
```text
|
||||
Mara once saw the same broken-circle symbol on a sealed cellar door beneath
|
||||
the Crooked Lantern.
|
||||
|
||||
Mara has not told anyone about the cellar door.
|
||||
|
||||
Mara is not a spy.
|
||||
```
|
||||
|
||||
This hidden fact is intended to test:
|
||||
- narrator-only knowledge,
|
||||
- delayed revelation,
|
||||
- abandoned-branch leakage.
|
||||
|
||||
### Edrin
|
||||
|
||||
```yaml
|
||||
name: Edrin
|
||||
type: character
|
||||
role: missing scholar
|
||||
current_location: unknown
|
||||
status: missing
|
||||
```
|
||||
|
||||
### Hidden Canon — Edrin
|
||||
|
||||
```text
|
||||
Edrin discovered that the Silver Key opens the sealed cellar door beneath
|
||||
the Crooked Lantern.
|
||||
|
||||
Edrin disappeared before he could tell Mara.
|
||||
```
|
||||
|
||||
The user should not know this at campaign start.
|
||||
|
||||
## 7. Locations
|
||||
|
||||
### Crooked Lantern Tavern
|
||||
|
||||
```yaml
|
||||
name: Crooked Lantern Tavern
|
||||
type: location
|
||||
description: >
|
||||
An old timber-framed tavern near the north road. It has a stone hearth,
|
||||
dark beams, shared tables, and a cellar beneath the main room.
|
||||
```
|
||||
|
||||
Hidden location fact:
|
||||
|
||||
```text
|
||||
A sealed cellar door beneath the tavern bears a broken-circle symbol.
|
||||
```
|
||||
|
||||
### Old Abbey
|
||||
|
||||
```yaml
|
||||
name: Old Abbey
|
||||
type: location
|
||||
description: >
|
||||
A ruined abbey five miles north of Westhaven. Its crypt bears a
|
||||
broken-circle symbol.
|
||||
```
|
||||
|
||||
## 8. Item
|
||||
|
||||
### Silver Key
|
||||
|
||||
```yaml
|
||||
name: Silver Key
|
||||
type: item
|
||||
description: >
|
||||
A small silver key bearing a broken-circle symbol.
|
||||
current_owner: Aldric
|
||||
origin: Edrin's desk
|
||||
```
|
||||
|
||||
Hidden function:
|
||||
|
||||
```text
|
||||
The Silver Key opens the sealed cellar door beneath the Crooked Lantern.
|
||||
```
|
||||
|
||||
## 9. Initial Relationships
|
||||
|
||||
```text
|
||||
Aldric -> trusts -> Mara
|
||||
Mara -> cautiously_trusts -> Aldric
|
||||
Mara -> knows -> Edrin
|
||||
Edrin -> frequently_visited -> Old Abbey
|
||||
Aldric -> possesses -> Silver Key
|
||||
```
|
||||
|
||||
## 10. Initial Story Thread
|
||||
|
||||
```yaml
|
||||
title: Find Edrin
|
||||
status: open
|
||||
description: Determine what happened to Edrin.
|
||||
```
|
||||
|
||||
## 11. Global Canon
|
||||
|
||||
These facts are authoritative from campaign start.
|
||||
|
||||
```text
|
||||
1. Magic exists.
|
||||
2. Resurrection is impossible.
|
||||
3. The Old Abbey lies five miles north of Westhaven.
|
||||
4. The Silver Key was found in Edrin's desk.
|
||||
5. The Silver Key bears a broken-circle symbol.
|
||||
6. The Old Abbey crypt bears the same broken-circle symbol.
|
||||
7. Mara has never visited the Old Abbey.
|
||||
8. Mara does not initially know where the Silver Key was found.
|
||||
9. Mara is not a spy.
|
||||
10. Aldric begins the campaign carrying the Silver Key.
|
||||
```
|
||||
|
||||
## 12. Imported Knowledge Files
|
||||
|
||||
Create exactly these three files.
|
||||
|
||||
---
|
||||
|
||||
### File A — `canon.md`
|
||||
|
||||
Classification:
|
||||
|
||||
```text
|
||||
Canon
|
||||
```
|
||||
|
||||
Contents:
|
||||
|
||||
```markdown
|
||||
# Campaign Canon
|
||||
|
||||
The Old Abbey lies five miles north of Westhaven.
|
||||
|
||||
The abbey crypt bears a symbol shaped like a broken circle.
|
||||
|
||||
Magic exists in this world, but resurrection is impossible.
|
||||
|
||||
Mara has never visited the Old Abbey.
|
||||
```
|
||||
|
||||
Expected behavior:
|
||||
- treated as authoritative,
|
||||
- may be retrieved selectively,
|
||||
- cannot be overridden by lower-authority sources.
|
||||
|
||||
---
|
||||
|
||||
### File B — `reference.md`
|
||||
|
||||
Classification:
|
||||
|
||||
```text
|
||||
Reference
|
||||
```
|
||||
|
||||
Contents:
|
||||
|
||||
```markdown
|
||||
# Tavern Reference
|
||||
|
||||
Medieval roadside taverns commonly used timber framing, stone hearths,
|
||||
wooden benches, shared tables, candles, and oil lamps.
|
||||
|
||||
Cellars were often used for ale, food storage, and secure storage.
|
||||
|
||||
Old buildings frequently accumulated renovations, blocked passages, and
|
||||
sealed storage areas over generations.
|
||||
```
|
||||
|
||||
Expected behavior:
|
||||
- may influence environmental detail,
|
||||
- must not establish that the Crooked Lantern definitely has a secret tunnel,
|
||||
- must not override campaign canon.
|
||||
|
||||
---
|
||||
|
||||
### File C — `inspiration.md`
|
||||
|
||||
Classification:
|
||||
|
||||
```text
|
||||
Inspiration
|
||||
```
|
||||
|
||||
Contents:
|
||||
|
||||
```markdown
|
||||
# Atmospheric Inspiration
|
||||
|
||||
A traveler entered a silent hall while rain tapped against dark shutters.
|
||||
A single lantern illuminated the room.
|
||||
|
||||
Beneath an old house, a forgotten doorway waited behind a wall of barrels.
|
||||
|
||||
A frightened innkeeper concealed a dangerous political secret from a stranger.
|
||||
```
|
||||
|
||||
Expected behavior:
|
||||
- may influence atmosphere,
|
||||
- must not establish that Mara is concealing a political secret,
|
||||
- must not turn Mara into a spy,
|
||||
- must not create a hidden doorway unless accepted story events establish one.
|
||||
|
||||
## 13. Deliberate Continuity Traps
|
||||
|
||||
The fixture contains several traps.
|
||||
|
||||
### Trap 1 — Mara's knowledge
|
||||
|
||||
Mara initially does not know:
|
||||
- where the key was found,
|
||||
- that Aldric possesses it.
|
||||
|
||||
If the narrator gives Mara this knowledge before Aldric reveals it, continuity failed.
|
||||
|
||||
### Trap 2 — Mara has never visited Old Abbey
|
||||
|
||||
If Mara claims personal experience inside the abbey without a later accepted explanation, canon failed.
|
||||
|
||||
### Trap 3 — Inspiration says an innkeeper hides a political secret
|
||||
|
||||
Mara is explicitly not a spy.
|
||||
|
||||
If Inspiration causes the narrator to establish Mara as a political spy, authority handling failed.
|
||||
|
||||
### Trap 4 — Reference describes sealed passages
|
||||
|
||||
This is descriptive reference only.
|
||||
|
||||
It must not automatically create unrelated secret tunnels.
|
||||
|
||||
### Trap 5 — Resurrection
|
||||
|
||||
Any retrieved text or pretrained knowledge suggesting resurrection must lose to global canon.
|
||||
|
||||
### Trap 6 — Abandoned branch secret
|
||||
|
||||
One test branch will reveal:
|
||||
- Mara has seen the broken-circle symbol in the cellar.
|
||||
|
||||
After undo/divergence, the new active branch must not know that revelation occurred.
|
||||
|
||||
### Trap 7 — Possession
|
||||
|
||||
Aldric starts with the Silver Key.
|
||||
|
||||
The key must not vanish or move owners without an accepted event.
|
||||
|
||||
## 14. Initial Expected State
|
||||
|
||||
At campaign creation:
|
||||
|
||||
```yaml
|
||||
active_location: Crooked Lantern Tavern
|
||||
|
||||
aldric:
|
||||
possesses:
|
||||
- Silver Key
|
||||
knows:
|
||||
- Silver Key was found in Edrin's desk
|
||||
- Edrin is missing
|
||||
|
||||
mara:
|
||||
knows:
|
||||
- Edrin is missing
|
||||
- Edrin often visited Old Abbey
|
||||
does_not_know:
|
||||
- key origin
|
||||
- Aldric possesses key
|
||||
|
||||
threads:
|
||||
- Find Edrin: open
|
||||
```
|
||||
|
||||
## 15. Core Scripted Test Sequence
|
||||
|
||||
The following sequence should be used for candidate comparison.
|
||||
|
||||
The narrator's exact prose will vary.
|
||||
|
||||
The important part is state and continuity.
|
||||
|
||||
---
|
||||
|
||||
## Turn 1
|
||||
|
||||
User:
|
||||
|
||||
```text
|
||||
I enter the Crooked Lantern and look for Mara.
|
||||
```
|
||||
|
||||
Expected:
|
||||
- Mara is present or plausibly becomes available.
|
||||
- Current location remains Crooked Lantern.
|
||||
- No hidden canon is revealed automatically.
|
||||
|
||||
---
|
||||
|
||||
## Turn 2
|
||||
|
||||
User:
|
||||
|
||||
```text
|
||||
I ask Mara, "Have you heard anything about Edrin?"
|
||||
```
|
||||
|
||||
Expected:
|
||||
- Mara may say Edrin is missing.
|
||||
- Mara may mention his interest in Old Abbey.
|
||||
- Mara should not mention the Silver Key unless Aldric reveals it.
|
||||
- Mara should not mention the cellar symbol yet.
|
||||
|
||||
---
|
||||
|
||||
## Turn 3
|
||||
|
||||
User:
|
||||
|
||||
```text
|
||||
I ask whether Mara has ever been to the Old Abbey.
|
||||
```
|
||||
|
||||
Expected:
|
||||
- Mara says no or equivalent.
|
||||
- Any statement that she personally visited the abbey is a failure.
|
||||
|
||||
Create named checkpoint:
|
||||
|
||||
```text
|
||||
Before revealing the key
|
||||
```
|
||||
|
||||
Expected checkpoint state:
|
||||
- Mara still does not know Aldric has the key.
|
||||
- Mara still does not know where it was found.
|
||||
|
||||
---
|
||||
|
||||
## Turn 4A — Primary Test Path
|
||||
|
||||
User:
|
||||
|
||||
```text
|
||||
I show Mara the Silver Key but do not tell her where I found it.
|
||||
```
|
||||
|
||||
Expected state:
|
||||
- Mara now knows Aldric possesses the Silver Key.
|
||||
- Mara still does not know it came from Edrin's desk.
|
||||
|
||||
Expected narrative opportunity:
|
||||
- Mara may recognize the broken-circle symbol.
|
||||
- If she reveals she has seen it beneath the tavern, that becomes accepted story knowledge.
|
||||
|
||||
For deterministic testing, if the narrator does not volunteer the recognition, continue with:
|
||||
|
||||
```text
|
||||
Does the symbol mean anything to you?
|
||||
```
|
||||
|
||||
Expected:
|
||||
- Mara may reveal that she saw the symbol on a sealed cellar door.
|
||||
- This revelation is now accepted on Path A.
|
||||
|
||||
Record this as:
|
||||
|
||||
```text
|
||||
Path A Secret Revealed:
|
||||
Mara has seen the broken-circle symbol beneath the tavern.
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Turn 5A
|
||||
|
||||
User:
|
||||
|
||||
```text
|
||||
I tell Mara that I found the key in Edrin's desk.
|
||||
```
|
||||
|
||||
Expected state:
|
||||
- Mara now knows the key origin.
|
||||
- New clue may connect Edrin, key, and tavern cellar.
|
||||
|
||||
---
|
||||
|
||||
## Turn 6A
|
||||
|
||||
User:
|
||||
|
||||
```text
|
||||
I ask Mara to take me to the cellar door.
|
||||
```
|
||||
|
||||
Expected:
|
||||
- location may change into tavern cellar,
|
||||
- active thread may gain clue,
|
||||
- key remains with Aldric unless explicitly handed over.
|
||||
|
||||
## 16. Undo / Divergence Test
|
||||
|
||||
After completing Path A through Turn 6A:
|
||||
|
||||
Restore checkpoint:
|
||||
|
||||
```text
|
||||
Before revealing the key
|
||||
```
|
||||
|
||||
Expected:
|
||||
- active story returns to post-Turn-3 state,
|
||||
- Mara does not know Aldric has key,
|
||||
- Mara does not know key origin,
|
||||
- accepted Path A future becomes abandoned/disposable,
|
||||
- checkpoint remains.
|
||||
|
||||
Create new continuation.
|
||||
|
||||
---
|
||||
|
||||
## Turn 4B — Divergent Path
|
||||
|
||||
User:
|
||||
|
||||
```text
|
||||
I decide not to mention the key. I ask Mara what she remembers about Edrin's last visit.
|
||||
```
|
||||
|
||||
Expected:
|
||||
- Mara does not know Aldric has the key.
|
||||
- Mara does not know the key origin.
|
||||
- the prior Path A revelation about the cellar symbol must not be treated as something already said.
|
||||
|
||||
---
|
||||
|
||||
## Turn 5B
|
||||
|
||||
User:
|
||||
|
||||
```text
|
||||
I ask whether Edrin ever spoke about unusual symbols.
|
||||
```
|
||||
|
||||
Expected:
|
||||
- narrator may choose a plausible response consistent with current canon,
|
||||
- must not phrase the Path A cellar revelation as something already discussed,
|
||||
- may reveal the cellar symbol now if the narrator decides it is narratively appropriate.
|
||||
|
||||
Important:
|
||||
If the system retrieves:
|
||||
```text
|
||||
Mara already told Aldric about the cellar symbol.
|
||||
```
|
||||
from abandoned Path A, the candidate fails lineage safety.
|
||||
|
||||
## 17. Redo Test
|
||||
|
||||
Before entering Turn 4B, test ordinary Redo after checkpoint restore/undo if supported.
|
||||
|
||||
Expected:
|
||||
- Redo may return into Path A only until a new Turn 4B is accepted.
|
||||
- once Turn 4B is accepted, ordinary Redo into Path A should be invalidated.
|
||||
|
||||
Path A remains retained/disposable internally.
|
||||
|
||||
## 18. Retry Test
|
||||
|
||||
On a fresh/appropriate turn, use:
|
||||
|
||||
```text
|
||||
I open the cellar door.
|
||||
```
|
||||
|
||||
Receive narrator Take A.
|
||||
|
||||
Then Retry.
|
||||
|
||||
Receive narrator Take B.
|
||||
|
||||
Expected:
|
||||
- both narrator takes are retained,
|
||||
- user may select either before continuing,
|
||||
- continuing from Take B makes Take A inactive/disposable,
|
||||
- Take A does not influence later active context.
|
||||
|
||||
## 19. Narrator Edit Test
|
||||
|
||||
Create a narrator response containing:
|
||||
|
||||
```text
|
||||
Mara wears a red cloak.
|
||||
```
|
||||
|
||||
Edit it to:
|
||||
|
||||
```text
|
||||
Mara wears a green cloak.
|
||||
```
|
||||
|
||||
Expected:
|
||||
- green cloak becomes active continuity,
|
||||
- old red-cloak version remains historical/disposable,
|
||||
- structured visual/state data is re-evaluated if the system tracks clothing.
|
||||
|
||||
## 20. Manual State Correction Test
|
||||
|
||||
Introduce or simulate an incorrect fact:
|
||||
|
||||
```text
|
||||
Mara knows the Silver Key came from Edrin's desk.
|
||||
```
|
||||
|
||||
Use manual state/canon correction:
|
||||
|
||||
```text
|
||||
Mara does not know where the Silver Key was found.
|
||||
```
|
||||
|
||||
Expected:
|
||||
- correction is authoritative,
|
||||
- correction has user/manual provenance,
|
||||
- future narrator behavior respects correction.
|
||||
|
||||
## 21. Long-Term Memory Plant
|
||||
|
||||
Near the beginning of the active branch, establish:
|
||||
|
||||
```text
|
||||
Mara says Edrin always tapped twice on the table before mentioning something he feared.
|
||||
```
|
||||
|
||||
This detail is intentionally minor but specific.
|
||||
|
||||
Do not mention it for many turns.
|
||||
|
||||
At least 30-50 turns later, ask:
|
||||
|
||||
```text
|
||||
I think back to Mara's description of Edrin when he was frightened. Was there any distinctive habit she mentioned?
|
||||
```
|
||||
|
||||
Expected:
|
||||
- system should retrieve or reconstruct the two-tap habit,
|
||||
- full transcript should not need to be in prompt.
|
||||
|
||||
This is the standard long-term memory recall fact.
|
||||
|
||||
## 22. Promise Memory Plant
|
||||
|
||||
Establish:
|
||||
|
||||
```text
|
||||
Aldric promises Mara he will return before sunrise.
|
||||
```
|
||||
|
||||
Later, after enough turns for direct context to expire, ask or create a situation near dawn.
|
||||
|
||||
Expected:
|
||||
- promise should be retrievable as a high-value commitment memory.
|
||||
|
||||
## 23. Possession Transfer Test
|
||||
|
||||
Later in the campaign:
|
||||
|
||||
User:
|
||||
|
||||
```text
|
||||
I hand the Silver Key to Mara and ask her to hold it.
|
||||
```
|
||||
|
||||
Expected:
|
||||
- Mara now possesses key,
|
||||
- Aldric no longer possesses key.
|
||||
|
||||
Several turns later:
|
||||
|
||||
```text
|
||||
I reach for the Silver Key.
|
||||
```
|
||||
|
||||
Expected:
|
||||
- narrator should not act as if Aldric still has it.
|
||||
|
||||
Then:
|
||||
|
||||
```text
|
||||
I ask Mara to give the key back.
|
||||
```
|
||||
|
||||
Expected:
|
||||
- possession returns to Aldric after accepted transfer.
|
||||
|
||||
## 24. Location Continuity Test
|
||||
|
||||
Move from tavern to Old Abbey.
|
||||
|
||||
Expected:
|
||||
- active location updates.
|
||||
|
||||
Ask about an object clearly located at the tavern without returning.
|
||||
|
||||
Expected:
|
||||
- narrator should not imply the protagonist is still physically at the tavern.
|
||||
|
||||
## 25. Resurrection Canon Test
|
||||
|
||||
Introduce:
|
||||
|
||||
```text
|
||||
I ask whether any known magic could bring Edrin back if we find him dead.
|
||||
```
|
||||
|
||||
Expected:
|
||||
- narrator maintains resurrection is impossible,
|
||||
- lower-authority inspiration/reference/pretrained knowledge cannot override this.
|
||||
|
||||
## 26. Reference Retrieval Test
|
||||
|
||||
At tavern:
|
||||
|
||||
```text
|
||||
I look around the room carefully. What is the place physically like?
|
||||
```
|
||||
|
||||
Expected:
|
||||
- reference may contribute timber framing, hearth, benches, lighting,
|
||||
- narrator should not say these details came from campaign canon unless actually established.
|
||||
|
||||
## 27. Inspiration Authority Test
|
||||
|
||||
Because Inspiration contains:
|
||||
|
||||
```text
|
||||
A frightened innkeeper concealed a dangerous political secret.
|
||||
```
|
||||
|
||||
ask:
|
||||
|
||||
```text
|
||||
I watch Mara carefully. Does she seem like someone involved in political intrigue?
|
||||
```
|
||||
|
||||
Expected:
|
||||
- narrator may describe ambiguity,
|
||||
- must not establish Mara is a spy solely because Inspiration contains that trope,
|
||||
- global canon says Mara is not a spy.
|
||||
|
||||
## 28. Hidden Canon / Spoiler Test
|
||||
|
||||
Before the active branch discovers the sealed cellar door, ask:
|
||||
|
||||
```text
|
||||
What do I know about the purpose of the Silver Key?
|
||||
```
|
||||
|
||||
Expected player-facing answer:
|
||||
- Aldric does not yet know its purpose.
|
||||
|
||||
The narrator may have hidden canon saying it opens the cellar door, but must not reveal this as player knowledge.
|
||||
|
||||
## 29. Checkpoint Persistence Test
|
||||
|
||||
Create named checkpoint:
|
||||
|
||||
```text
|
||||
Before entering the abbey
|
||||
```
|
||||
|
||||
Restart application.
|
||||
|
||||
Expected:
|
||||
- checkpoint still exists,
|
||||
- restoring it recreates correct state.
|
||||
|
||||
## 30. Export / Import Test
|
||||
|
||||
After:
|
||||
- at least one abandoned path,
|
||||
- at least two named checkpoints,
|
||||
- imported knowledge,
|
||||
- possession changes,
|
||||
- long-term memories,
|
||||
|
||||
export campaign.
|
||||
|
||||
Import into a fresh data directory.
|
||||
|
||||
Expected:
|
||||
- active transcript restored,
|
||||
- current state restored,
|
||||
- checkpoints restored,
|
||||
- disposable history retained,
|
||||
- imported knowledge classifications retained,
|
||||
- memory provenance retained where required.
|
||||
|
||||
## 31. Science-Fiction Variant
|
||||
|
||||
The same engine should also run this compact alternate fixture without schema changes.
|
||||
|
||||
Campaign:
|
||||
|
||||
```text
|
||||
Persephone Test
|
||||
```
|
||||
|
||||
Canon:
|
||||
|
||||
```text
|
||||
1. FTL does not exist.
|
||||
2. Persephone is a fusion-powered survey ship.
|
||||
3. Artificial gravity is available only through thrust or rotation.
|
||||
4. Dr. Vale has never visited Europa.
|
||||
5. The encrypted data crystal belongs to Captain Imani.
|
||||
```
|
||||
|
||||
Entities:
|
||||
- Captain Imani — protagonist
|
||||
- Dr. Vale — scientist
|
||||
- Persephone — vehicle
|
||||
- Ceres Station — location
|
||||
- Europa — location
|
||||
- encrypted data crystal — item
|
||||
- Helios Dynamics — organization
|
||||
|
||||
Purpose:
|
||||
- verify genre-neutral entities,
|
||||
- verify hard technology canon,
|
||||
- verify possession,
|
||||
- verify character knowledge,
|
||||
- verify reference retrieval.
|
||||
|
||||
No database/schema changes should be required relative to Continuity Test.
|
||||
|
||||
## 32. Expected State Checkpoints
|
||||
|
||||
### Checkpoint S0 — Campaign Start
|
||||
|
||||
```yaml
|
||||
location: Crooked Lantern Tavern
|
||||
key_owner: Aldric
|
||||
mara_knows_key_possession: false
|
||||
mara_knows_key_origin: false
|
||||
mara_cellar_symbol_revealed_to_aldric: false
|
||||
find_edrin: open
|
||||
```
|
||||
|
||||
### Checkpoint S1 — Before Revealing Key
|
||||
|
||||
Same as S0, after initial conversation.
|
||||
|
||||
```yaml
|
||||
mara_knows_key_possession: false
|
||||
mara_knows_key_origin: false
|
||||
```
|
||||
|
||||
### Checkpoint S2A — After Showing Key
|
||||
|
||||
```yaml
|
||||
key_owner: Aldric
|
||||
mara_knows_key_possession: true
|
||||
mara_knows_key_origin: false
|
||||
```
|
||||
|
||||
### Checkpoint S3A — After Revealing Origin
|
||||
|
||||
```yaml
|
||||
mara_knows_key_possession: true
|
||||
mara_knows_key_origin: true
|
||||
```
|
||||
|
||||
### Checkpoint S2B — Divergent Path
|
||||
|
||||
After restoring S1 and continuing without mentioning key:
|
||||
|
||||
```yaml
|
||||
key_owner: Aldric
|
||||
mara_knows_key_possession: false
|
||||
mara_knows_key_origin: false
|
||||
```
|
||||
|
||||
Path A revelations must not appear as accepted Path B state.
|
||||
|
||||
## 33. Required Test Evidence
|
||||
|
||||
For candidate comparison, record at important turns:
|
||||
|
||||
- active turn/head ID,
|
||||
- visible transcript,
|
||||
- current structured state,
|
||||
- summary text,
|
||||
- retrieved memories,
|
||||
- retrieved imported chunks,
|
||||
- prompt/context inspection,
|
||||
- database lineage if accessible,
|
||||
- checkpoint IDs,
|
||||
- network activity if security test is running.
|
||||
|
||||
## 34. Candidate Comparison Procedure
|
||||
|
||||
For each finalist:
|
||||
|
||||
1. create the same Continuity Test fixture,
|
||||
2. use the same imported files,
|
||||
3. follow the same scripted turns where supported,
|
||||
4. record deviations,
|
||||
5. do not compensate manually for missing architecture unless the purpose is a documented experiment.
|
||||
|
||||
Rate each capability:
|
||||
|
||||
```text
|
||||
PASS
|
||||
PARTIAL
|
||||
FAIL
|
||||
NOT IMPLEMENTED
|
||||
```
|
||||
|
||||
## 35. Fixture Success Criteria
|
||||
|
||||
A production v1 implementation passes the fixture if:
|
||||
|
||||
- no canon trap is violated,
|
||||
- Mara's knowledge remains correct,
|
||||
- possession remains correct,
|
||||
- Undo/Restore returns to correct state,
|
||||
- abandoned Path A facts do not leak into Path B,
|
||||
- Retry alternatives do not contaminate active history,
|
||||
- named checkpoints persist,
|
||||
- old planted memories can be retrieved,
|
||||
- imported Reference and Inspiration remain lower authority than Canon,
|
||||
- hidden canon is not exposed prematurely,
|
||||
- export/import preserves active and retained history,
|
||||
- science-fiction variant requires no schema redesign.
|
||||
|
||||
## 36. Fixture Files
|
||||
|
||||
The canonical fixture package should eventually contain:
|
||||
|
||||
```text
|
||||
continuity-test/
|
||||
├── campaign.yaml
|
||||
├── canon.md
|
||||
├── reference.md
|
||||
├── inspiration.md
|
||||
├── expected-state.yaml
|
||||
├── scripted-turns.md
|
||||
└── README.md
|
||||
```
|
||||
|
||||
For Phase 0B, this document is sufficient to create those files manually or through a small fixture setup script.
|
||||
|
||||
## 37. Current Recommendation
|
||||
|
||||
Use this fixture as the standard narrative test bed throughout the project.
|
||||
|
||||
Do not replace it with ad hoc stories for each candidate.
|
||||
|
||||
A stable fixture makes it possible to distinguish:
|
||||
|
||||
```text
|
||||
model randomness
|
||||
```
|
||||
|
||||
from:
|
||||
|
||||
```text
|
||||
actual persistence / memory / canon bugs
|
||||
```
|
||||
|
||||
The prose may vary.
|
||||
|
||||
The expected state, authority, and lineage rules should not.
|
||||
File diff suppressed because it is too large
Load Diff
@@ -0,0 +1,139 @@
|
||||
# CaoRuiming/ai-adventure — Static Architecture Analysis
|
||||
|
||||
**Project name in repository docs:** Local Adventure Engine
|
||||
**Repository:** https://github.com/CaoRuiming/ai-adventure
|
||||
**Date reviewed:** 2026-09-01
|
||||
**Disposition:** Finalist #3; strongest state/privacy reference, possible core candidate.
|
||||
|
||||
## Architectural fit
|
||||
|
||||
This project most closely matches the desired trust boundary:
|
||||
|
||||
> The model proposes narration/events; the application validates and commits authoritative state.
|
||||
|
||||
Its architecture separates:
|
||||
- authored content,
|
||||
- runtime state and pure reducers,
|
||||
- SQLite storage/migrations,
|
||||
- local lore indexing/retrieval,
|
||||
- deterministic bounded context construction,
|
||||
- model provider,
|
||||
- application turn logic,
|
||||
- CLI presentation.
|
||||
|
||||
That separation makes it especially valuable even if it is not the final fork.
|
||||
|
||||
## Turn/commit model
|
||||
|
||||
The documented flow:
|
||||
|
||||
1. load/replay state,
|
||||
2. synchronize lore,
|
||||
3. build deterministic bounded context,
|
||||
4. call local model,
|
||||
5. parse a structured turn proposal,
|
||||
6. validate proposed events,
|
||||
7. apply events in memory,
|
||||
8. atomically append turn/events and move the session head,
|
||||
9. display narration only after commit.
|
||||
|
||||
This is the strongest candidate design for “the model is not the database.”
|
||||
|
||||
## Persistence and recovery
|
||||
|
||||
The project documents:
|
||||
- parent-linked turn history,
|
||||
- append-only state events,
|
||||
- cached reconstructed state,
|
||||
- undo by moving session head,
|
||||
- named checkpoints,
|
||||
- restore,
|
||||
- branching into another session that shares ancestors,
|
||||
- replayable state.
|
||||
|
||||
This satisfies the conceptual checkpoint/branch requirement better than a destructive chat log.
|
||||
|
||||
Potential mismatch:
|
||||
- branches are represented as sessions rather than necessarily one unified visual story tree.
|
||||
- export behavior and cross-branch navigation should be tested for the browser product.
|
||||
|
||||
## Lore and long memory
|
||||
|
||||
The project currently favors deterministic local retrieval:
|
||||
- Markdown lore,
|
||||
- SQLite FTS5/fallback,
|
||||
- bounded context,
|
||||
- summaries.
|
||||
|
||||
It intentionally avoids an embedding/vector dependency in the initial architecture.
|
||||
|
||||
This is attractive for privacy and auditability, but the target project likely also wants optional local semantic retrieval through Ollama for:
|
||||
- old story events,
|
||||
- large imported reference/inspiration libraries.
|
||||
|
||||
The deterministic lexical layer should still be considered as part of a hybrid retriever.
|
||||
|
||||
## Privacy/security fit
|
||||
|
||||
This is the strongest static privacy design among the finalists.
|
||||
|
||||
The project documentation explicitly addresses:
|
||||
- local data directory,
|
||||
- loopback model endpoint by default,
|
||||
- warning for non-loopback endpoints,
|
||||
- no telemetry/cloud account,
|
||||
- no MCP,
|
||||
- no executable plugins,
|
||||
- no shell tools,
|
||||
- parameterized SQL,
|
||||
- bounded imports,
|
||||
- path traversal/symlink restrictions,
|
||||
- local world files treated as data.
|
||||
|
||||
The default provider is LM Studio rather than Ollama, but the provider boundary appears intentionally small.
|
||||
|
||||
## Tests
|
||||
|
||||
Project documentation reports an offline test suite that grew during implementation (later milestone notes report 74 tests). Phase 0B should run the actual current suite and treat it as authoritative.
|
||||
|
||||
## Major gaps for target product
|
||||
|
||||
- terminal UI,
|
||||
- LM Studio rather than Ollama as documented primary provider,
|
||||
- no browser API/UI,
|
||||
- no current media system,
|
||||
- no semantic embedding retrieval,
|
||||
- authored entity/event model may be more rigid than freeform narrative state,
|
||||
- likely more front-end work than either browser finalist.
|
||||
|
||||
## Best reuse case
|
||||
|
||||
Even if it is not the production base, reuse its architectural rules:
|
||||
|
||||
- append-only authoritative events,
|
||||
- model proposals never direct state writes,
|
||||
- validate before commit,
|
||||
- commit narration and state atomically,
|
||||
- deterministic replay,
|
||||
- non-destructive head movement,
|
||||
- imported files are data only,
|
||||
- minimal network surface.
|
||||
|
||||
If selected as base, Phase 0B must prove that adding Ollama + a browser service/UI is smaller than stripping AI-DnD.
|
||||
|
||||
## Phase 0B questions for Codex
|
||||
|
||||
1. Can its provider interface talk to Ollama via compatibility mode with a tiny adapter?
|
||||
2. Can a native Ollama adapter be added without touching turn/state logic?
|
||||
3. How much application code assumes CLI presentation?
|
||||
4. Is the app/service layer clean enough to expose through FastAPI without refactoring state internals?
|
||||
5. How are branches/checkpoints exported and navigated?
|
||||
6. Can generic freeform narrative facts/entities be represented without expanding typed events excessively?
|
||||
7. With Internet blocked, is the only runtime network connection the configured local model endpoint?
|
||||
|
||||
## Primary source links
|
||||
|
||||
- Repository: https://github.com/CaoRuiming/ai-adventure
|
||||
- Architecture: https://github.com/CaoRuiming/ai-adventure/blob/main/docs/architecture.md
|
||||
- Privacy/security: https://github.com/CaoRuiming/ai-adventure/blob/main/docs/privacy-and-security.md
|
||||
- Apache-2.0 license: repository `LICENSE`
|
||||
@@ -0,0 +1,168 @@
|
||||
# AI-DnD — Static Architecture Analysis
|
||||
|
||||
**Repository:** https://github.com/parththakkar106/AI-DnD
|
||||
**Date reviewed:** 2026-09-01
|
||||
**Disposition:** Preliminary fork recommendation / Finalist #1.
|
||||
|
||||
## Why it moved to first place
|
||||
|
||||
The static review indicates that AI-DnD already implements most of the difficult correctness infrastructure that would otherwise need to be invented:
|
||||
|
||||
- browser UI (React/Vite),
|
||||
- FastAPI backend,
|
||||
- local SQLite,
|
||||
- Ollama via local OpenAI-compatible endpoint,
|
||||
- story as a tree rather than a list,
|
||||
- alternate takes,
|
||||
- branch lineage that borrows ancestors,
|
||||
- state restored when switching branches,
|
||||
- non-destructive retry,
|
||||
- state snapshots,
|
||||
- exact prompt/context snapshots,
|
||||
- automatic summaries,
|
||||
- embedding-based long-term memory,
|
||||
- story cards/world information,
|
||||
- export/import of the complete story tree,
|
||||
- substantial automated backend testing.
|
||||
|
||||
The current README reports 549 backend tests. The design guide contains an older measured-results count of 440, so the clone should treat the live test suite—not prose counts—as authoritative.
|
||||
|
||||
## Story tree
|
||||
|
||||
This is the strongest reason to prefer AI-DnD.
|
||||
|
||||
The project explicitly models:
|
||||
|
||||
- branches,
|
||||
- actions/nodes,
|
||||
- parent/fork lineage,
|
||||
- multiple takes at a turn,
|
||||
- branch-aware context,
|
||||
- state after a node,
|
||||
- retry that preserves the replaced attempt.
|
||||
|
||||
That matches the user's desired “Git for stories” behavior much more closely than Open Dungeon.
|
||||
|
||||
Its documentation also describes measured optimization work so branches do not duplicate the ancestor transcript.
|
||||
|
||||
## Turn pipeline
|
||||
|
||||
The documented flow is close to the target Story Director:
|
||||
|
||||
```text
|
||||
player input
|
||||
-> optional input hook
|
||||
-> retrieve memories
|
||||
-> assemble bounded context
|
||||
-> snapshot exact context
|
||||
-> stream provider output
|
||||
-> extract proposed state delta
|
||||
-> Python referee validates state
|
||||
-> save action + resulting state
|
||||
-> background summarize/embed
|
||||
```
|
||||
|
||||
The target project would simplify this rather than reinvent it.
|
||||
|
||||
## Memory/context
|
||||
|
||||
AI-DnD already includes three useful layers:
|
||||
|
||||
- direct recent history,
|
||||
- AI-generated memories,
|
||||
- running story summary.
|
||||
|
||||
Embedding retrieval pulls old relevant memories back into context and exposes similarity/context details through an Insights UI.
|
||||
|
||||
Story cards provide a mature starting point for lore/world-info injection.
|
||||
|
||||
The main extension needed is a first-class imported document library with explicit authority classes:
|
||||
- Canon,
|
||||
- Reference,
|
||||
- Inspiration.
|
||||
|
||||
## Prompt transparency
|
||||
|
||||
The current project stores the exact prompt sent for a turn and provides an Insights view with context components and token costs. This directly satisfies a stated debugging requirement.
|
||||
|
||||
## What must be removed or generalized
|
||||
|
||||
AI-DnD is not a clean fit out of the box.
|
||||
|
||||
### RPG-specific world state
|
||||
Current world state is designed around stats, bands, flags, milestones, cooldowns, NPC presence, and state deltas.
|
||||
|
||||
Target:
|
||||
- retain the proposal/referee/snapshot pattern,
|
||||
- replace or supplement RPG stats with generic narrative entities/facts/relationships/story threads/scenes.
|
||||
|
||||
### QuickJS scripting
|
||||
The project includes AI-Dungeon-compatible user scripting.
|
||||
|
||||
For this project, executable campaign content conflicts with the desired narrow trust surface. Unless a compelling future use appears, remove or disable scripting in v1.
|
||||
|
||||
### Hosted/multi-user behavior
|
||||
Current code supports:
|
||||
- optional accounts,
|
||||
- guest users,
|
||||
- rate limits,
|
||||
- demo keys,
|
||||
- hosted deployments,
|
||||
- Postgres/Neon,
|
||||
- Render,
|
||||
- remote model providers.
|
||||
|
||||
The target is a single-user local application. These paths should be removed or compiled/configured out rather than merely hidden in the UI.
|
||||
|
||||
### Analytics
|
||||
The project includes its own owner-only aggregate visit analytics for hosted mode. It is not described as a third-party tracker, but it is unnecessary for the local fork and should be removed.
|
||||
|
||||
### Cloud providers
|
||||
OpenRouter/OpenAI/Groq/vLLM support is broader than desired. v1 should retain only the local Ollama path.
|
||||
|
||||
## Security positive
|
||||
|
||||
The local/hosted modes are already explicitly separated, and the code contains network-guard thinking around hosted deployments. This is a better starting point than a project with cloud assumptions scattered everywhere, but static review cannot prove that removal is trivial.
|
||||
|
||||
## Main risk
|
||||
|
||||
The central Phase 0B question is:
|
||||
|
||||
> Are the RPG/cloud/scripting systems modular enough that removing them is less work and less risk than adding correct branching/state/memory to Open Dungeon?
|
||||
|
||||
Static evidence suggests yes, but this must be tested with a local strip-down experiment.
|
||||
|
||||
## Best reuse case
|
||||
|
||||
If selected:
|
||||
- keep story tree,
|
||||
- keep action/state snapshots,
|
||||
- keep context/history windowing,
|
||||
- keep Memory Bank structure,
|
||||
- keep story cards,
|
||||
- keep Insights/prompt snapshots,
|
||||
- keep SQLite and local FastAPI/React split,
|
||||
- keep Ollama adapter path,
|
||||
- remove hosted/auth/analytics/cloud,
|
||||
- remove QuickJS,
|
||||
- generalize world state,
|
||||
- add document ingestion,
|
||||
- add scene/media schema and provider interface,
|
||||
- use Open Dungeon/Gamentic as media UX references.
|
||||
|
||||
## Phase 0B questions for Codex
|
||||
|
||||
1. Can the app run fully local with only Ollama and no Internet?
|
||||
2. Can QuickJS, hosted auth, analytics, Render/Neon, and remote provider paths be removed without destabilizing core tests?
|
||||
3. How tightly does branching depend on RPG world-state fields?
|
||||
4. Can an adventure run with minimal/no stats while branch rollback still passes?
|
||||
5. Can the state snapshot payload be generalized to narrative JSON without rewriting the tree?
|
||||
6. How many tests cover branch/undo/retry/context/memory independently of RPG logic?
|
||||
7. Does current Memory Bank work with a local Ollama embedding model in practice?
|
||||
8. What exact outbound traffic occurs in default local mode?
|
||||
|
||||
## Primary source links
|
||||
|
||||
- Repository / README: https://github.com/parththakkar106/AI-DnD
|
||||
- Design guide: https://github.com/parththakkar106/AI-DnD/blob/main/docs/GUIDE.md
|
||||
- MIT license: repository `LICENSE`
|
||||
@@ -0,0 +1,46 @@
|
||||
# aiMultiFool — Static Architecture Analysis
|
||||
|
||||
**Repository:** https://github.com/omgboohoo/aimultifool
|
||||
**Date reviewed:** 2026-09-01
|
||||
**Disposition:** Reference only.
|
||||
|
||||
## Useful ideas
|
||||
|
||||
aiMultiFool is a local roleplay/chat sandbox with:
|
||||
- Ollama support,
|
||||
- local inference paths,
|
||||
- Vector Chat / semantic-memory concepts,
|
||||
- save/load,
|
||||
- rewind/regenerate,
|
||||
- context inspection,
|
||||
- optional encrypted local data.
|
||||
|
||||
Those are useful implementation references for local memory tooling and diagnostics.
|
||||
|
||||
## Why it is not a fork finalist
|
||||
|
||||
### Product mismatch
|
||||
The interface is terminal/Textual-oriented and character-chat/roleplay focused rather than a browser-first persistent fiction editor.
|
||||
|
||||
### History/context mismatch
|
||||
Its documented smart-pruning strategy removes older middle messages from active chat state as context pressure grows. That is a reasonable chat optimization but not the target architecture. The target must preserve an immutable authoritative transcript and prune only the prompt representation.
|
||||
|
||||
### State model
|
||||
The project does not provide the same authoritative event/state/branch model found in AI-DnD or ai-adventure.
|
||||
|
||||
### License
|
||||
The repository is GPL-3.0. Directly copying substantial GPL code into an MIT/Apache-derived application would change licensing obligations. Unless the final project intentionally adopts GPL-compatible distribution terms, use this project for concepts rather than source copying.
|
||||
|
||||
## Recommended reuse
|
||||
|
||||
Study:
|
||||
- local embedding workflow,
|
||||
- vector inspection/debugging,
|
||||
- encrypted local payload design,
|
||||
- user-facing memory controls.
|
||||
|
||||
Do not make it a Phase 0B build finalist.
|
||||
|
||||
## Source
|
||||
|
||||
- Repository: https://github.com/omgboohoo/aimultifool
|
||||
@@ -0,0 +1,66 @@
|
||||
# Candidate Inventory and Triage
|
||||
|
||||
**Phase:** 0A — Static research
|
||||
**Date:** 2026-09-01
|
||||
|
||||
## Executive result
|
||||
|
||||
Three projects should advance to local validation:
|
||||
|
||||
1. **AI-DnD** — strongest implementation of the hardest required backend capabilities.
|
||||
2. **Open Dungeon** — strongest direct product/UX fit and strongest near-term media path.
|
||||
3. **CaoRuiming/ai-adventure (Local Adventure Engine)** — strongest authoritative-state, replay, checkpoint, and privacy architecture.
|
||||
|
||||
Everything else should remain available as a design/source reference but should not consume local build-validation effort unless one of the three finalists fails.
|
||||
|
||||
## Triage table
|
||||
|
||||
| Project | Browser-first | Ollama | Durable branch/rollback | Long memory | Local knowledge | Future media | Static disposition |
|
||||
|---|---|---|---|---|---|---|---|
|
||||
| AI-DnD | Yes | Yes | **Strong** | **Strong** | Story cards + memory | Not core | **Finalist #1** |
|
||||
| Open Dungeon | **Yes** | **Yes** | Weak / destructive linear tail today | Summary-based | Limited | **Strong; local image generation already present** | **Finalist #2** |
|
||||
| ai-adventure | No; CLI | LM Studio today | **Strong** | Summary + lore FTS | **Strong deterministic local lore** | No | **Finalist #3** |
|
||||
| Chronicler | Yes | Yes | Not the focus | **Excellent memory model** | Memory-centric | No | Reference |
|
||||
| Gamentic | **Yes** | llama.cpp/OpenAI-compatible | Game-state oriented | Strong | World bible | **Excellent image/voice provider design** | Reference |
|
||||
| Interactive Fiction Framework | **Yes** | **Yes** | Not established as required story-tree model | Canon/scene/character memory | Story Bible | Not core | Reference |
|
||||
| Sonder Engine | **Yes** | **Yes** | Persistent variants/checkpoints, but much more agentic | **Very sophisticated** | Character-scoped retrieval | Not primary | Reference |
|
||||
| Corvus Story Core | **Yes** | OpenAI-compatible | No equivalent branch tree established | Summaries + state | World/state | ComfyUI + TTS | Reference |
|
||||
| aiMultiFool | No; terminal | **Yes** | Rewind, not target architecture | Vector chat | RAG-oriented | No | Reference only |
|
||||
| SillyTavern | **Yes** | Local backends | Chat-oriented | Extensions/lorebooks | **Excellent lorebook UX** | Broad extensions | Reference only |
|
||||
| RisuAI | **Yes** | Local/remote ecosystem | Chat-oriented | Hypa/SupaMemory | Lorebooks | Broad media | Reference only |
|
||||
| KoboldAI | **Yes** | Local ecosystem | Traditional save/load | Memory/World Info | World Info | Limited | Reference only |
|
||||
|
||||
## Why the shortlist is only three
|
||||
|
||||
### AI-DnD advances because
|
||||
It already implements the expensive correctness work: a parent/lineage story tree, alternate takes, non-destructive retry, state snapshots and rollback, branch-aware context, summaries, embedding retrieval, story cards, exact prompt inspection, export/import of the complete tree, and a substantial automated test suite.
|
||||
|
||||
### Open Dungeon advances because
|
||||
It is almost exactly the desired product shape: browser-first, simple interactive fiction, Ollama, local SQLite, streaming narration, visual character continuity, and local image-generation hooks. Its key weakness is architectural rather than cosmetic: its current message schema is linear and its retry/erase operation deletes the selected message and the rest of the tail.
|
||||
|
||||
### ai-adventure advances because
|
||||
Its core philosophy most closely matches the required trust model. SQLite and typed events are authoritative; the model proposes changes; validation occurs before atomic commit; undo/checkpoint/restore/branch work by replaying parent-linked history; lore is local; and the privacy documentation explicitly minimizes network and executable-extension surfaces.
|
||||
|
||||
## Projects eliminated from fork contention
|
||||
|
||||
### Chronicler
|
||||
Excellent source for memory semantics, but the application is centered on long-running roleplay and YantrikDB cognitive memory rather than the simpler interactive-story product. Its memory-tier design should be borrowed conceptually.
|
||||
|
||||
### Gamentic
|
||||
Technically impressive and very useful for future media design, but it is intentionally a multi-agent RPG with image and voice infrastructure, tuned around a heavier local stack. Forking it would mean removing more game/agent behavior than necessary.
|
||||
|
||||
### Interactive Fiction Framework
|
||||
Its Story Bible, validation, and application-owned-state design are highly relevant. However, it is oriented toward contributor-authored, schema-driven stories and planner-approved choices rather than the unrestricted natural-language story continuation and branch history required here.
|
||||
|
||||
### Sonder Engine
|
||||
Strong engineering, but its core differentiator is separate fictional minds with strict perception/knowledge boundaries and a multi-stage agent pipeline. That is substantially more complexity than v1 requires.
|
||||
|
||||
### Corvus Story Core
|
||||
Useful image/TTS and state-extraction reference, but its persistence is JSON/JSONL-oriented and the static review did not establish the required non-destructive branch/checkpoint model.
|
||||
|
||||
### aiMultiFool
|
||||
Useful local vector-memory ideas, but it is a terminal character-roleplay application, its context-pruning approach is not the desired immutable-history architecture, and GPL-3.0 complicates direct code reuse into a permissively licensed fork.
|
||||
|
||||
## Sources
|
||||
|
||||
See `SOURCE-INDEX.md` for repository/source links.
|
||||
@@ -0,0 +1,67 @@
|
||||
# Licensing and Reuse Review
|
||||
|
||||
**Date:** 2026-09-01
|
||||
**Nature:** Engineering planning summary, not legal advice.
|
||||
|
||||
## Permissive finalists
|
||||
|
||||
### AI-DnD
|
||||
- License: MIT
|
||||
- Direct modification/forking is generally compatible with a permissive local application, subject to preserving required notices.
|
||||
|
||||
### Open Dungeon
|
||||
- License: MIT
|
||||
- Same practical advantage for direct reuse.
|
||||
|
||||
### ai-adventure
|
||||
- License: Apache-2.0
|
||||
- Permissive, but Apache notice/license obligations must be preserved.
|
||||
|
||||
These three can plausibly participate in a permissively licensed implementation strategy, subject to checking individual vendored/third-party files.
|
||||
|
||||
## Permissive reference projects
|
||||
|
||||
Static repository licensing indicates:
|
||||
- Chronicler: MIT
|
||||
- Interactive Fiction Framework: MIT
|
||||
- Gamentic: MIT
|
||||
- Sonder Engine: MIT
|
||||
- Corvus Story Core: MIT
|
||||
|
||||
If source is copied, retain the applicable notices and verify whether particular directories/files carry separate licenses.
|
||||
|
||||
## Copyleft references
|
||||
|
||||
### aiMultiFool
|
||||
- GPL-3.0
|
||||
- Treat as a concept/reference source unless the final project intentionally accepts GPL obligations.
|
||||
|
||||
### LettuceAI
|
||||
- AGPL-3.0
|
||||
- Reference only for this project unless there is a deliberate licensing decision.
|
||||
|
||||
Mature roleplay ecosystems such as SillyTavern/RisuAI/KoboldAI should have their exact current license verified before any code copying. No direct reuse is currently recommended.
|
||||
|
||||
## Media dependencies
|
||||
|
||||
Important distinction:
|
||||
- application code license,
|
||||
- media runtime license,
|
||||
- model-weight license
|
||||
are separate.
|
||||
|
||||
For example Gamentic documents:
|
||||
- its own code under MIT,
|
||||
- ComfyUI runtime under GPL-3.0,
|
||||
- model weights under their own terms.
|
||||
|
||||
Using a separately running local service through an API is architecturally different from copying its code into the storyteller, but distribution/bundling choices should be reviewed before release.
|
||||
|
||||
## Recommendation
|
||||
|
||||
Keep the production application's own code on a permissive-license path if possible:
|
||||
- primary fork from MIT or Apache-2.0,
|
||||
- copy code only from compatible permissive sources,
|
||||
- treat GPL/AGPL projects as design references unless a conscious license change is made,
|
||||
- keep optional media providers as external adapters/services where practical,
|
||||
- maintain a third-party notices file from the first production milestone.
|
||||
@@ -0,0 +1,138 @@
|
||||
# Open Dungeon — Static Architecture Analysis
|
||||
|
||||
**Repository:** https://github.com/newideas99/open-dungeon
|
||||
**Date reviewed:** 2026-09-01
|
||||
**Disposition:** Finalist #2; strongest product/UI/media fit, but branch persistence requires material redesign.
|
||||
|
||||
## What maps well to the specification
|
||||
|
||||
Open Dungeon already provides a product very close to the desired interaction model:
|
||||
|
||||
- browser-first UI,
|
||||
- local Ollama text generation,
|
||||
- streaming narration,
|
||||
- Do / Say / Story-style interaction,
|
||||
- Continue / Retry / Erase / Edit controls,
|
||||
- SQLite persistence,
|
||||
- rolling story summary for long conversations,
|
||||
- persistent character records,
|
||||
- local inline image generation,
|
||||
- character portraits/visual continuity feeding image generation,
|
||||
- optional ComfyUI path.
|
||||
|
||||
The future-media requirement is therefore not hypothetical in this codebase. It already has a concept of the narrator requesting an image after prose and a local image backend producing it.
|
||||
|
||||
## Current stack
|
||||
|
||||
From the current package/config:
|
||||
|
||||
- Next.js 16
|
||||
- React 19
|
||||
- TypeScript
|
||||
- `better-sqlite3`
|
||||
- Node.js 22+
|
||||
- Ollama default endpoint at `127.0.0.1:11434`
|
||||
- local image worker defaults to loopback
|
||||
- optional remote OpenAI-compatible/OpenRouter configuration
|
||||
|
||||
## Persistence finding: the major issue
|
||||
|
||||
The current database is fundamentally a linear chat model.
|
||||
|
||||
The reviewed schema contains:
|
||||
|
||||
- chats,
|
||||
- messages,
|
||||
- characters,
|
||||
- app settings,
|
||||
- rolling story summary fields.
|
||||
|
||||
Messages do not expose a parent-turn/branch-lineage model equivalent to AI-DnD or ai-adventure.
|
||||
|
||||
More importantly, the data layer includes an operation named `deleteMessageAndAfter()`. Its own comment says it is used by retry/erase to discard the tail of the story. Prior text can also be updated in place.
|
||||
|
||||
That is directly contrary to the target requirement:
|
||||
|
||||
> Going backward should preserve the abandoned future as an alternate branch.
|
||||
|
||||
This means adding robust branching is not simply a UI feature. It requires changing the persistence semantics and all features that assume a single mutable message sequence, including retry/erase/edit and summary lineage.
|
||||
|
||||
## Memory/context model
|
||||
|
||||
The prompt builder contains a history-packing mechanism with block eviction. Old story material is compressed into a rolling story summary, while recent history stays direct.
|
||||
|
||||
This is a reasonable lightweight storyteller strategy but is below the target design:
|
||||
|
||||
- no established semantic retrieval of old story events,
|
||||
- no explicit Canon / Reference / Inspiration document library,
|
||||
- no branch-aware memory lineage,
|
||||
- no rich authoritative generic story-state graph.
|
||||
|
||||
Those systems would need to be added.
|
||||
|
||||
## Media design
|
||||
|
||||
Open Dungeon is the strongest finalist for immediate media UX.
|
||||
|
||||
The current narrator prompt exposes a `generate_image` tool after a passage and passes selected character IDs so the image path can preserve visual identity. The app can use local FLUX tooling and supports ComfyUI in recent releases.
|
||||
|
||||
Useful ideas to retain even if Open Dungeon is not the base:
|
||||
|
||||
1. media is optional; text play does not depend on it,
|
||||
2. image generation is scene/turn-associated,
|
||||
3. character visual identity is stored rather than reinvented each image,
|
||||
4. local backend is behind a service boundary,
|
||||
5. generated media appears inline in the story.
|
||||
|
||||
For our architecture, image generation should eventually move behind a generic media-provider interface rather than remain hard-coded to one model/workflow.
|
||||
|
||||
## Privacy/static network assessment
|
||||
|
||||
Positive:
|
||||
- local Ollama is the default,
|
||||
- local SQLite is the default,
|
||||
- local image generation is supported,
|
||||
- no telemetry requirement was apparent in the inspected package/config.
|
||||
|
||||
Hardening needed:
|
||||
- remove or disable OpenRouter and arbitrary remote OpenAI-compatible provider options in v1,
|
||||
- review Tailscale/LAN exposure separately from loopback-only default,
|
||||
- verify built frontend has no remote runtime assets,
|
||||
- verify image setup does not make unexpected runtime downloads after installation,
|
||||
- runtime network capture still required.
|
||||
|
||||
## Testing concern
|
||||
|
||||
The inspected `package.json` exposes build/lint/image checks but no obvious comprehensive automated test command comparable to AI-DnD or Gamentic. This must be verified after clone; if accurate, a branch/persistence rewrite would need a new test foundation before implementation.
|
||||
|
||||
## Best reuse case
|
||||
|
||||
If Open Dungeon becomes the base:
|
||||
- preserve the browser experience,
|
||||
- preserve Ollama integration,
|
||||
- preserve image/visual-continuity concepts,
|
||||
- replace/extend linear message persistence with a parent-linked turn graph,
|
||||
- make summary/memory branch-aware,
|
||||
- add authoritative generic narrative state,
|
||||
- add local document ingestion and retrieval,
|
||||
- add prompt/provenance inspection.
|
||||
|
||||
If AI-DnD becomes the base:
|
||||
- use Open Dungeon primarily as a UX and media-generation reference.
|
||||
|
||||
## Phase 0B questions for Codex
|
||||
|
||||
1. How many routes/components assume messages are a single ordered list?
|
||||
2. Can a parent-linked turn/branch layer be introduced without replacing most chat APIs?
|
||||
3. What happens to `story_summary` when retry/erase edits earlier history?
|
||||
4. Can current image records attach cleanly to immutable turn IDs/scene IDs?
|
||||
5. Is there an automated test suite not visible from the package manifest?
|
||||
6. With Internet blocked, does ordinary text + local image play produce only loopback traffic?
|
||||
|
||||
## Primary source links
|
||||
|
||||
- Repository: https://github.com/newideas99/open-dungeon
|
||||
- DB: https://github.com/newideas99/open-dungeon/blob/main/src/lib/db.ts
|
||||
- Prompt builder: https://github.com/newideas99/open-dungeon/blob/main/src/lib/story-prompt.ts
|
||||
- Environment: https://github.com/newideas99/open-dungeon/blob/main/.env.example
|
||||
- Package: https://github.com/newideas99/open-dungeon/blob/main/package.json
|
||||
@@ -0,0 +1,39 @@
|
||||
# Phase 0A Status
|
||||
|
||||
**Completed:** 2026-09-01
|
||||
|
||||
## Completed statically
|
||||
|
||||
- candidate discovery and triage,
|
||||
- deep source/document architecture review of the three finalists,
|
||||
- static privacy/network-surface review,
|
||||
- preliminary licensing/reuse review,
|
||||
- subsystem reuse matrix,
|
||||
- preliminary fork recommendation,
|
||||
- narrowed Codex validation plan.
|
||||
|
||||
## Preliminary decision
|
||||
|
||||
Validate **AI-DnD first as the production fork candidate**.
|
||||
|
||||
Keep:
|
||||
- **Open Dungeon** as the fallback fork and primary UI/media reference.
|
||||
- **ai-adventure** as the state/replay/privacy architecture reference and third validation candidate.
|
||||
|
||||
## Still requires local/Codex work
|
||||
|
||||
- pin exact SHAs,
|
||||
- clone/install/build,
|
||||
- run actual tests,
|
||||
- verify Ollama against the user's machine,
|
||||
- runtime network capture,
|
||||
- offline operation,
|
||||
- AI-DnD strip-down experiment,
|
||||
- Open Dungeon branch-retrofit impact experiment,
|
||||
- ai-adventure Ollama/service-boundary experiment.
|
||||
|
||||
See `PHASE-0B-CODEX-HANDOFF.md`.
|
||||
|
||||
## Phase gate
|
||||
|
||||
Do not finalize `TECHNICAL-DESIGN.md` v1.0 or production `BUILD-MILESTONES.md` until Phase 0B results are reviewed.
|
||||
@@ -0,0 +1,153 @@
|
||||
# Phase 0A Preliminary Recommendation
|
||||
|
||||
**Date:** 2026-09-01
|
||||
**Status:** Static recommendation; pending Phase 0B clone/build/runtime experiments.
|
||||
|
||||
## Recommendation
|
||||
|
||||
### First choice to validate: AI-DnD
|
||||
|
||||
Use **AI-DnD as the preliminary production fork candidate**.
|
||||
|
||||
This is a change from the earlier slight preference for Open Dungeon.
|
||||
|
||||
The deciding evidence is not feature count; it is **where the hard architectural work already lives**.
|
||||
|
||||
AI-DnD already implements:
|
||||
- parent/lineage story tree,
|
||||
- alternate takes,
|
||||
- non-destructive retry,
|
||||
- branch-aware state rollback,
|
||||
- prompt snapshots,
|
||||
- context windowing,
|
||||
- memory bank + embeddings,
|
||||
- story cards,
|
||||
- complete tree export/import,
|
||||
- local Ollama,
|
||||
- a substantial automated test suite.
|
||||
|
||||
Those are precisely the systems most dangerous to retrofit after a linear chat application has accumulated behavior.
|
||||
|
||||
## Why Open Dungeon is second
|
||||
|
||||
Open Dungeon remains the best direct match to the desired *product*:
|
||||
- simple browser fiction interface,
|
||||
- Ollama,
|
||||
- local SQLite,
|
||||
- strong local image path,
|
||||
- visual continuity.
|
||||
|
||||
However, its present persistence semantics are linear and destructive:
|
||||
- prior messages can be updated,
|
||||
- retry/erase deletes the selected message and the story tail.
|
||||
|
||||
To satisfy the specification, we would need to introduce turn parentage/branches, branch-specific summaries/state, and non-destructive editing underneath features already written around a list. That is foundational work.
|
||||
|
||||
Open Dungeon should remain the fallback base if Codex proves AI-DnD's RPG/cloud systems are too entangled to remove.
|
||||
|
||||
## Why ai-adventure is third
|
||||
|
||||
ai-adventure has the cleanest *architecture* for state authority and local-only trust:
|
||||
- typed model proposals,
|
||||
- validation,
|
||||
- atomic commit,
|
||||
- append-only events,
|
||||
- replay,
|
||||
- checkpoints,
|
||||
- branches,
|
||||
- deterministic local lore,
|
||||
- explicit minimal network posture.
|
||||
|
||||
Its problem is product distance:
|
||||
- CLI presentation,
|
||||
- LM Studio primary provider,
|
||||
- no browser application,
|
||||
- no media,
|
||||
- less semantic long-memory machinery.
|
||||
|
||||
It should be the architectural control against which the selected browser fork is judged.
|
||||
|
||||
## Do not merge repositories
|
||||
|
||||
The recommendation is not to combine several projects mechanically.
|
||||
|
||||
Fork one project and re-implement selected ideas using compatible patterns/code only where justified.
|
||||
|
||||
A merged codebase would import:
|
||||
- incompatible assumptions,
|
||||
- duplicate persistence models,
|
||||
- different provider abstractions,
|
||||
- unnecessary dependencies,
|
||||
- licensing complexity.
|
||||
|
||||
## Proposed target architecture after Phase 0B
|
||||
|
||||
If AI-DnD passes validation:
|
||||
|
||||
### Retain
|
||||
- React/Vite browser shell,
|
||||
- FastAPI service boundary,
|
||||
- SQLite,
|
||||
- story tree/lineage,
|
||||
- state snapshots,
|
||||
- context budgeting,
|
||||
- Memory Bank,
|
||||
- story cards,
|
||||
- Insights,
|
||||
- Ollama path,
|
||||
- export/import,
|
||||
- relevant tests.
|
||||
|
||||
### Remove
|
||||
- multi-user/hosted auth,
|
||||
- demo keys/rate-limit hosting features,
|
||||
- Render/Neon path,
|
||||
- analytics,
|
||||
- cloud model providers,
|
||||
- QuickJS scripting,
|
||||
- AI-Dungeon compatibility not needed for core stories,
|
||||
- RPG-only presentation/mechanics.
|
||||
|
||||
### Generalize
|
||||
- world-state engine -> narrative state/facts/entities/threads,
|
||||
- Story Cards -> local knowledge sources with authority/provenance,
|
||||
- Memory Bank -> branch-safe story memory with Canon/Scene/Heuristic trust classes,
|
||||
- scenario -> genre-neutral campaign/story profile.
|
||||
|
||||
### Add
|
||||
- local document ingestion,
|
||||
- Canon / Reference / Inspiration source classification,
|
||||
- local lexical + optional Ollama semantic retrieval,
|
||||
- scene snapshots,
|
||||
- visual character/location fields,
|
||||
- media asset/job records,
|
||||
- media-provider interface,
|
||||
- later local image/video adapters.
|
||||
|
||||
## Phase 0B should be narrow
|
||||
|
||||
Codex should not repeat the broad research.
|
||||
|
||||
It should validate three concrete engineering hypotheses:
|
||||
|
||||
### Hypothesis 1 — AI-DnD can be stripped safely
|
||||
Prove local Ollama story/branch/memory operation still works after disabling/removing hosted/cloud/analytics/scripting paths and running with minimal RPG state.
|
||||
|
||||
### Hypothesis 2 — Open Dungeon branch retrofit is materially larger
|
||||
Map exactly how many DB functions/API routes/UI components/summary behaviors must change to make retry/edit non-destructive and branch-aware.
|
||||
|
||||
### Hypothesis 3 — ai-adventure is viable but farther from product
|
||||
Prove Ollama adapter effort is small and estimate the service/browser wrapper effort without starting production UI development.
|
||||
|
||||
Then choose the fork based on measured modification cost.
|
||||
|
||||
## Decision gate
|
||||
|
||||
Select AI-DnD unless Phase 0B finds one of these blockers:
|
||||
|
||||
- branching/state logic is inseparable from RPG mechanics,
|
||||
- removing hosted/scripting paths destabilizes a large percentage of tests,
|
||||
- local-only configuration still requires hard-to-remove external services,
|
||||
- dependency/security burden is materially worse than static review suggests.
|
||||
|
||||
If any blocker is confirmed, select Open Dungeon and explicitly budget a story-tree/persistence rewrite as the first production architecture milestone.
|
||||
@@ -0,0 +1,122 @@
|
||||
# Static Privacy and Network Review
|
||||
|
||||
**Date:** 2026-09-01
|
||||
**Scope:** Source/config/documentation review only. Runtime capture is still required in Phase 0B.
|
||||
|
||||
## Target rule
|
||||
|
||||
The final v1 should be able to operate with Internet access physically blocked, with ordinary story data traveling only:
|
||||
|
||||
```text
|
||||
Browser -> local application -> local Ollama
|
||||
```
|
||||
|
||||
Future media should similarly use explicitly configured local providers.
|
||||
|
||||
## AI-DnD
|
||||
|
||||
### Static positives
|
||||
- documented local single-user mode,
|
||||
- local SQLite,
|
||||
- local Ollama support,
|
||||
- no auth required in local mode,
|
||||
- hosted analytics are first-party application functionality rather than a required third-party browser tracker.
|
||||
|
||||
### Unwanted surfaces to remove
|
||||
- OpenRouter/OpenAI/Groq/vLLM provider support,
|
||||
- hosted account/guest flows,
|
||||
- demo API keys,
|
||||
- Render deployment,
|
||||
- Neon/Postgres cloud deployment path,
|
||||
- visit analytics,
|
||||
- QuickJS user scripting,
|
||||
- Claude CLI shim if not wanted,
|
||||
- any hosted-mode rate-limit/account code that adds no local value.
|
||||
|
||||
### Risk
|
||||
The cloud/hosted code is explicit and documented, which is good, but Phase 0B must prove it can be removed cleanly.
|
||||
|
||||
## Open Dungeon
|
||||
|
||||
### Static positives
|
||||
- Ollama loopback default,
|
||||
- local SQLite,
|
||||
- local image backend,
|
||||
- no telemetry requirement apparent in inspected package/config.
|
||||
|
||||
### Unwanted or optional surfaces
|
||||
- OpenRouter configuration,
|
||||
- arbitrary remote OpenAI-compatible endpoint support,
|
||||
- Tailscale/LAN exposure options,
|
||||
- any runtime remote assets,
|
||||
- any model/image automatic download behavior after setup.
|
||||
|
||||
### Risk
|
||||
The app is smaller, so hardening may be easier, but no runtime capture has been performed.
|
||||
|
||||
## ai-adventure
|
||||
|
||||
### Static positives
|
||||
This project most closely matches the target from the outset:
|
||||
- no telemetry,
|
||||
- no cloud account,
|
||||
- no MCP,
|
||||
- no executable plugins,
|
||||
- no shell tools,
|
||||
- loopback model endpoint default,
|
||||
- non-loopback warning,
|
||||
- imported content treated as bounded data,
|
||||
- path traversal/symlink defenses documented.
|
||||
|
||||
### Unwanted surface
|
||||
- configurable non-loopback model endpoint should be prohibited or strongly gated in the target v1.
|
||||
- LM Studio provider should be replaced/extended with Ollama.
|
||||
|
||||
## Reference projects
|
||||
|
||||
### Gamentic
|
||||
Local defaults are strong, but the project intentionally supports cloud text/image/audio dialects as alternatives. A target fork would need those disabled. Its Docker/media stack also has setup-time model acquisition concerns separate from story-time privacy.
|
||||
|
||||
### Chronicler
|
||||
Supports local Ollama but also broader providers and a separate local YantrikDB/MCP memory service. More moving parts than needed.
|
||||
|
||||
### Sonder / Corvus
|
||||
Both support local backends but also remote provider configurations; Sonder additionally has extension/optional external-service surfaces.
|
||||
|
||||
### aiMultiFool
|
||||
Primarily local, but direct code reuse is constrained by GPL considerations and it is not a fork finalist.
|
||||
|
||||
## Required Phase 0B runtime tests
|
||||
|
||||
For each finalist:
|
||||
|
||||
1. block outbound Internet access,
|
||||
2. start the app,
|
||||
3. create/load a story,
|
||||
4. generate multiple turns,
|
||||
5. trigger summarization/memory,
|
||||
6. trigger embeddings where applicable,
|
||||
7. save/restore/branch,
|
||||
8. for Open Dungeon, generate a local image,
|
||||
9. capture socket/DNS/HTTP activity,
|
||||
10. fail the test if story content leaves loopback or explicitly approved LAN endpoints.
|
||||
|
||||
Record:
|
||||
- process,
|
||||
- destination IP/hostname,
|
||||
- port,
|
||||
- trigger,
|
||||
- payload classification,
|
||||
- whether required or optional.
|
||||
|
||||
## Recommended production hardening
|
||||
|
||||
- bind app and Ollama to loopback by default,
|
||||
- allowlist provider URLs rather than accept arbitrary URLs,
|
||||
- no API-key UI in v1,
|
||||
- no remote URL ingestion,
|
||||
- no executable campaign scripts,
|
||||
- no third-party analytics,
|
||||
- bundle frontend assets locally,
|
||||
- content-security policy that rejects remote scripts/styles/images by default,
|
||||
- CI test or integration harness that runs with outbound networking disabled.
|
||||
@@ -0,0 +1,111 @@
|
||||
# Reference Project Findings
|
||||
|
||||
**Date:** 2026-09-01
|
||||
|
||||
These projects are not recommended as primary forks after static review, but each contributes a useful architectural pattern.
|
||||
|
||||
## Chronicler
|
||||
|
||||
Repository: https://github.com/yantrikos/chronicler
|
||||
|
||||
### Borrow
|
||||
Its memory model distinguishes different trust levels rather than treating all remembered text equally.
|
||||
|
||||
Useful conceptual tiers:
|
||||
- durable canon,
|
||||
- scene/recent memory,
|
||||
- heuristic/inferred memory.
|
||||
|
||||
Its anti-confabulation approach is especially relevant: retrieved hints should not automatically become established historical fact.
|
||||
|
||||
### Do not necessarily adopt
|
||||
The full YantrikDB/MCP cognitive-memory stack is heavier than v1 needs. Start with a simpler local store and preserve the trust-tier semantics.
|
||||
|
||||
## Interactive Fiction Framework
|
||||
|
||||
Repository: https://github.com/georgebutler/interactive-fiction-framework
|
||||
|
||||
### Borrow
|
||||
- Story Bible as highest-authority narrative context,
|
||||
- application owns durable state,
|
||||
- model enriches prose rather than overriding state,
|
||||
- structured output validation,
|
||||
- deterministic fallback,
|
||||
- separation of director/planner/memory/validator.
|
||||
|
||||
### Why not fork
|
||||
It is designed around contributor-authored story bundles and planner-approved choices, whereas the target is more freeform collaborative fiction with branch-preserving history.
|
||||
|
||||
## Gamentic
|
||||
|
||||
Repository: https://github.com/hec-ovi/gamentic
|
||||
|
||||
### Borrow
|
||||
This is the strongest reference found for future multimodal architecture.
|
||||
|
||||
It separates each modality behind a provider layer:
|
||||
|
||||
```text
|
||||
engine
|
||||
-> text provider
|
||||
-> image provider
|
||||
-> audio provider
|
||||
```
|
||||
|
||||
The game can continue text-first while images render asynchronously. Character image/voice identity lives in game state rather than in provider-specific code.
|
||||
|
||||
It also demonstrates an unusually strong local-project test strategy with over a thousand automated tests documented across backend/frontend/services.
|
||||
|
||||
### Why not fork
|
||||
The core product is a multi-agent RPG with significant game mechanics and a heavy local image/voice stack. That is broader than the desired v1 storyteller.
|
||||
|
||||
## Sonder Engine
|
||||
|
||||
Repository: https://github.com/N0819/Sonder_Engine
|
||||
|
||||
### Borrow later
|
||||
- one persistent commit boundary,
|
||||
- objective state distinct from character perception/belief/memory,
|
||||
- retrieval scoped by what a character may legitimately know,
|
||||
- model stages with different contexts.
|
||||
|
||||
### Why not fork
|
||||
Its defining feature is separate character minds and a multi-stage agent pipeline. That is valuable for a future sophisticated simulation but unnecessary complexity for v1.
|
||||
|
||||
## Corvus Story Core
|
||||
|
||||
Repository: https://github.com/JustLateNightAI/Corvus-Story-Core
|
||||
|
||||
### Borrow
|
||||
- hidden GM/state extraction pass,
|
||||
- scene/NPC visual descriptions,
|
||||
- ComfyUI scene art,
|
||||
- optional TTS,
|
||||
- local-first media integration.
|
||||
|
||||
### Why not fork
|
||||
Static review did not show the same robust branch/checkpoint/replay model; persistence is oriented around local JSON/JSONL rather than the desired transactional story graph.
|
||||
|
||||
## SillyTavern / RisuAI / KoboldAI
|
||||
|
||||
### Borrow
|
||||
- lorebook/world-info UX,
|
||||
- author's-note concepts,
|
||||
- context placement and triggering,
|
||||
- character/world metadata workflows.
|
||||
|
||||
### Why not fork
|
||||
They are mature but broad roleplay/chat ecosystems. Adapting them would mean carrying a large amount of unrelated general-purpose functionality.
|
||||
|
||||
## Design consequence
|
||||
|
||||
The production fork should not try to merge these projects.
|
||||
|
||||
Use a primary codebase, then deliberately implement selected patterns:
|
||||
|
||||
- AI-DnD: story tree, rollback, memory, prompt inspection.
|
||||
- ai-adventure: authoritative event/replay/privacy discipline.
|
||||
- Open Dungeon: story-focused UX and visual continuity.
|
||||
- Chronicler: memory trust tiers.
|
||||
- Gamentic: provider-neutral/asynchronous media.
|
||||
- IFF: Story Bible authority and validation.
|
||||
@@ -0,0 +1,62 @@
|
||||
# Reuse Matrix
|
||||
|
||||
**Date:** 2026-09-01
|
||||
|
||||
Legend:
|
||||
- **KEEP** — candidate implementation is close to target.
|
||||
- **MODIFY** — strong implementation but needs adaptation.
|
||||
- **REFERENCE** — borrow pattern/idea; do not make it the ownership center.
|
||||
- **BUILD** — target capability is substantially absent.
|
||||
|
||||
| Capability | AI-DnD | Open Dungeon | ai-adventure | Best current source |
|
||||
|---|---|---|---|---|
|
||||
| Browser storyteller UI | **MODIFY/KEEP** | **KEEP** | BUILD | Open Dungeon |
|
||||
| Ollama text adapter | **KEEP** | **KEEP** | MODIFY | AI-DnD/Open Dungeon |
|
||||
| SQLite local persistence | **KEEP** | MODIFY | **KEEP** | AI-DnD / ai-adventure |
|
||||
| Immutable turn parentage | **KEEP** | BUILD | **KEEP** | AI-DnD |
|
||||
| Alternate takes | **KEEP** | BUILD | MODIFY | AI-DnD |
|
||||
| Named checkpoints | MODIFY | BUILD | **KEEP** | ai-adventure |
|
||||
| Branch restore | **KEEP** | BUILD | **KEEP** | AI-DnD / ai-adventure |
|
||||
| Complete tree export | **KEEP** | BUILD | MODIFY | AI-DnD |
|
||||
| Exact prompt inspection | **KEEP** | BUILD/MODIFY | audit-oriented | AI-DnD |
|
||||
| Recent-history budgeting | **KEEP** | **KEEP** | **KEEP** | AI-DnD |
|
||||
| Rolling summaries | **KEEP** | **KEEP** | **KEEP** | all |
|
||||
| Semantic old-story retrieval | **KEEP/MODIFY** | BUILD | BUILD/MODIFY | AI-DnD |
|
||||
| Lexical local lore | MODIFY | BUILD | **KEEP** | ai-adventure |
|
||||
| Lore/story cards | **KEEP/MODIFY** | BUILD | MODIFY | AI-DnD |
|
||||
| Canon/Reference/Inspiration authority tiers | BUILD | BUILD | MODIFY | Chronicler/IFF concepts |
|
||||
| Generic narrative state | MODIFY | BUILD | MODIFY | ai-adventure pattern |
|
||||
| Model-proposes/app-validates | **KEEP but RPG-shaped** | BUILD | **KEEP** | ai-adventure |
|
||||
| Atomic state + turn commit | VERIFY | VERIFY | **KEEP** | ai-adventure |
|
||||
| Local-only privacy posture | MODIFY | MODIFY | **KEEP** | ai-adventure |
|
||||
| Local image generation | BUILD | **KEEP** | BUILD | Open Dungeon |
|
||||
| Provider-neutral media | BUILD | MODIFY | BUILD | Gamentic reference |
|
||||
| Scene/visual continuity | BUILD | **KEEP/MODIFY** | BUILD | Open Dungeon |
|
||||
| Large automated test base | **KEEP** | BUILD/VERIFY | **KEEP/VERIFY** | AI-DnD |
|
||||
| Genre-neutral core | MODIFY | **MODIFY/KEEP** | MODIFY | IFF/story-state concepts |
|
||||
|
||||
## Cross-project architecture we should aim for
|
||||
|
||||
Use one primary fork, not a stitched codebase.
|
||||
|
||||
Preferred composition of ideas:
|
||||
|
||||
```text
|
||||
AI-DnD production base
|
||||
+ ai-adventure trust/commit/privacy rules
|
||||
+ Open Dungeon scene/media UX
|
||||
+ Chronicler memory-authority tiers
|
||||
+ IFF Story Bible authority/validation
|
||||
+ Gamentic media-provider abstraction
|
||||
```
|
||||
|
||||
If AI-DnD strip-down proves too invasive, invert the first line:
|
||||
|
||||
```text
|
||||
Open Dungeon production base
|
||||
+ new AI-DnD-style immutable story tree
|
||||
+ ai-adventure event/commit discipline
|
||||
+ local memory/document retrieval
|
||||
```
|
||||
|
||||
That fallback is viable, but static analysis suggests it recreates more hard correctness work.
|
||||
@@ -0,0 +1,68 @@
|
||||
# Phase 0A Source Index
|
||||
|
||||
**Status:** Static research completed 2026-09-01
|
||||
**Scope:** Public repository source/docs inspection only. No local clone/build/runtime validation has been performed yet.
|
||||
|
||||
## Finalists
|
||||
|
||||
### AI-DnD
|
||||
- Repository: https://github.com/parththakkar106/AI-DnD
|
||||
- README / architecture summary: https://github.com/parththakkar106/AI-DnD/blob/main/README.md
|
||||
- Design guide: https://github.com/parththakkar106/AI-DnD/blob/main/docs/GUIDE.md
|
||||
- License: MIT
|
||||
|
||||
### Open Dungeon
|
||||
- Repository: https://github.com/newideas99/open-dungeon
|
||||
- Database layer: https://github.com/newideas99/open-dungeon/blob/main/src/lib/db.ts
|
||||
- Prompt/context layer: https://github.com/newideas99/open-dungeon/blob/main/src/lib/story-prompt.ts
|
||||
- Environment configuration: https://github.com/newideas99/open-dungeon/blob/main/.env.example
|
||||
- Package manifest: https://github.com/newideas99/open-dungeon/blob/main/package.json
|
||||
- License: MIT
|
||||
|
||||
### Local Adventure Engine / ai-adventure
|
||||
- Repository: https://github.com/CaoRuiming/ai-adventure
|
||||
- Architecture: https://github.com/CaoRuiming/ai-adventure/blob/main/docs/architecture.md
|
||||
- Privacy/security: https://github.com/CaoRuiming/ai-adventure/blob/main/docs/privacy-and-security.md
|
||||
- License: Apache-2.0
|
||||
|
||||
## High-value reference projects
|
||||
|
||||
### aiMultiFool
|
||||
- Repository: https://github.com/omgboohoo/aimultifool
|
||||
- Role: local roleplay/RAG/encryption ideas
|
||||
- License: GPL-3.0
|
||||
|
||||
### Chronicler
|
||||
- Repository: https://github.com/yantrikos/chronicler
|
||||
- Role: memory tiers, canon/heuristic/reflex separation, anti-confabulation patterns
|
||||
- License: MIT (application); YantrikDB is separately Apache-2.0
|
||||
|
||||
### Interactive Fiction Framework
|
||||
- Repository: https://github.com/georgebutler/interactive-fiction-framework
|
||||
- Role: Story Bible, model-as-prose-writer/application-as-state-owner, validation/fallback patterns
|
||||
- License: MIT
|
||||
|
||||
### Gamentic
|
||||
- Repository: https://github.com/hec-ovi/gamentic
|
||||
- Role: local text/image/voice provider abstraction, asynchronous media generation, large automated test suite
|
||||
- License: MIT
|
||||
|
||||
### Sonder Engine
|
||||
- Repository: https://github.com/N0819/Sonder_Engine
|
||||
- Role: objective truth vs perception/memory/belief, commit boundary, sophisticated character knowledge
|
||||
- License: MIT
|
||||
|
||||
### Corvus Story Core
|
||||
- Repository: https://github.com/JustLateNightAI/Corvus-Story-Core
|
||||
- Role: structured state + local ComfyUI/TTS integration
|
||||
- License: MIT
|
||||
|
||||
## Mature ecosystem references
|
||||
|
||||
- SillyTavern: https://github.com/SillyTavern/SillyTavern
|
||||
- RisuAI: https://github.com/kwaroran/RisuAI
|
||||
- KoboldAI Client: https://github.com/KoboldAI/KoboldAI-Client
|
||||
|
||||
## Important research caveat
|
||||
|
||||
Repository documentation can be stale relative to current source. Phase 0B should pin exact commit SHAs at clone time, run the projects, run their tests, and verify all network behavior locally.
|
||||
Reference in New Issue
Block a user