An interactive storytelling application built with Flask and vanilla JavaScript. Choose what happens next, follow the consequences, and explore another path when the adventure ends.
Play a self contained branching demo or enable live AI storytelling with optional generated illustrations.
| Mode | Story | Illustrations | API keys |
|---|---|---|---|
| Demo, the default | Two prerecorded adventures with 16 different endings | Included static illustrations | None |
| Live | New scenes generated through the OpenAI Responses API | Optional OpenAI or Stability AI generation | Your own provider keys |
The demo contains a wizard's forest adventure and an explorer's journey through time. Each path has four scenes. Live adventures run for up to 12 scenes. The demo is clearly labeled in the interface and makes no external API requests.
Use Python 3.11 to 3.13:
git clone https://github.com/stefisha/CYOA_App.git
cd CYOA_App
python -m venv .venv
source .venv/bin/activate
python -m pip install -r requirements.txt
python app.pyOpen localhost:5000. No .env file is needed for the demo.
On Windows, activate with .venv\Scripts\activate. Set PORT if port 5000 is busy.
Choose a beginning, select one of the two options at each scene, and use Start over to explore a different path. Refreshing the page also starts a new story. Stories are not saved to a database or restored across browser sessions.
Copy .env.example to .env, then configure:
CYOA_MODE=live
OPENAI_API_KEY=your-own-key
OPENAI_MODEL=gpt-4.1-mini
IMAGE_PROVIDER=noneOPENAI_MODEL is configurable. The default compact model supports structured
output. Account
access, credits and provider availability determine which models you can use.
Images are optional. Choose IMAGE_PROVIDER=openai to use the configured
OPENAI_IMAGE_MODEL, or IMAGE_PROVIDER=stability and provide STABILITY_API_KEY.
The default OpenAI image model is gpt-image-1-mini. If an illustration fails,
the scene and choices remain available.
Live mode sends the story conversation to OpenAI and the current visual caption to the selected image provider. API usage is billed by those providers. Keys stay on the server and should never be committed. Demo mode remains available without keys, credits or a network connection.
- The browser sends a choice number and a signed story token.
- Flask verifies the token, its expiry and the available choices.
- The demo follows a prerecorded branch, or the live provider requests a typed scene.
- The server returns story text, two choices, a new token and an optional image.
- The browser renders text safely and keeps the previous scene available if a request fails.
Story tokens expire after two hours and carry signed text history, without image
bytes. They prevent the browser from editing the conversation or introducing its
own system messages. Tokens are signed, not encrypted, and are not user accounts
or a guarantee against replay. An optional stable SECRET_KEY keeps tokens valid
across server restarts. Otherwise each process generates a temporary signing key.
The live integration validates structured story responses. Requests have timeouts, automatic SDK retries are disabled, and the browser blocks duplicate clicks while a choice is pending. Errors restore the choices and loading indicator to a usable state.
| Variable | Default | Purpose |
|---|---|---|
CYOA_MODE |
demo |
Select prerecorded or live scenes |
OPENAI_API_KEY |
Empty | Required only for live stories |
OPENAI_MODEL |
gpt-4.1-mini |
Structured story generation |
IMAGE_PROVIDER |
none |
none, openai or stability |
OPENAI_IMAGE_MODEL |
gpt-image-1-mini |
Optional OpenAI illustrations |
STABILITY_API_KEY |
Empty | Required for Stability images in live mode |
SECRET_KEY |
Temporary random value | Signs story history |
PORT |
5000 |
Local listening port |
ALLOWED_HOSTS |
Local hostnames | Host header allowlist |
This repository provides local setup instructions and has no hosted demo. The included server binds to the local machine. Rate limits use process memory and are intended for local use. Public or shared deployment would require appropriate authentication, shared request limits and provider spending controls.
Python checks:
python -m pip install -r requirements-dev.txt
python -m pytest -q
ruff check .
ruff format --check .
pip-audit -r requirements.txtBrowser logic checks use Node.js 22.12 or later within version 22, or Node.js 24:
npm ci
npm testTests cover all demo paths, tampered and expired tokens, input bounds, rate limits, provider failures, safe rendering, duplicate clicks and late responses after starting over. The real OpenAI SDK is exercised through an offline HTTP transport. CI runs on Python 3.11, 3.12 and 3.13. Automated checks do not make paid API calls, and live generation quality and account access have not been verified.
app.py Flask application factory and choice endpoint
cyoa/story.py Validated scene contract and story instructions
cyoa/demo.py Prerecorded branching adventures
cyoa/providers.py OpenAI and Stability AI adapters
templates/index.html Story page
static/ Browser logic, styling and demo illustrations
tests/ Offline backend and browser logic tests
.env.example Optional provider configuration
The included demo illustrations are static AI generated artwork. OpenAI provides the optional story and GPT Image services. Stability AI provides Stable Image Core.
Author: Stefan Veličković
Code is available under the MIT License.

