Skip to content

README.md

Latest commit

 

History

History
323 lines (257 loc) · 18.7 KB

README.md

File metadata and controls

323 lines (257 loc) · 18.7 KB

StoryForge

AI-powered story generation with multi-agent drama simulation

Python 3.10+ FastAPI Alpine.js TypeScript MIT License GitHub Stars

Tiếng Việt

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

StoryForge — Create Story

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
Create Settings
Story Library Light Mode
Library Light

Features

Story Engine

  • 2-layer pipeline — Story Generation → Drama Simulation, with checkpoint & resume and real-time SSE streaming
  • L3 Sensory Polish — optional post-enhancement layer for vivid sensory details and immersive prose
  • 13 specialized AI agents — autonomous character agents plus a drama critic, editor-in-chief, pacing analyzer, style consistency checker, dialogue expert, reader simulator, and more
  • Reader Simulator agent — simulates reader reactions to provide quality feedback before finalization
  • Quality scoring & auto-revision — 6-dimension LLM-as-judge (coherence, character, drama, writing style, thematic depth, dialogue quality) with an automated re-enhancement loop
  • Cumulative story memory — character knowledge, relationships, and plot threads accumulate across chapters instead of resetting, ensuring multi-chapter continuity
  • Genre-aware naming conventions — Vietnamese names by default; Chinese (tiên hiệp/kiếm hiệp/tu tiên/wuxia/xianxia) and Western fantasy/sci-fi styles auto-selected from genre
  • Arc scaling — character arc waypoints scale automatically with num_chapters to keep character development paced for short or long stories
  • RAG knowledge base — optional world-building context retrieval via ChromaDB + sentence-transformers; upload .txt, .md, or .pdf reference files to enrich story generation

Advanced Story Continuation

  • 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
  • Multi-path preview — preview 2-5 different continuation directions with summaries and outlines; click to select and write
  • Outline editor — generate chapter outlines first, edit titles and summaries inline, then write from approved outlines
  • Collaborative chapter writing — write your own chapter text, then let AI polish it with 3 levels (light/medium/heavy)
  • Consistency checker — scan story for contradictions in characters, timeline, facts, and locations; view issues with severity and suggested fixes
  • Character arc steering — guide character development trajectory across new chapters
  • Chapter insertion — insert new chapters mid-story with automatic renumbering
  • Selective chapter regeneration — regenerate specific chapters without affecting others
  • Retroactive consistency fix — automatically fix continuity errors in earlier chapters when new chapters introduce changes

Layer 1 — Story Generation Quality

  • Chapter contracts — per-chapter requirements with validation and failure propagation
  • Arc waypoints — character arc milestones with validation
  • Arc memory cache — persistent cache for arc state across generation runs
  • Dialogue injection — natural dialogue insertion and voice consistency validation
  • Tiered context system — 4-level priority context management for long stories (full/summary/key-points/minimal)
  • Narrative linking — thread dependencies, semantic foreshadowing, conflict escalation tracking
  • Pacing enforcement — automatic pacing analysis with corrective rewriting
  • Self-critique with rollback — LLM self-evaluation with automatic rollback on quality failure
  • Feedback loops — pacing correction, location validation, selective critique
  • Emotional memory — character emotional state tracking across chapters
  • Causal graph — cause-effect relationship tracking for plot consistency

Layer 2 — Drama Simulation Quality

  • Contract gate — per-chapter validation with single-retry rewrite on failure
  • Parallel processing — concurrent chapter enhancement for faster throughput
  • Coherence pre-check — validates consistency before enhancement begins
  • Knowledge constraints — agent prompts bounded by character knowledge graphs
  • Thread urgency — psychological pressure tracking wired into agent behavior
  • Causal accountability — revelation events, witness propagation, LLM audit trail
  • Knowledge context — agent prompts enriched with causal chain formatting
  • Zero-cost quality signals — stale thread detection, chapter hooks, emotional arc tracking

Interactive Branch Reader

  • Choose-your-own-adventure — LLM-generated branching paths with real-time SSE streaming and live text animation
  • SVG tree visualization — interactive tree map of all branches with clickable goto-node navigation
  • Undo/Redo navigation — navigate back and forth through your choice history with full state preservation
  • Bookmarks — save and jump to any node in the tree; bookmarks persist across sessions
  • Branch analytics — track visits, unique paths explored, popular choices, and depth distribution
  • Minimap with zoom/pan — bird's-eye view of the entire tree with zoom controls and current position indicator
  • WebSocket collaboration — real-time multi-user sessions with live user count and synchronized navigation
  • EPUB export — download the entire branch tree as an EPUB with all paths included
  • Branch merging — merge divergent branches back together with conflict detection and resolution
  • 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), Z.AI (free models), Kyma API, Ollama (local), or any custom OpenAI-compatible endpoint; auto-detect provider from API key
  • Preemptive rate-limit switching — live monitoring of provider quota; the chain switches to the next model before hitting 429, using reset-header timing to queue retries
  • Chain-level wait-and-retry — when the entire fallback chain exhausts quota, requests wait for the earliest reset rather than failing
  • Latency-aware primary routing — slow primary models are retried instead of silently skipped, preventing empty chains on transient slowness
  • Provider-aware model routing — automatic model format adaptation per provider in fallback chains
  • Auto-router support — let the system pick the best model for each task based on cost/capability tradeoffs
  • 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

  • Full SPA redesign (v2.3) — all 7 pages rebuilt on a unified sf-* design system: hero gradient borders, step badges, empty-state heroes, story cards, stat tiles, and guide steps
  • Swiss Modernism palette — brand #2563EB · violet #8B5CF6 · orange #F97316 · emerald done #10B981, tuned for readable contrast in both themes
  • Vietnamese-first copy — every page, button, empty state, and toast is localized; English strings only surface where technical (provider names, env vars)
  • Create Story — 6-phase pipeline visualizer, idea composer with live char count, slider-based config (chapters · characters · words · drama level), and persistent form state in localStorage
  • Library — search-as-you-type filter, inline continue/delete actions, layer badge (Draft / Enhanced / Complete)
  • Reader — distraction-free typography, image inline display, chapter sidebar navigation
  • Analytics — simulation dashboard with 4 stat tiles and 4 quality-score meters (coherence, character, drama, writing style)
  • Branching — source picker for open or saved stories with interactive tree overlay
  • Settings — Quick Setup preset cards (Basic / Optimized / Max Context), provider picker grid, image generation toggles
  • Guide — pipeline flow diagram with Layer 1 & Layer 2 cards and 5-step onboarding
  • Dark / Light mode — polished theme toggle with full color-scheme sync; Heroicons SVGs throughout

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

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://localhost:6379 NUM_WORKERS=4 python app.py

⚠️ 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:

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 · Z.AI · Kyma API · 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

Architecture

flowchart LR
    idea([Idea]) --> L1[Layer 1<br/>Story Generation]
    L1 --> L2[Layer 2<br/>Drama Enhancement]
    L2 --> media[Images · Export]
    media --> out([PDF · EPUB · HTML · ZIP])
Loading
  • Layer 1 builds characters, outline, conflict web, foreshadowing, then writes chapters in parallel batches.
  • Layer 2 runs a multi-agent drama simulation, rewrites scenes with voice preservation, and validates chapter contracts.
  • Quality gates, structural rewrites, and smart revision loops kick in between layers to catch weak chapters automatically.

See docs/system-architecture.md for the full pipeline flow, signal integration, and retry semantics.

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)

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