lishehao/RPG_Demo
lishehao/RPG_Demo has 59 GitHub stars and 6 forks. GitHot measured 0 stars in 24 hours. Last checked 2026-11-17 00:22 UTC. Last push 2026-11-14.
Measured star growth
- in 24h
- 0
- in 7 days
- Collecting history
- in 15 days
- Collecting history
- in 1 month
- Collecting history
Net star changes over overlapping periods, not daily totals. Missing measurements are left blank. Stars measure attention, not software quality.
About
Tiny Stories: an interactive story system. One premise becomes a 12-turn story of choices or free actions, with saved sessions, replay, and a reviewer view.
AIREADME.md
OriginalTiny Stories
An interactive story system: one premise becomes a 12-turn story of choices or free actions, with saved sessions, replay, and a reviewer view of each turn's state.
RPG Demo repository · 中文
Demo

A 27-second silent loop from a live local run. Waits for the model are cut. This run used gpt-4.1-mini in place of DeepSeek V4 Flash.
Longer walkthrough:
- Watch the 75s demo on YouTube
- MP4 copy of the same cut, for places where YouTube is blocked
- GitHub Pages site and its static reviewer demo
The reviewer demo on GitHub Pages is a static, deterministic build: no API
key, no backend, and no live generation. The GitHub Pages copy can lag behind
main.
Why
The project asks one question: can an LLM story generator feel like a designed game loop instead of a chat window?
The target player wants a short story on a phone, not a blank writing canvas or an endless feed. Each turn has the same rhythm: read the scene, compare a few moves (or type your own action), act once, see what changed, then use that consequence to pick the next move. The LLM writes the prose; the code around it decides what each turn has to deal with, keeps the state, and records the run so it can be replayed and inspected.
How to run
Requirements:
- Python 3.11+
- Node
^20.19.0 || >=22.12.0(required by Vite 7, whichfrontend2/uses) - For live play only: an OpenAI-compatible chat/completions endpoint and key
Install from a fresh clone:
git clone https://github.com/lishehao/RPG_Demo.git
cd RPG_Demo
python3 -m venv .venv
source .venv/bin/activate
python3 -m pip install -e ".[dev]"
cd frontend2
npm install
cd ..
Without a key (offline mode)
APP_LLM_MODE=fake replaces the narrative LLM with the canned fake gateway
that tools/narrative_release_gate.py uses, and seeds one public story
("The Ledger Room") on startup so there is something to play.
APP_LLM_MODE=fake \
APP_RUNTIME_STATE_DB_PATH=artifacts/offline_runtime_state.sqlite3 \
uvicorn rpg_backend.main:app --host 127.0.0.1 --port 8000
In another terminal:
cd frontend2
npm run dev
Open http://127.0.0.1:8001 (the port is fixed in frontend2/vite.config.ts;
the dev server proxies API calls to http://127.0.0.1:8000). Pick the seeded
story and play.
Offline mode is for trying the UI and API flow. Every turn returns the same canned text, so it says nothing about writing quality. The separate database path keeps the fake story out of your live database.
With a key (live play)
cp .env.example .env
# Fill in:
# APP_RESPONSES_PLAY_BASE_URL=...
# APP_RESPONSES_PLAY_API_KEY=...
# APP_RESPONSES_PLAY_MODEL=...
uvicorn rpg_backend.main:app --host 127.0.0.1 --port 8000 --reload
Then start frontend2 with npm run dev as above and open
http://127.0.0.1:8001. .env.example lists the other settings. With no key
and no APP_LLM_MODE, the backend still starts, but /narrative/templates
is empty and nothing is playable.
Checks
python3 -m pytest -q
python3 tools/narrative_release_gate.py --mode fake
cd frontend2
npm run check
npm run build
Against a running live backend, python3 tools/http_product_smoke.py --base-url http://127.0.0.1:8000
walks the same /narrative/* path the UI uses.
python3 tools/portfolio_public_evidence_preflight.py reports whether local
HEAD matches origin/main and whether the GitHub Pages copy is current.
Design and results
seed
-> story compiler: cast, player role, hidden objectives, leverage
-> 12-turn play loop (choices or free-text actions)
-> advisor side channel (reads the run, cannot change it)
-> ending compiler: label, highlights, alternate branches, replay
- State before prose. Before each LLM call, Python code assembles the turn: NPC agenda, pressure, inventory, recent consequences. The model returns structured output (narration, options, NPC shifts, inventory changes), which is persisted before the UI renders it.
- Typed contracts. Pydantic models in
rpg_backend/narrative/contracts.pyare mirrored infrontend2/src/api/contracts.ts. - Separate LLM roles. Narrator, advisor, and ending compiler get different context and authority.
- Reviewer view.
#/play/<session>?reviewer=1shows seed, stage, role, options, inventory, and ending state for each turn. - Demo guards. Authoring routes need a real session; public deployments can turn authoring off and apply per-IP and per-user LLM quotas.
- Evaluation.
tools/narrative_release_gate.py --mode fakeruns the core path (create, fork, turns, advisor, ending, replay) against the fake gateway. The Eval v3 redesign and the RPG Runtime Evaluation Lab (deployed) describe the wider evaluation work; the lab scores are a deterministic diagnostic, not a calibrated metric.
Deeper docs:
- Current System Map: which code is the active chain and which is legacy
- Case Study
- Architecture
- Code map
Limits
- This is a portfolio case study, not a validated consumer product. Demand and repeat play are unproven; see the pause memo.
- Live play needs an OpenAI-compatible key. Offline mode only replays canned text.
frontend2/is the current frontend. Thefrontend/folder is historical and no longer maintained.
Who wrote what
Built with coding agents by Shehao Li (React, TypeScript, FastAPI, Python, SQLite). The story runtime is built around story state, free-text intent mapping, fallbacks, budgets, and character behavior; an advisor can read a run but cannot change the story.
License
MIT. See LICENSE.
