fabricatio-novel

MIT

AI-powered novel generation — outline to publication-ready EPUB.

Full dataflow and generation-logic walkthrough: docs/superpowers/specs/2026-08-21-novel-generation-dataflow.md

Installation

pip install fabricatio[novel]
# or
uv pip install fabricatio[novel]

For the CLI tool:

pip install fabricatio-novel[cli]

Pipeline

Generation runs a staged, template-driven pipeline over a context tree (NovelContext → ChapterContext → StoryContext → SceneContext), with every plan and character state proposed by the LLM in batched calls:

1. Metadata — outline → NovelPlan (title, description, word count, global writing constraint, bible)
2. Characters — bible roster → one CharacterSpan (start + end card) per character for the whole novel
3. Chapters — chapter plans, then N-1 boundary cards per character so chapter 1 starts at the roster start and the last chapter ends at the roster end
4. Stories — per chapter: story plans, then S-1 boundary cards per character anchored on the chapter's start/end
5. Scenes — per story: scene plans; the story's spans are broadcast to every scene, which is where the prose is actually written
6. Assembly — the composed context tree becomes a Novel; NovelBuilder (Rust/PyO3) produces the EPUB
7. Illustration (wri only) — one post-process pass proposes an image prompt per scene, renders it via ComfyUI, and embeds the PNGs in the EPUB

Character state is two pure cards, never an interpolated chain: the LLM is only asked for the coarsest boundary states, and code stitches them so continuity is guaranteed. Single-child levels inherit their parent's spans with no LLM call.

The CLI runs the pipeline as a staged workflow (DebugNovelWorkflow), persisting a whole-tree JSON snapshot after every stage so any wrong result is traceable:

01_init → 02_metadata → 03_characters → 04_chapter_plans → 05_story_plans
       → 06_scene_plans → 07_scenes → 08_novel → 09_export

An optional RAG variant (RagDebugNovelWorkflow) retrieves WritingStyleDocument entries from LanceDB once per story and renders them raw into the scene prompts.

The wri variant (RagIllustrationDebugNovelWorkflow) appends one final post-process stage that illustrates every scene of the finished context before export; its stage snapshots stay identical to wr's.

Data Flow & Prompt Assembly

The pipeline follows one principle: every LLM touchpoint is a template plus named context variables, and nothing else. Each stage renders a Handlebars template from the current context channel; planner calls parse the reply into validated pydantic models, while the single prose call captures raw paragraphs. Everything between calls — word-count allocation, character-arc stitching, prefix propagation, assembly — is deterministic code.

LLM call inventory

Templates live in templates/built-in/ and are selectable through the Configuration keys below.

What flows down the tree

Each level materializes its plan via create(outline).update_from(plan).set_plan(plan), with word counts assigned out-of-band via expect_ (the root takes the novel plan's count, children take their allocated share). update_from adopts only the plan's scalar fields (title, description, cast); the style channel is stacked explicitly by the composing capability through set_writing_styles (the root from the novel plan, every child from its parent's chain), and the constraint channel through set_writing_constraints (each level from its own plan alone). Each level then passes state down:

• Running manuscript — an append-only ContextLog; every walk seeds each child with exactly the bytes that precede it in the final book (iter_prefixed_contexts)
• Setting bible — rendered once at the root into a setting_bible prefix entry; every descendant inherits it through its own log
• Word budget — each level splits its expected_word_count among children by plan weight
• Writing style — accumulated verbatim down the chain (style stacking)
• Writing constraint — scoped, never merged: each level carries its own entries, its planner sees the level above as the rules in force, and a scene's prose prompt renders only the scene's own list
• Unit partition — a level's children are proposed as one batch per parent, so the batch itself is the partition: the ## Requirements block in the plan prompt keeps every unit inside the parent's description and makes the units cover it exactly once
• Character arcs — the roster fixes both endpoints; intermediate boundary cards are proposed per level and stitched in code; scenes receive the finished span list read-only

Composed prose flows back up: scene content enters the logs, and Novel.from_context aggregates the whole tree for export.

How a scene prompt is assembled

The scene write is the only content-producing call, so its prompt is engineered for provider prefix caching: every row above ## Scene is byte-identical across the scenes of a story, and divergence starts exactly at the per-scene tail.

Benchmark

Every finished run is measured against its own artifacts — no LLM calls, no re-execution. w/wr/wri print the scorecard right after the run, next to the delta against the newest comparable earlier run:

• Hard gates — terms the corpus marks as gated, a chapter export that disagrees with the scenes, an empty scene, prose in the wrong script.
• Compared metrics — length against target, both sides in the framework's own words (the core's word_count, the same counter the scene planner's satisfaction ratio uses), seam echo (the same moment written at the end of one scene and again at the top of the next), verbatim sentence repeats, cross-scene 12-gram overlap, sentence lengths (mean, median, max, spread and the share of run-on sentences, on the core's Unicode sentence segmentation), vocabulary repeats (how many n-grams repeat inside a fixed-size window, plus the most repeated n-grams), watch-term rate, run duration. Sentences and vocabulary are counted in characters, so every metric reads the same for a Chinese and an English run without a per-language rule.
• Provenance — a plan_fingerprint over the planning snapshots: two runs sharing it replayed planning from the cache, so they compare per scene, with an exact sign test over the scenes that changed.

A metric that moves off zero is never called noise — one gated term is a regression regardless of sample size. A metric with no better side (how long the sentences are, how much their lengths vary) reports an out-of-band move as drift instead of inventing a verdict. Semantic over-run (a scene staging the next scene's beats in its own words) is deliberately not gated: calibration showed term statistics cannot decide it, which is why benchmark/scorecard.py records what is measurable and what is not.

The three reports are handlebars templates (bench_scorecard, bench_comparison, bench_board), so their wording and layout change without touching the scorer. The scorer only measures: every number a report prints is carried by the models themselves as a *_display field (handlebars has no arithmetic helpers, so rounding, percentages and units are precomputed next to the measurement), and --json leaves those report-only fields out of the machine-readable form.

Each model also owns how it is read and measured, as classmethod factories — StageArtifact.collect/ load, SceneRef.collect, SceneScore.of, RepetitionScore.of, ProbeScore.of and their siblings — so benchmark/scorecard.py only sequences those factories and no measurement lives outside the model that carries it.

Content probes

Term lists belong to a corpus, not to this package, so they are supplied per corpus as a JSON file: gated terms fail the run when they appear in the prose, watch terms are reported per 1000 characters (raw and unlicensed — vocabulary the outline or the bible uses itself is licensed), and each aliases group warns when one novel mixes two names for the same object. Point benchmark_probes (see Configuration) at a file and the post-run report measures every run against it, or pass --probes per invocation. Without a probe file the corpus-independent metrics still run, and the probe row reads not configured.

fanvl bench score novels/20260101-101010     # one run's scorecard (--json for the raw form)
fanvl bench compare novels/20260101-101010   # against the newest comparable run (--against to pin one)
fanvl bench board novels -n 12               # the newest runs side by side
fanvl bench score novels/20260101-101010 --probes corpus/probes.json

Key Classes

Context channels

Every channel carries its running manuscript as an append-only ContextLog: composed blocks enter as frozen ContextEntry records, parents seed children with pure log snapshots, and prompts render them exactly like the former prefixed-content strings. Logs support with_entry/with_entries appends, branch() to fork alternative continuations from any point (copy-on-write), and clear() which returns a fresh empty log while the original history stays intact.

Plans & models

Capabilities (mixins)

Actions (staged workflow)

Every stage wraps one compose_novel chain segment and fires the chain's lifecycle hooks at their chain positions, so a hook override on a stage customizes the staged run exactly like it customizes the programmatic chain; the scene-level hooks fire inside compose_scenes_phase, exactly as they do in the chain.

Workflows

Rust / PyO3

Configuration

All options below are read through the fabricatio configuration chain (see the Configuration Guide). Set them under the [ext.novel] table in fabricatio.toml, equivalently under [tool.fabricatio.ext.novel] in pyproject.toml, or via FABRICATIO_EXT__NOVEL__<FIELD_UPPER> environment variables.

[ext.novel]
novel_metadata_requirement_template = "built-in/novel_metadata_requirement"

Access at runtime: from fabricatio_novel.config import novel_config.

Usage

CLI

# Generate a novel from an outline
fanvl w -o "In a world where dreams are currency..."

# Generate with writing style RAG (LanceDB)
fanvl wr -o "In a world where dreams are currency..." -rq "Hemingway terse prose style"

# Generate with RAG + ComfyUI scene illustrations embedded in the EPUB
fanvl wri -o "In a world where dreams are currency..." -rq "Hemingway terse prose style"
fanvl wri -o "..." --choose-loras  # per-scene LLM-chosen LoRAs from the [ext.comfyui] catalog
fanvl wri -o "..." --judge --judge-tries 5  # vision-judge each illustration; retry with a revised prompt up to N total attempts

# Constrain generation with a setting bible + global writing constraint
fanvl w -o "..." -b settings/bible.json -c "first person view throughout"

# Export as plain text instead of (or besides) EPUB: chapters/01.txt, 02.txt, …
fanvl w -o "..." --format both
fanvl w -o "..." --format txt

# Create / update / show the setting bible
fanvl bible create -o "In a world where dreams are currency..." --out settings/bible.json
fanvl bible update settings/bible.json -o "..." --sections characters
fanvl bible show settings/bible.json

# Store reference texts as writing style documents in LanceDB
fanvl store-refs ./corpus/*.txt
fanvl enrich-refs ./corpus/*.txt -eg "Extract world-building facts"

Programmatic

from fabricatio_novel.workflows.novel import DebugNovelWorkflow
from fabricatio_core import Event

event = Event.instantiate("write")
event.payload["novel_outline"] = "In a world where dreams are currency..."
role = Role.with_bio(name="writer").subscribe(event, DebugNovelWorkflow).dispatch()

EPUB Builder (Rust)

from fabricatio_novel.rust import NovelBuilder, text_to_xhtml_paragraphs

xhtml = text_to_xhtml_paragraphs(raw_chapter_text)

builder = (
    NovelBuilder()
    .new_novel()
    .set_title("My Novel")
    .add_author("Author Name")
    .add_chapter("Chapter 1", xhtml)
    .add_inline_toc()
)

builder.export("output.epub")

Dependencies

• fabricatio-core — Core interfaces, template management, LLM capabilities
• fabricatio-character — Character card models
• pydantic — Data validation via models
• Optional: fabricatio-lancedb — writing style RAG, typer — CLI

License

MIT — see LICENSE