An AI-powered story continuity and world-state tracking platform for writers of long-form serialized fiction — light novels, manga, web novels, games, and episodic screenwriting.
This is not a text generator. It's a deterministic, queryable world-state database for fiction, layered with an agentic validation pipeline that catches plot holes, lore contradictions, and state drift before they become published mistakes.
Once a story crosses 50+ chapters, tracking every character's location, item inventory, relationship status, power level, and faction allegiance becomes humanly impossible. Manual wikis drift out of sync. Editors miss continuity errors. Readers catch them.
This system prevents failures like:
- A character using an ability they haven't unlocked yet
- A dead character reappearing without explanation
- An item changing hands with no recorded transfer
- Two chapters contradicting each other on a timeline event
- A faction alliance dissolved three arcs ago referenced as active
Next.js Frontend (port 3000)
│
│ HTTP / REST
▼
FastAPI Backend (port 8000)
├── Ingestion Pipeline
├── LangGraph Agent Pipeline
└── Auth (JWT + SQLite)
│
▼
┌─────────────────────────────────┐
│ Data Layer │
│ Neo4j SQLite │
│ - World state - PageIndex │
│ - Entity graph - Auth │
│ - Schema - Jobs / Diffs │
└─────────────────────────────────┘
│
▼
Gemini API (Google)
gemini-2.5-flash-lite · gemini-2.5-flash
Dynamic Ontology — the system never assumes what entities or relationships exist. On first ingestion, Gemini reads the opening chapters and discovers the schema (entity types, fields, relationship types). A school drama and a pirate adventure have completely different world models — the system adapts to both.
PageIndex (Vectorless RAG) — instead of vector embeddings, retrieval uses a deterministic hierarchical tree: Volume → Chapter → Scene → Summary Leaf. "What was Kira's status in Chapter 7?" walks directly to that scene leaf. No hallucination from fuzzy similarity matching.
Human-in-the-Loop — three things always require human approval: schema discovery, schema extensions, and continuity violations. Nothing is ever silently written to the world-state graph.
| Layer | Technology |
|---|---|
| Backend | Python 3.11, FastAPI, LangGraph, Pydantic v2 |
| LLM | Google Gemini API (gemini-2.5-flash-lite / gemini-2.5-flash) |
| Graph DB | Neo4j 5.x |
| Document Store | SQLite (aiosqlite) |
| Frontend | Next.js 15 (App Router), TypeScript, Tailwind CSS |
| Auth | JWT (HS256), bcrypt |
| Infrastructure | Docker + Docker Compose |
cp apps/.env.example apps/.envFill in your values in apps/.env:
GEMINI_API_KEY=your_key_here
NEO4J_PASSWORD=your_password_here
JWT_SECRET=your_secret_herecd apps
docker-compose up -d neo4jcd apps/api
conda env create -f environment.yml
conda activate narrative-engine
uvicorn main:app --reloadAPI available at http://localhost:8000. Swagger docs at http://localhost:8000/docs.
cd apps/web
npm install
npm run devFrontend available at http://localhost:3000.
cd apps
docker-compose up- Upload a PDF or paste chapter text via the Ingest page
- Gemini reads the first 3 chapters and discovers the schema (entity types, relationship types, tracked fields)
- You review and approve the schema
- Gemini extracts all entities and relationships using the approved schema
- You review the diff (before/after for every field change) and approve changes
- Approved changes are written to Neo4j
Ask natural language questions about your story. The pipeline:
- Routes the query (narrative history vs. current state vs. both)
- Retrieves from PageIndex (historical) and Neo4j (current) in parallel
- Synthesizes a grounded answer with citations like
(Vol.1 Ch.3 Sc.2)
Paste a new draft chapter. The Critic agent:
- Reads the current world state and recent scene history
- Validates every claim in the draft
- Requires a citation for every assertion — no citation = invalid, always
- Returns pass/fail with per-claim verdicts and citations
| Page | Route | Purpose |
|---|---|---|
| Home | /home |
Story selector and navigation |
| Ingest | /ingest |
Upload chapters, track jobs, approve schema |
| Audit | /audit |
Validate draft chapters, co-writer chat |
| Approve | /approve |
Review and approve world-state diffs |
| World State | /world |
Graph visualization, blast radius, wiki export |
| Schema | /schema |
View ontology, propose extensions, intent flags |
| Query | /query |
Natural language questions about the story |
| Entity | /entity/[story_id]/[name] |
Deep-dive on a single entity |
Full docs available at http://localhost:8000/docs when the server is running.
| Group | Base Path | Key Endpoints |
|---|---|---|
| Auth | /api/v1/auth |
register, login, me |
| Ingestion | /api/v1/ingest |
raw, pdf, approve-schema, pending-diffs |
| Query | /api/v1 |
query, entity state + timeline |
| Audit | /api/v1/audit |
draft validation, co-writer chat, history |
| World State | /api/v1/world-state |
current state, blast radius, wiki export |
| Schema | /api/v1/schema |
view schema, propose/approve extensions, intent flags |
apps/
├── api/ # FastAPI backend
│ ├── agents/ # LangGraph agents (router, retriever, critic, co-creator)
│ ├── api/ # Route handlers and Pydantic models
│ ├── auth/ # JWT auth, user store
│ ├── graph/ # Neo4j client, entity CRUD, world state queries
│ ├── ingestion/ # Schema discovery, entity extraction, PageIndex, jobs
│ └── utils/ # Gemini client, JSON validator, diff utilities
├── web/ # Next.js frontend
│ ├── app/ # App Router pages
│ └── src/
│ ├── components/ # Nav, auth guards, story picker
│ ├── context/ # Auth and story context providers
│ └── lib/ # API client, TypeScript types
├── .env # Local secrets (never committed)
├── .env.example # Environment variable template
└── docker-compose.yml # Neo4j + API + Web
MIT