Add initial planning files from ChatGPT research here
This commit is contained in:
JesseMarkowitz
@@ -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`
|
||||
Reference in New Issue
Block a user