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

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 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
• 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)
• 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 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)

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"

# 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

# 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).

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