Upload a book. A language model you choose and control reads it page by page into an interactive character graph, an incident timeline, and a dossier for everyone in the cast.
The demo is PIN-gated. Use the access PIN
shared with your invite · all demo data is synthetic.
On first open your browser shows a one-time certificate warning — click Advanced → Proceed to continue (the connection is still encrypted).
Readers, students, book clubs, writers and editors routinely lose track of a book's cast — who is who, how they relate, and the order key events happen — especially in large ensembles or a series picked up after months.
Re-reading to rebuild that mental model is slow. And the existing "character map" tools are either fully manual — you draw it yourself — or locked to one AI vendor and one closed book catalog.
The book is processed in small overlapping windows. Each window is sent to your model alongside the running cast, so recurring characters resolve to a single node. Results merge on the server and persist after every window — the map fills in as it reads.
A force-directed graph: nodes sized by mentions, coloured by role; edges typed and weighted. Drag, zoom, and click a character to focus its web.
Every incident in reading order, anchored to its page — plus a dossier per character with role, aliases, traits and importance.
Point it at any OpenAI- or Anthropic-compatible endpoint — hosted or a local model. The key stays server-side; nothing is locked to a vendor.
A single FastAPI + HTMX app. Text is extracted per page, windowed, read by your chosen LLM, merged into one JSON map per book, and streamed live to the browser. Everything persists as plain JSON files on disk.
Verified against the running demo on this machine. This is an honest matrix — it marks what ships today, what is conditional, and what is deliberately still ahead.
| Stated requirement | What was built | Status |
|---|---|---|
| Provider configuration P0.1 |
Switch OpenAI-/Anthropic-compatible wire, base URL, model, reading params; live "Test connection"; key masked and kept on re-save. | Built |
| Upload & ingest P0.2 |
PDF, EPUB and plain-text accepted; type / size / encryption validated; page count & title parsed. | Built |
| Page-by-page analysis P0.3 |
Overlapping-window extraction, running-cast context per window, tolerant JSON parsing, partial persist every window, background thread. | Built |
| Live progress (SSE) P0.4 |
Streaming window / message / counts; badges, progress bar and graph update live. | Built |
| Character graph P0.5 |
Self-contained force-directed SVG — drag, zoom, pan, click-to-focus with a detail panel. Verified with a 68-character graph. | Built |
| Timeline & dossiers P0.6 |
Page-anchored incident timeline and a per-character dossier grid. | Built |
| Export P0.7 |
Full map as JSON; graph as SVG or 2× PNG. | Built |
| Multi-format + OCR | EPUB / TXT ingestion shipped. OCR for scanned pages runs automatically when tesseract + poppler are present, and degrades gracefully when they aren't. Both present on this demo host. | Built Host-conditional |
| Sentiment arc & reveal-reader | Chapter-aware emotional-tone chart, and an in-app reader whose map reveals spoiler-safe as you read. | Built |
| Multi-book crossovers | Characters shared by name across two or more analyzed books. | Built |
| Live LLM analysis in the demo | Fully working; the public demo ships three pre-analyzed synthetic books so it is instantly walkable, and can run fresh analysis against a configured provider. | Built Demo-scoped |
| PIN access gate | Added by this betadoc so the single-user app can be exposed safely — a signed-cookie gate over every route. | Built |
| Multi-user accounts & cloud sync | Out of scope by design — the tool is local-first and single-user. The PIN gate is the interim answer for shared demos. | Roadmap |
Windowed page-by-page analysis, the graph / timeline / dossiers, live SSE, export, provider switch — plus EPUB & TXT, OCR, the sentiment arc, the reveal-as-you-read reader, and cross-book character linking.
Read a book fully offline on local models (your text never leaves the machine), ground characters to Wikidata with a ✓ verified badge that flags invented ones, and export the map to GraphML, JSON-LD, Neo4j and Parquet — so it opens in Gephi, Cytoscape, Neo4j or Obsidian.
The near-term, high-impact set: automatic Wikidata badges everywhere, character search & filter, one-click "open in Gephi / Neo4j / Obsidian", and shareable read-only map links.
Evidence behind every relationship — click an edge, jump to the passage that supports it — a per-book map-quality score, relationship confidence, and a hosted, multi-book mode.
A mobile-friendly graph and reader, an audio overview of the map, and a hosted multi-user demo with sample books.
A stronger, research-only coreference model was evaluated as a possible accuracy boost over the shipped engine. It's parked pending GPU hardware — its checkpoint doesn't produce valid results on CPU — and remains research-only under a non-commercial license, so the shipped offline coreference is unaffected.
One codebase. The difference is only where the model runs and whether the data is live — flipped with environment variables, no code changes.
Runs on your own box against a local model. Your book and your model never leave the machine. This is the lane this demo is running in right now.
# install & run pip install -r requirements.txt uvicorn app.main:app --port 8000 # enable the gated demo lane DEMO_GATE=1 DEMO_PIN=•••••• \ uvicorn app.main:app --port 8000
The same application on a small cloud box, pointed at a cloud model through a thin keyless gateway and a synthetic dataset. The app itself stays keyless — the gateway holds the key and redacts PII.
# same image, environment-flipped DEMO_GATE=1 LLM_BASE_URL=http://gateway:9100/v1 DATA_FIXTURE=snapshot # replay, not live
Secrets live in gitignored environment files, never in the repository. Demo data is synthetic — no real reader, customer, or manuscript content is ever placed on a public demo.
The live demo is the actual working application — the same code described above, gated behind a PIN, with three books already mapped for you to explore.
Enter the live demo →Access PIN shared with your invite ·
full walkthrough in the documentation.
First open shows a one-time certificate warning — click Advanced → Proceed (the connection is still encrypted).