Metadata-Version: 2.4
Name: fabricatio-novel
Version: 0.11.4
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Typing :: Typed
Requires-Dist: fabricatio-character
Requires-Dist: fabricatio-comfyui
Requires-Dist: fabricatio-core
Requires-Dist: pydantic>=2.11.9
Requires-Dist: fabricatio-novel[workflows] ; extra == 'cli'
Requires-Dist: questionary>=2.1.0 ; extra == 'cli'
Requires-Dist: typer>=0.15.2 ; extra == 'cli'
Requires-Dist: fabricatio-comfyui ; extra == 'comfyui'
Requires-Dist: fabricatio-novel[workflows,cli,rag] ; extra == 'full'
Requires-Dist: fabricatio-lancedb ; extra == 'lancedb'
Requires-Dist: fabricatio-actions ; extra == 'workflows'
Provides-Extra: cli
Provides-Extra: comfyui
Provides-Extra: full
Provides-Extra: lancedb
Provides-Extra: workflows
Summary: An extension of fabricatio
Author-email: Whth <zettainspector@foxmail.com>
License-Expression: MIT
Requires-Python: >=3.12, <3.15
Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
Project-URL: Homepage, https://github.com/Whth/fabricatio
Project-URL: Issues, https://github.com/Whth/fabricatio/issues
Project-URL: Repository, https://github.com/Whth/fabricatio

# `fabricatio-novel`

[MIT](https://img.shields.io/badge/license-MIT-blue.svg)
![Python Versions](https://img.shields.io/pypi/pyversions/fabricatio-novel)
[![PyPI Version](https://img.shields.io/pypi/v/fabricatio-novel)](https://pypi.org/project/fabricatio-novel/)
[![PyPI Downloads](https://static.pepy.tech/badge/fabricatio-novel/week)](https://pepy.tech/projects/fabricatio-novel)
[![PyPI Downloads](https://static.pepy.tech/badge/fabricatio-novel)](https://pepy.tech/projects/fabricatio-novel)
[![Bindings: PyO3](https://img.shields.io/badge/bindings-pyo3-green)](https://github.com/PyO3/pyo3)
[![Build Tool: uv + maturin](https://img.shields.io/badge/built%20with-uv%20%2B%20maturin-orange)](https://github.com/astral-sh/uv)

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

## Installation

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

For the CLI tool:

```bash
pip install fabricatio-novel[cli]
```

## Pipeline

Novel generation runs as a five-stage sequential pipeline driven by Handlebars templates.

1. **Draft** — Outline text → `NovelDraft` (title, genre, synopsis, chapter list, character descriptions, language
   detection)
2. **Characters** — `NovelDraft` → `CharacterCard[]` (one per described character)
3. **Scripts** — `NovelDraft` + `CharacterCard[]` → `Script[]` (batched; each script is a list of `Scene` objects with
   per-scene prompts and global writing guidance)
4. **Chapters** — `Script[]` + `CharacterCard[]` → raw chapter text (sequential; each chapter receives a rolling
   `ChapterSummary` from the previous chapter for narrative continuity)
5. **Assembly** — Components assembled into a `Novel` object; `NovelBuilder` (Rust/PyO3) produces the EPUB

An optional RAG variant (`NovelComposeRAG`) queries LanceDB for `WritingStyleDocument` entries and injects them into
script-level `global_prompt` and scene-level `prompt` fields before chapter generation.

## Key Classes

### Models

| Class                  | Description                                                                                                                                                                                        |
|------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `NovelDraft`           | High-level novel plan: title, genre, synopsis, character descriptions, ordered `ChapterDraft` list, expected word count                                                                            |
| `ChapterDraft`         | Per-chapter outline with title, detailed synopsis, and weight (for word-count allocation)                                                                                                          |
| `Script`               | Sequence of `Scene` objects with a `global_prompt` for chapter-level writing guidance                                                                                                              |
| `Scene`                | Basic narrative unit: narrative description, tone/style prompt, tags, weight                                                                                                                       |
| `ChapterSummary`       | Structured summary of a generated chapter — key events, character states, character knowledge, numerical stats, emotional arc, unresolved threads, resolved threads, established facts, last scene |
| `ChapterPlan`          | Bundles a `ChapterDraft`, its `Script`, and computed word count per chapter                                                                                                                        |
| `Chapter`              | Final chapter with XHTML content, zero-based index, and word count                                                                                                                                 |
| `Novel`                | Collection of `Chapter` objects with aggregate word count, compliance ratio, and ``export_chapters_as_texts()`` for per-chapter text file export                                                   |
| `WritingStyleDocument` | LanceDB-backed document for storing and retrieving writing style references                                                                                                                        |
| `NovelConfig`          | Frozen dataclass specifying built-in template names for all pipeline stages                                                                                                                        |

### Capabilities (Mixins)

| Class             | Description                                                                                                                                     |
|-------------------|-------------------------------------------------------------------------------------------------------------------------------------------------|
| `NovelCompose`    | Full pipeline: `create_draft`, `create_characters`, `create_scripts`, `create_chapters`, `summarize_chapter`, `assemble_novel`, `compose_novel` |
| `NovelComposeRAG` | Extends `NovelCompose` — fetches writing style docs from LanceDB and injects them into script/scene prompts before chapter generation           |

### Actions (fabricatio-actions)

| Class                                    | Description                                                  |
|------------------------------------------|--------------------------------------------------------------|
| `GenerateNovelDraft`                     | Generate a `NovelDraft` from an outline                      |
| `GenerateCharactersFromDraft`            | Generate `CharacterCard` list from a draft                   |
| `GenerateScriptsFromDraftsAndCharacters` | Generate `Script` list from draft + characters               |
| `GenerateChaptersFromScripts`            | Generate chapter text sequentially from scripts + characters |
| `AssembleNovelFromComponents`            | Build final `Novel` from draft, plans, and chapter contents  |
| `ValidateNovel`                          | Validate chapter count, word count, and compliance ratio     |
| `GenerateNovel`                          | Run the full pipeline in one action                          |
| `DumpNovel`                              | Serialize a `Novel` to disk as EPUB via `NovelBuilder`       |

### Workflows (fabricatio-actions)

| Workflow                              | Description                                                                          |
|---------------------------------------|--------------------------------------------------------------------------------------|
| `WriteNovelWorkflow`                  | One-step outline → EPUB                                                              |
| `DebugNovelWorkflow`                  | Step-by-step: draft → characters → scripts → chapters → validation → assembly → dump |
| `GenerateOnlyCharactersWorkflow`      | Draft → characters only, for iterating on character design                           |
| `RewriteChaptersOnlyWorkflow`         | Reuse existing scripts + characters to regenerate chapter prose                      |
| `ValidatedNovelWorkflow`              | Full pipeline with quality gates (min chapters, word count, compliance ratio)        |
| `RegenerateWithNewCharactersWorkflow` | A/B test character impact by re-running with fresh character generation              |
| `DumpOnlyWorkflow`                    | Export a pre-built `Novel` object to EPUB                                            |

### Rust / PyO3

| Symbol                     | Description                                                                                                                                 |
|----------------------------|---------------------------------------------------------------------------------------------------------------------------------------------|
| `NovelBuilder`             | Builder for EPUB 3.0 novels: set title/description/authors, add chapters (auto-XHTML), cover images, fonts, CSS, inline TOC, export to file |
| `text_to_xhtml_paragraphs` | Convert plain text with newline-separated paragraphs to `<p>`-wrapped XHTML                                                                 |

## Usage

### CLI

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

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

# Generate with mental state tracking (character psychology)
fanvl wm -o "In a world where dreams are currency..."

# Generate with RAG + mental state tracking
fanvl wrm -o "In a world where dreams are currency..." -rq "Hemingway terse prose style"

# Generate with mental state tracking + illustrations
fanvl wmi -o "In a world where dreams are currency..."

# Generate with RAG + mental state tracking + illustrations
fanvl wrmi -o "In a world where dreams are currency..." -rq "Hemingway terse prose style"

# Store reference texts as writing style documents in LanceDB
fanvl store-refs ./corpus/*.txt
```

### Programmatic

```python
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)

```python
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")
```

### Text Export

```python
from pathlib import Path
from fabricatio_novel.models.novel import Novel

# Export each chapter as chapter-{index}.txt with a metadata.json file.
novel.dump_artifacts("./novel-text")
# → ./novel-text/chapter-0.txt
# → ./novel-text/chapter-1.txt
# → ./novel-text/metadata.json
```

Each ``.txt`` file starts with the chapter title, a blank line, then the chapter content.
``metadata.json`` contains the novel title, synopsis, and chapter listing with filenames.

## Dependencies

- `fabricatio-core` — Core interfaces, template management, LLM capabilities
- `fabricatio-character` — Character generation and card models
- `pydantic` — Data validation via models
- Optional: `fabricatio-lancedb` — Writing style RAG, `fabricatio-actions` — workflow support, `questionary` + `typer` —
  CLI

## License

MIT — see [LICENSE](../../LICENSE)

