Phase 7: MIT license, portfolio README, Docker, cross-platform start
- LICENSE: MIT - README: rewritten as portfolio-grade docs (features with code pointers, architecture, Docker/Windows/macOS quick starts, BYO-model table) - Dockerfile (3-stage: SPA build, pip wheels, slim runtime) + compose with a /data volume; .dockerignore keeps secrets and local data out - database.py: AIDND_DB_PATH env override so deployments can relocate the SQLite file; documented in backend/.env.example - start.sh: macOS/Linux dev script with first-run setup Verified locally: production SPA build served by the backend (deep links OK), DB created at the override path. Docker image itself untested here (Docker not installed); flagged in plan/07. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01KFsGHju9szibJJa2YJcdbg
This commit is contained in:
parththakkar106
co-authored by
Claude Fable 5
Claude Fable 5
parent
466d7bc0e4
commit
22630c8411
@@ -1,54 +1,119 @@
|
||||
# AI D&D — local AI Dungeon-style storytelling app
|
||||
# AI D&D
|
||||
|
||||
Python (FastAPI + SQLite) backend, React (Vite) frontend, connectable to any
|
||||
OpenAI-compatible AI endpoint (Ollama, LM Studio, OpenAI, OpenRouter, …).
|
||||
An AI Dungeon-style interactive storytelling app you can run entirely on your own machine —
|
||||
with your own AI model. Create scenarios, play open-ended adventures where an LLM narrates the
|
||||
world, and extend the engine with **JavaScript scripts compatible with real AI Dungeon
|
||||
scripting**.
|
||||
|
||||
Plan: see [`plan/00-OVERVIEW.md`](plan/00-OVERVIEW.md). Currently completed: **Phase 4** (AI Dungeon-compatible scripting).
|
||||
Built with FastAPI + SQLite on the backend and React (Vite) on the frontend. Works with **any
|
||||
OpenAI-compatible endpoint**: Ollama and LM Studio locally, or OpenRouter / OpenAI / Groq / vLLM
|
||||
in the cloud — endpoint, key, and model are all runtime settings, and OpenRouter's free-tier
|
||||
models make the whole experience $0.
|
||||
|
||||
## Run
|
||||
> 📸 *Screenshots and a demo GIF are coming; for now the fastest tour is running it — one
|
||||
> command with Docker.*
|
||||
|
||||
## Features
|
||||
|
||||
- **The full play loop** — Do / Say / Story / Continue actions, streamed AI responses (SSE),
|
||||
retry, undo, and edit. Reasoning models supported: "thinking" streams into a collapsible 💭
|
||||
panel with its own token budget.
|
||||
- **AI Dungeon-compatible context engine** — memory, author's note, and story cards (world
|
||||
info) triggered by keywords in recent story text, assembled under a token budget
|
||||
(`backend/app/context/builder.py`).
|
||||
- **Insights: total prompt transparency** — every turn stores the exact prompt sent to the
|
||||
model; open 🔍 on any AI action to see each context component and why it was included.
|
||||
- **JavaScript scripting, AI Dungeon-compatible** — `onInput` / `onModelContext` / `onOutput`
|
||||
modifiers with shared `state` and a `worldEntries` API, executed in an embedded quickjs
|
||||
sandbox (`backend/app/scripting/`). Real AI Dungeon scripts import and run. In-app
|
||||
CodeMirror editor included.
|
||||
- **Auto-summarization + Memory Bank** — the modern AI Dungeon memory system: AI-generated
|
||||
memories every few actions, a running story summary, and embedding-based retrieval that
|
||||
pulls old-but-relevant facts back into context, with similarity scores visible in Insights
|
||||
(`backend/app/memorybank.py`).
|
||||
- **Import/export** — AI Dungeon-compatible formats for scripts and scenarios; JSON for
|
||||
everything.
|
||||
|
||||
## Quick start
|
||||
|
||||
### Docker (any OS)
|
||||
|
||||
```sh
|
||||
docker compose up --build
|
||||
```
|
||||
|
||||
Open http://localhost:8000. Your data persists in a named volume across restarts.
|
||||
|
||||
### Windows
|
||||
|
||||
```powershell
|
||||
cd backend; python -m venv .venv; .\.venv\Scripts\pip.exe install -r requirements.txt; cd ..
|
||||
cd frontend; npm install; cd ..
|
||||
.\start.ps1
|
||||
```
|
||||
|
||||
Then open http://localhost:5173. Backend API docs at http://localhost:8000/docs.
|
||||
Open http://localhost:5173 (dev servers; API docs at http://localhost:8000/docs).
|
||||
|
||||
Or manually, in two terminals:
|
||||
### macOS / Linux
|
||||
|
||||
```powershell
|
||||
# Terminal 1 — backend
|
||||
cd backend
|
||||
.\.venv\Scripts\uvicorn.exe app.main:app --port 8000 --reload
|
||||
|
||||
# Terminal 2 — frontend
|
||||
cd frontend
|
||||
npm run dev
|
||||
```sh
|
||||
./start.sh # creates the venv and installs dependencies on first run
|
||||
```
|
||||
|
||||
## First-time setup
|
||||
Open http://localhost:5173.
|
||||
|
||||
```powershell
|
||||
cd backend
|
||||
python -m venv .venv
|
||||
.\.venv\Scripts\pip.exe install -r requirements.txt
|
||||
## Connect a model
|
||||
|
||||
cd ..\frontend
|
||||
npm install
|
||||
Open **Settings** in the app and point it at any OpenAI-compatible endpoint:
|
||||
|
||||
| Provider | Endpoint URL | Notes |
|
||||
|---|---|---|
|
||||
| Ollama (local) | `http://localhost:11434/v1` | free, private; also serves embedding models for the Memory Bank (e.g. `nomic-embed-text`) |
|
||||
| LM Studio (local) | `http://localhost:1234/v1` | free, private |
|
||||
| OpenRouter | `https://openrouter.ai/api/v1` | `:free` models cost nothing (no embeddings on the free tier) |
|
||||
| OpenAI / Groq / vLLM / … | provider's `/v1` URL | anything speaking `/v1/chat/completions` |
|
||||
|
||||
Model name, API key, generation parameters, and (optionally) summary/embedding models for the
|
||||
Memory Bank are all configured there too — no config files, no rebuild.
|
||||
|
||||
## How a turn works
|
||||
|
||||
```
|
||||
player input
|
||||
→ onInput script modifier
|
||||
→ assemble context: [AI instructions] + [plot essentials] + [story summary]
|
||||
+ [retrieved memories] + [triggered story cards]
|
||||
+ [story history, token-budgeted] + [author's note] + [player action]
|
||||
→ onModelContext script modifier
|
||||
→ snapshot context (Insights)
|
||||
→ provider adapter → AI (streamed)
|
||||
→ onOutput script modifier
|
||||
→ store & render
|
||||
```
|
||||
|
||||
## Production-ish serving (single port)
|
||||
## Architecture
|
||||
|
||||
Build the frontend, then the backend serves it statically:
|
||||
|
||||
```powershell
|
||||
cd frontend
|
||||
npm run build
|
||||
# then run the backend and open http://localhost:8000
|
||||
```
|
||||
frontend/ React + Vite SPA ──HTTP/SSE──► backend/ FastAPI
|
||||
├─ routers/ scenarios, adventures, story cards, scripts, settings, debug
|
||||
├─ models.py SQLAlchemy: Scenario, Adventure, Action, StoryCard, Script, Settings, Memory
|
||||
├─ context/ prompt assembly under a token budget
|
||||
├─ scripting/ quickjs sandbox + AI Dungeon API surface
|
||||
├─ memorybank.py auto-summarization + embedding retrieval
|
||||
├─ providers/ OpenAI-compatible adapter, streaming
|
||||
└─ data.db SQLite (path overridable via AIDND_DB_PATH)
|
||||
```
|
||||
|
||||
## Layout
|
||||
In production the backend serves the built SPA from one port (see `Dockerfile`); in
|
||||
development Vite proxies `/api` to FastAPI.
|
||||
|
||||
- `backend/app/` — FastAPI app: `models.py` (SQLAlchemy), `schemas.py` (Pydantic), `routers/`
|
||||
- `backend/data.db` — SQLite database (created on first run)
|
||||
- `frontend/src/` — React SPA: `pages/`, `api.js`
|
||||
- `plan/` — phased implementation plan
|
||||
## Repo notes
|
||||
|
||||
- `plan/` — the phased implementation plan this was built from, kept as a build log
|
||||
(phases 1–6 complete; 7–10 cover the public release).
|
||||
- `backend/.env.example` — the few environment variables the backend reads.
|
||||
- `CODE_REVIEW_FINDINGS.md` — notes from a self-review pass.
|
||||
|
||||
## License
|
||||
|
||||
[MIT](LICENSE)
|
||||
|
||||
Reference in New Issue
Block a user