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_bible → 04_characters → 05_chapter_plans → 06_story_plans
       → 07_scene_plans → 08_scenes → 09_novel → export

Those snapshots are also the run's resume points. --resume <run> reloads the newest snapshot the run holds as the starting state and restarts at the stage that follows it — the newest stage itself when the run reached the end of the pipeline, so a finished novel can be exported again or drawn. --stage <name>, e.g. 08_scenes, restarts at that stage instead, continuing from the newest snapshot taken before it; the named stage runs again, so it is also the fix for a run that died inside it. In both cases the run drives the same workflow with every stage up to the restart point leaving itself out, so a run stopped mid-novel finishes instead of starting over and nothing already written is paid for twice. A stage the run holds no state before fails the resume before any LLM call rather than quietly running the novel again, and a run is only ever resumed by a command of its own family: w for a plain run, wr/wri for a sealed one. Everything the snapshot carries comes back with it — the outline, the resolved skills, the retrieval settings and the seals — while routing (--send-to) and the export options are per invocation and are stated again as usual. The two sealed commands interchange, so wri --resume <wr run> --stage 09_novel draws the illustrations of a novel that was written without them.

An optional RAG variant (RagDebugNovelWorkflow) retrieves WritingStyleDocument entries from LanceDB at two levels. The novel level searches the outline in the init stage's before-hook and renders the documents into the metadata and chapter-planning prompts. The chapter level retrieves once per story, renders the documents raw into that story's scene prompts, and stops rendering them into later prefix walks once every scene of the story carries content (the raw texts stay on the context for scoring and audit).

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 and constraint channels are stacked explicitly by the composing capability — set_writing_styles and set_writing_constraints each receive the parent's list followed by the child plan's own — so both accumulate down the chain, the novel's own channels being seeded from the novel plan. 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
• Selected skills — the names the user gave (plus their lookup roots) are resolved once at the root, carried by every level, and fetched by name from the skill library whenever a prompt is assembled: one byte-stable section heads the metadata proposal, the setting bible proposals, the roster-span proposal, the boundary-card proposals, every plan prompt, every scene write prompt and every RAG query refinement
• Word budget — each level splits its expected_word_count among children by plan weight
• Writing style — accumulated verbatim down the chain (style stacking); entries select the diction the prose must use — from the run's skill documents when the run carries them — rather than inventing amounts
• Writing constraint — accumulated verbatim down the chain (constraint stacking): the ancestors' entries first, the level's own last, and the whole list reaches that level's planner and every scene's prose prompt; where two contradict, the later (deeper) entry wins
• 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 thirty most frequent n-grams of every size from one to six), 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.

Every number above is measured in Rust — one Measure trait per signal, in fabricatio_novel.rust — and the scorer only sequences those measures: it owns the report and never re-measures, so a metric a measure adds reaches the scorecard JSON without a change here. The sizes a run is measured at live under [ext.novel.benchmark] (see Configuration).

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 scorecard and the comparison are handlebars templates (bench_scorecard, bench_comparison), so their wording and layout change without touching the scorer; the board is one table and nothing else, so Board renders it directly. 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 a table's column widths span several rows (Comparison.table, Board), so the models measure and pad it for the same reason and the template prints it as-is; --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 live in one table beside it — probes.toml in the working directory, which every fanvl bench command reads without being handed a path. 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.

gated   = ["hologram"]              # every occurrence fails the run
watch   = ["sapphire"]              # counted per 1000 characters
aliases = [["lamp", "lantern"]]     # names one object must not alternate between

JSON works as well. --probes measures a single invocation against another table, and fanvl bench scan applies the same table to prose that has no run directory behind it:

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 scan novels/ draft.txt           # manuscripts, chapters, drafts (dirs read every *.txt)
fanvl bench score novels/20260101-101010 --probes corpus/probes.toml

--probes defaults to probes.toml in the working directory, so a project with one table never repeats a path, and a path that does not exist only skips the probe rows — the benchmark never fails a run over its probe file. Without a table the corpus-independent metrics still run, and the probe row reads not configured.

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)

The structured stages (02–07: metadata, setting bible, roster spans, and the three plan levels) fall back to the PLAN agent variant: a run whose context names no routing group proposes and plans through the [agent] plan slot, while the scene write (08) and assembly (09) keep their TASK default and the illustrated pipeline's illustration proposals ride the SMOL variant — mechanical prompt drafting that need not ride the run's writing group. An explicit --send-to still governs every stage alike. Leave --send-to unset to plan on the plan model, keep the prose on the TASK model, and draft illustrations on the SMOL model.

The RAG query refinement is no stage of its own: decomposing a level's text into search heads is mechanical, so it rides the SMOL agent variant — arefined_query's own default — and neither --send-to nor a level's fallback moves it off the [agent] smol slot. A decomposition that never arrives — the reply parses into no list — is asked again, up to rag_decompose_attempts times, each retry bypassing the cache read so a stored failure is refreshed rather than replayed, and a level still unanswered after that searches its raw text; an empty answer is the model's own verdict, so that level retrieves nothing at all, while a lone head is discarded for the raw text.

The scene write is guarded against refusals. A model that declines answers with a few hundred characters of policy prose in place of the scene, which the scene's own word budget already gives away: measured on a refused run, every refusal came back at 0.15–0.78 of its budget, while every composed scene ran 1.03–2.11. A reply under scene_refusal_ratio_floor is a refusal and nothing is asked, one at or above scene_refusal_ratio_accept is prose and nothing is asked, and only the band between them goes to ajudge on the SMOL tier, asking whether the requested scene is present rather than whether the answer reads as a refusal — a refusal-shaped question reads explicit prose as one — while a verdict that comes back unparseable counts as a refusal, because a reply nobody could vouch for is not one to write down. Every refusal is asked again, up to scene_refusal_max_retries times, with the cache read bypassed but the answer still stored, so the refusal sitting in the cache for that prompt is replaced rather than replayed. A scene refused on its last attempt raises SceneRefusedError and the run stops: a refusal is not prose, and written down it would reach the chapter, the prefix every later scene reads, and the EPUB with nothing downstream to flag it. refusal_ratio_floor, refusal_ratio_accept and refusal_max_retries on a role override the [ext.novel] defaults for that role's scenes.

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

Every measure is one implementation of one trait, so a new measurement is a new type and nothing else: it reads any iterator of documents (Measure<T> where T: AsRef<str> — scenes, drafts, whole manuscripts), returns its own report, and names its numbers <measure>.<metric> through Reported. A report carries the evidence it was read from (the pairs, the seams, the ordered gram counts) and the flat metrics() list the scorecard JSON publishes, so a measure that gains a number reaches the artifact without a Python change. The sizes a run is measured at are calibrated once, in Knobs::default(); [ext.novel.benchmark] moves any of them for a run.

from fabricatio_novel.rust import Knobs, measure_repetition, measure_script, measure_vocabulary

knobs = Knobs(seam_size=4)          # only the named knob moves off its calibrated value
measured = measure_vocabulary(prose, knobs)
print(measured.size, measured.distinct, measured.windows, measured.recycled_per_1k)
for table in measured.tables:       # every size from 1 to 6, 30 grams each by default
    print(table.size, table.distinct, table.tops[:5])

repeats = measure_repetition([scene.content for scene in scenes])
print(repeats.max_pair, repeats.median_pair, repeats.p90_pair, repeats.worst_seam_index, repeats.loud_pairs)

print(measure_script(prose).cjk_share)

Vocabulary windows are packed into integers (21 bits per scalar value) and counted by sorting, so measuring a 200k-character text costs one pass and a single key vector per size rather than a string per window. Only the grams a report names are ranked and unpacked — the tail is selected away rather than sorted — so naming thirty grams of each of the six sizes costs about half a millisecond on that text.

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"

[ext.novel.benchmark] re-takes every measurement at other sizes than the calibrated ones; every key is optional, and a key left unset keeps the value the measures were calibrated with:

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
fanvl w -o "..." -b settings/bible.json

# Write with the user's own skills from the fabricatio-skill library
fanvl w  -o "..." -s terse-action -s no-adverbs   # repeatable, or comma-separated: -s terse-action,no-adverbs
# Extra skill roots are configured once, not per run: [ext.skill] extra_skill_dirs in fabricatio.toml

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

# Resume a run that stopped mid-novel without re-running what is on disk
fanvl wr --resume novels/20260101-101010                    # restarts at the stage after the newest snapshot
fanvl wr --resume novels/20260101-101010 --stage 08_scenes  # restarts at the prose stage, running it again

# Draw the illustrations of a novel that was written without them
fanvl wri --resume novels/20260101-101010 --stage 09_novel --judge

# 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"

Skills

Skills are built into novel composition, not an add-on: a run names them and every planning prompt and scene write honors them. --skill/-s (repeatable, comma-separated allowed) resolves each name through the fabricatio-skill library — <root>/<name>/SKILL.md then <root>/<name>.md, over the cross-client skill dirs plus [ext.skill] extra_skill_dirs — and a name that resolves nowhere is logged by the library, with the roots it searched, while the run goes on with the names that resolved. Extra skill roots are configured there once (extra_skill_dirs), never per run.

The run binds only the names it resolved to its root context (skill_names), and every level carries that selection the way it carries outline. The bodies stay in the process-wide fabricatio-skill library, which parses a skill once and hands the same text to every walk: prompt assembly fetches them by name through ctx.skill_references(), so a run renders byte-identical text on every walk and a tree rebuilt in a fresh process re-reads exactly the files it resolved (a name that no longer resolves is logged and dropped rather than crashing the walk that renders it). Each reference comes back rendered as <name>body</name> — the skill's body wrapped in a tag named after it — so a prompt separates one skill's instructions from the next.

The resolved text forms one section (ctx.skill_section()) whose bytes are identical everywhere they appear: the metadata proposal, the setting bible proposals, the roster-span and boundary-card proposals, every plan prompt and every scene write prompt render it as their first block — ahead of the outline, or, for a scene, ahead of the manuscript block — so a run's calls to one model open with the same head and the provider's prefix cache carries over between them. The refinement prompt builds its head the same way: the section is prepended to the wrapped outline its template renders at byte 0. Nothing stores the text as prompt context: the log carries the manuscript itself, and the section is rendered from the root's skill_names wherever a prompt shows it.

import asyncio

from fabricatio_novel.actions.novel import InitNovelContext

ctx = asyncio.run(
    InitNovelContext().init_novel_context("In a world where dreams are currency...", skills=["terse-action"])
)

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..."
event.payload["skills"] = ["terse-action"]  # resolved once at the root, honored by every prompt
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-skill — Markdown skill library the run resolves its --skill names against
• fabricatio-character — Character card models
• pydantic — Data validation via models
• Optional: fabricatio-lancedb — writing style RAG, typer — CLI

License

MIT — see LICENSE