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

Plans materialize into child contexts via from_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
• Word budget — each level splits its expected_word_count among children by plan weight
• Writing constraint — accumulated verbatim down the chain
• 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.

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"

# 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