StoryWorld Engine

An open-source narrative simulation engine for exploring how pivotal decisions propagate through characters and fictional worlds.

StoryWorld models characters as stateful actors and explores how pivotal decisions propagate through a fictional world. A standard run creates three shared setup rounds, forks the state at three different character decisions, and simulates three rounds per branch (3 + 3 x 3 = 12).

中文说明

What is implemented

• Typed narrative state for characters, worlds, intents, events, and state changes.
• Deterministic three-branch state isolation and a strict 12-round budget.
• Character arcs, causal event chains, tension curves, continuity risks, unresolved foreshadowing, and scene-card reports.
• OpenAI-compatible dual-model gateway with a local mock mode.
• PostgreSQL/Neon persistence, JSONB checkpoints, and a single-consumer job queue.
• HMAC-signed control-plane requests with nonce replay protection.
• PDF, DOCX, Markdown, and text parsing with immediate temporary-file cleanup.
• Flask REST endpoints for runs, polling, reports, cancellation, and uploads.
• Fail-closed validation for hosted configurations.

Repository status

The StoryWorld implementation is isolated under backend/app/storyworld and backend/app/api/storyworld.py. The repository also contains the web application and supporting backend services used around the engine.

The private SaaS control plane, authentication, billing, and Paddle integration are intentionally not included in this repository.

Run locally

Python 3.11 or newer is recommended.

python -m venv .venv
# Windows PowerShell: .venv\Scripts\Activate.ps1
# macOS/Linux: source .venv/bin/activate
pip install -r requirements.txt
python backend/storyworld_run.py

Without DATABASE_URL or STORYWORLD_LLM_API_KEY, the service runs with in-memory persistence and deterministic mock models for local development.

Health endpoints:

GET http://localhost:7860/health
GET http://localhost:7860/api/storyworld/health

Copy .env.example to .env when connecting PostgreSQL or an OpenAI-compatible model provider. Never commit real credentials.

Test

Install the development dependencies declared in backend/pyproject.toml, then run:

python -m pytest backend/tests -q

The current test suite covers the state machine, branch isolation, document cleanup, request signing, API behavior, model rate limiting, and production configuration validation.

Database

The initial PostgreSQL schema is located at:

backend/migrations/001_storyworld.sql

It uses pgcrypto and pgvector. Run the migration against a disposable or properly backed-up database before starting the persistent worker.

Security notes

• Keep model keys, database URLs, and HMAC secrets outside Git.
• Set STORYWORLD_REQUIRE_PRODUCTION_CONFIG=1 in a hosted environment so the application refuses mock, unsigned, or in-memory fallbacks.
• Use a random HMAC secret of at least 32 characters.
• Put the API behind an authenticated control plane; it is not designed to be exposed directly to untrusted clients.

License

The project is licensed under the GNU Affero General Public License v3.0. If you modify and operate the software over a network, review the AGPL source-availability obligations.

Contributions

Issues and pull requests are welcome. Please keep engine changes modular and include tests for behavioral changes.