142 lines
5.0 KiB
Markdown
142 lines
5.0 KiB
Markdown
# CaoRuiming/ai-adventure — Static Architecture Analysis
|
|
|
|
**Historical status:** Static Phase 0A analysis. Phase 0B promoted ai-adventure to the primary implementation reference for state/event/head/checkpoint semantics, but not the production base.
|
|
|
|
**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`
|