Skip to content
stefishaPublic

About

Interactive storytelling with Flask, structured OpenAI responses and optional illustrations. Includes a playable offline demo, safe rendering and automated tests.

Topics

Resources

Stars

0 stars

Watchers

1 watching

Forks

Repository files navigation

Choose Your Own Adventure

Choose Your Own Adventure

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.

Forest adventure in the local demo

Two ways to play

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.

Run locally

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.py

Open 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.

Enable live generation

Copy .env.example to .env, then configure:

CYOA_MODE=live
OPENAI_API_KEY=your-own-key
OPENAI_MODEL=gpt-4.1-mini
IMAGE_PROVIDER=none

OPENAI_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.

How it works

  1. The browser sends a choice number and a signed story token.
  2. Flask verifies the token, its expiry and the available choices.
  3. The demo follows a prerecorded branch, or the live provider requests a typed scene.
  4. The server returns story text, two choices, a new token and an optional image.
  5. 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.

Configuration

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.

Verification

Python checks:

python -m pip install -r requirements-dev.txt
python -m pytest -q
ruff check .
ruff format --check .
pip-audit -r requirements.txt

Browser logic checks use Node.js 22.12 or later within version 22, or Node.js 24:

npm ci
npm test

Tests 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.

Project structure

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

References and credits

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.

About

Interactive storytelling with Flask, structured OpenAI responses and optional illustrations. Includes a playable offline demo, safe rendering and automated tests.

Topics

Resources

Stars

0 stars

Watchers

1 watching

Forks

Used by

Contributors

Languages