StoryForge

AI-powered story generation with multi-agent drama simulation

Tiếng Việt

Turn a one-sentence idea into a complete, drama-rich story with character-consistent images and cinematic scene backgrounds.
Self-hosted. Privacy-first. Works with any OpenAI-compatible LLM.

---

Why StoryForge?

Most AI writing tools produce flat, predictable stories. StoryForge takes a different approach: your characters become autonomous AI agents that interact, argue, form alliances, and betray each other in a multi-round drama simulation. The simulation uncovers conflicts the author never planned — then rewrites the story around them, scored and revised automatically until it meets a quality threshold.

---

Screenshots

Create Story	Settings

Story Library	Light Mode

---

Features

Story Engine

• 2-layer pipeline — Story Generation → Drama Simulation, with checkpoint & resume and real-time SSE streaming
• 13 specialized AI agents — autonomous character agents plus a drama critic, editor-in-chief, pacing analyzer, style consistency checker, dialogue expert, and more
• Quality scoring & auto-revision — 4-dimension LLM-as-judge (coherence, character, drama, writing style) with an automated re-enhancement loop
• Continue story — append new chapters to existing stories from saved checkpoints, with configurable chapter count and word count; optional Layer 2 re-enhancement on the full story
• Cumulative story memory — character knowledge, relationships, and plot threads accumulate across chapters instead of resetting, ensuring multi-chapter continuity
• RAG knowledge base — optional world-building context retrieval via ChromaDB + sentence-transformers; upload .txt, .md, or .pdf reference files to enrich story generation

Interactive Branch Reader

• Choose-your-own-adventure — LLM-generated branching paths with real-time SSE streaming
• SVG tree visualization — interactive tree map of all branches with clickable goto-node navigation
• 10-level depth limit — automatic ending generation when maximum depth is reached
• Session persistence — branch reader state saved to localStorage, survives page refresh
• Chapter selection — load any story from the current pipeline or saved checkpoints into branch mode

Image & Export

• Image generation — character-consistent portraits (IP-Adapter) and cinematic scene backgrounds, generated after drama simulation
• Rich export — PDF, EPUB, HTML web reader, and ZIP with chapters and image prompts

LLM & Providers

• Multi-provider LLM support — OpenAI, Google Gemini, Anthropic, OpenRouter (290+ models), Ollama (local), or any custom OpenAI-compatible endpoint; auto-detect provider from API key
• Multi-provider fallback — configure fallback profiles that auto-switch between providers on rate limit or failure
• Smart model routing — assign cheap models to analysis tasks and premium models to writing (~45% cost savings)
• Built-in LLM cache — SQLite-backed cache to avoid redundant API calls

UI & Experience

• Redesigned pipeline page — modernized Create Story form with hero cards, config pills, and persistent form state
• Settings wizard — guided multi-step provider setup with provider-specific model lists, API key masking, and connection testing
• Heroicons SVG icons — all emoji icons replaced with crisp Heroicons SVGs
• Dark / Light mode — polished theme toggle with full color-scheme sync across all pages
• Vietnamese & English — bilingual story generation out of the box

Security & Infrastructure

• CSRF protection — double-submit cookie pattern on all state-changing requests
• Body size limit — 10 MB request payload limit
• Prompt injection blocking — middleware detects and blocks injection patterns in JSON payloads
• Encrypted secrets — API keys encrypted at rest in data/secrets.json (requires STORYFORGE_SECRET_KEY)
• Self-hosted, privacy-first — your stories and API keys never leave your infrastructure
• Customizable agent prompts — edit data/prompts/agent_prompts.yaml to tune how AI agents evaluate and enhance stories

---

Quick Start

Docker (recommended)

docker compose up

Open http://localhost:7860. That's it.

Local

git clone https://github.com/HieuNTg/STORYFORGE.git
cd STORYFORGE
pip install -r requirements.txt
npm install && npm run build   # compile TypeScript → JS
npm run build:css              # compile Tailwind CSS
python app.py
# → http://localhost:7860

First Run

1. Settings → the setup wizard guides you through provider selection, API key, and model — connection tested automatically
2. Create Story → pick genre, style, describe your idea in one sentence
3. Run Pipeline → watch generation, simulation, and image generation stream in real-time
4. Continue → add more chapters to any saved story from checkpoints
5. Branch Reader → explore interactive branching paths with SVG tree visualization
6. Export → download as PDF, EPUB, HTML, or storyboard ZIP

---

Deployment & Scaling

Environment Variables

Variable	Default	Description
STORYFORGE_SECRET_KEY	(file-based)	HMAC signing key. Enables encrypted secrets storage. Set this in production.
REDIS_URL	(none)	Redis URL for cache + sessions. Required for multi-instance.
NUM_WORKERS	1	Uvicorn workers. Scale with CPU cores.
STORYFORGE_ALLOWED_ORIGINS	localhost:7860	CORS origins (comma-separated).
TRUSTED_PROXY_IPS	(none)	Trusted proxy IPs for X-Forwarded-For.
DB_POOL_SIZE	5	SQLAlchemy connection pool size.
STORYFORGE_BLOCK_INJECTION	true	Block detected prompt injections.
CHROMA_PERSIST_DIR	data/chroma	ChromaDB persistence directory for RAG knowledge base.
CHROMA_COLLECTION_NAME	storyforge	ChromaDB collection name.

Single Instance (default)

Works out of the box with SQLite cache. No Redis needed.

Multi-Instance

Requires Redis for shared cache and session state:

REDIS_URL=redis://redis:6379 NUM_WORKERS=4 docker compose up -d

⚠️ Without Redis, each worker has its own in-memory cache — sessions won't be shared.

---

Configuration

All settings are managed through the Settings tab in the web UI and persisted to data/config.json. Key environment variables for Docker deployments:

Variable	Description	Default
LLM_PROVIDER	openai | gemini | anthropic | openrouter | ollama	openai
LLM_API_KEY	API key for the selected provider	(none)
LLM_MODEL	Primary model for writing (e.g. gpt-4o)	gpt-4o
LLM_BASE_URL	Custom endpoint URL (OpenAI-compatible)	(provider default)
PORT	Server port	7860

Per-layer model overrides and a secondary budget model for analysis tasks can be configured in the UI under Settings → Advanced.

Compatible Providers

Any provider that exposes an OpenAI-compatible /v1/chat/completions endpoint works with StoryForge:

OpenAI · Google Gemini · Anthropic · OpenRouter · Ollama · Any custom endpoint

Customizing Agent Prompts

StoryForge ships with 10 customizable agent prompts in data/prompts/agent_prompts.yaml. Edit this file to:

• Change the language of AI evaluation (default: Vietnamese)
• Adjust scoring criteria and thresholds
• Modify agent personalities and review focus areas

---

Running

Docker Compose

# Start
docker compose up -d

# View logs
docker compose logs -f

# Stop
docker compose down

---

Architecture

                        ┌─────────────────────────────────────────┐
  User Prompt  ────────▶│         Layer 1 — Story Generation      │
                        │  Characters · World · Chapters · Context │
                        └──────────────────┬──────────────────────┘
                                           │
                        ┌──────────────────▼──────────────────────┐
                        │       Layer 2 — Drama Simulation         │
                        │  13 AI Agents · Conflict Emergence       │
                        │  Drama Scoring · Auto-Revision Loop      │
                        └──────────────────┬──────────────────────┘
                                           │
                        ┌──────────────────▼──────────────────────┐
                        │         Image Generation                  │
                        │  Character Consistency · Scene Backgrounds│
                        └──────────────────┬──────────────────────┘
                                           │
                              PDF · EPUB · HTML · ZIP

flowchart LR
    idea([User Idea]) --> L1

    subgraph L1 [Layer 1 — Story Generation]
        direction TB
        chars[Characters & World] --> chapters[Full Chapters]
    end

    L1 --> L2

    subgraph L2 [Layer 2 — Drama Simulation]
        direction TB
        agents[13 AI Agents] --> conflicts[Conflict & Alliance]
        conflicts --> score[Quality Score]
        score -- below threshold --> agents
    end

    L2 --> IMG

    subgraph IMG [Image Generation]
        direction TB
        portraits[Character Portraits] --> scenes[Scene Backgrounds]
    end

    IMG --> export([PDF / EPUB / HTML / ZIP])

Loading

---

Tech Stack

Layer	Technology
Backend	Python 3.10+, FastAPI, Uvicorn
Frontend	Alpine.js 3, TypeScript, Tailwind CSS
Streaming	Server-Sent Events (SSE)
AI / LLM	Any OpenAI-compatible API
RAG	ChromaDB, sentence-transformers (optional)
Image Generation	IP-Adapter (character consistency), diffusion models (scene backgrounds)
Storage	JSON files, SQLite (dev cache), Redis (production cache)
Export	fpdf2 (PDF), ebooklib (EPUB)
Containerization	Docker, Docker Compose
CI/CD	GitHub Actions

---

Project Structure

storyforge/
├── app.py                      # FastAPI entry point
├── mcp_server.py               # MCP tool server
├── pipeline/                   # 2-layer generation engine
│   ├── orchestrator.py         #   Pipeline orchestrator with checkpointing
│   ├── layer1_story/           #   Story generation (characters, world, chapters)
│   ├── layer2_enhance/         #   Drama simulation & enhancement
│   └── agents/                 #   13 specialized AI agents
├── services/                   # Reusable business logic
│   ├── llm/                    #   LLM client with provider abstraction & fallback
│   ├── llm_cache.py            #   Dual-backend cache (Redis / SQLite)
│   ├── rag_knowledge_base.py   #   RAG context retrieval (ChromaDB)
│   ├── pipeline/               #   Quality scoring, branch narrative, smart revision
│   ├── media/                  #   Image generation (character portraits, scenes)
│   ├── export/                 #   PDF, EPUB, HTML, Wattpad exporters
│   ├── infra/                  #   Database, i18n, structured logging
│   └── ...                     #   Analytics, feedback, onboarding, etc.
├── api/                        # FastAPI REST endpoints
│   ├── pipeline_routes.py      #   Pipeline SSE streaming + resume
│   ├── continuation_routes.py  #   Continue story with new chapters
│   ├── branch_routes.py        #   Interactive branch reader API
│   ├── config_routes.py        #   Settings CRUD + connection test
│   ├── export_routes.py        #   PDF, EPUB, ZIP export
│   └── ...                     #   Analytics, health, metrics, etc.
├── web/                        # Alpine.js frontend (SPA)
│   ├── index.html              #   Main application
│   ├── js/                     #   TypeScript source → compiled to JS via tsc
│   └── css/                    #   Tailwind CSS + custom styles
├── config/                     # Configuration package
├── data/prompts/               # Customizable agent prompts (YAML)
├── models/                     # Pydantic data models
├── plugins/                    # Plugin system
├── tests/                      # Test suite (unit, integration, security, load)
└── scripts/                    # Utility scripts

---

Contributing

Contributions are welcome! Please read CONTRIBUTING.md to get started — it covers development setup, code style, the PR process, and how to find good first issues.

---

License

MIT — Copyright 2026 StoryForge Contributors

---

Acknowledgments

StoryForge is built on the shoulders of excellent open source work:

• FastAPI — modern Python web framework
• Alpine.js — lightweight reactive frontend
• Tailwind CSS — utility-first CSS
• fpdf2 — PDF generation
• ebooklib — EPUB generation
• All LLM providers — OpenAI, Google, Anthropic, OpenRouter, and the Ollama community