fabricatio-novel 0.1.1__cp313-cp313-manylinux_2_34_x86_64.whl

fabricatio_novel/__init__.py

@@ -0,0 +1 @@
+"""An extension of fabricatio."""

fabricatio_novel/actions/__init__.py

@@ -0,0 +1 @@
+"""Actions defined in fabricatio-novel."""

fabricatio_novel/actions/novel.py

@@ -0,0 +1,337 @@
+"""This module provides actions related to novel generation and management.
+
+It includes classes such as GenerateNovel for creating novels based on prompts,
+and DumpNovel for saving generated novels to a specified file path. These actions
+leverage capabilities from the fabricatio_core and interact with both Python and
+Rust components to perform their tasks.
+"""
+
+from pathlib import Path
+from typing import Any, ClassVar, List, Optional
+
+from fabricatio_character.models.character import CharacterCard
+from fabricatio_core import Action, logger
+from fabricatio_core.utils import ok
+
+from fabricatio_novel.capabilities.novel import NovelCompose
+from fabricatio_novel.models.novel import Novel, NovelDraft
+from fabricatio_novel.models.scripting import Script
+from fabricatio_novel.rust import NovelBuilder
+
+
+class GenerateCharactersFromDraft(NovelCompose, Action):
+    """Generate character cards from a NovelDraft."""
+
+    novel_draft: Optional[NovelDraft] = None
+    """
+    The novel draft from which to generate characters.
+    """
+
+    output_key: str = "novel_characters"
+    """
+    Key under which the generated list of CharacterCard will be stored in context.
+    """
+
+    ctx_override: ClassVar[bool] = True
+
+    async def _execute(self, *_: Any, **cxt) -> List[CharacterCard] | None:
+        draft = ok(self.novel_draft, "`novel_draft` is required for character generation")
+        logger.info(f"Generating characters for novel draft: '{draft.title}'")
+        characters = await self.create_characters(draft)
+        if characters is None:
+            logger.warn("Character generation returned None.")
+            return None
+        valid_chars = [c for c in characters if c is not None]
+        logger.info(f"Generated {len(valid_chars)} valid character(s).")
+        return valid_chars
+
+
+class GenerateScriptsFromDraftAndCharacters(NovelCompose, Action):
+    """Generate chapter scripts from a draft and list of characters."""
+
+    novel_draft: Optional[NovelDraft] = None
+    """
+    The novel draft containing chapter synopses.
+    """
+
+    novel_characters: Optional[List[CharacterCard]] = None  # ← renamed for clarity & collision avoidance
+    """
+    List of character cards to be used in script generation.
+    """
+
+    output_key: str = "novel_scripts"
+    """
+    Key under which the generated list of Script will be stored in context.
+    """
+
+    ctx_override: ClassVar[bool] = True
+
+    async def _execute(self, *_: Any, **cxt) -> List[Script] | None:
+        draft = ok(self.novel_draft)
+        characters = ok(self.novel_characters)  # ← consume from context as "novel_characters"
+        logger.info(f"Generating scripts for '{draft.title}' with {len(characters)} character(s).")
+        scripts = await self.create_scripts(draft, characters)
+        if scripts is None:
+            logger.warn("Script generation returned None.")
+            return None
+        valid_scripts = [s for s in scripts if s is not None]
+        logger.info(f"Generated {len(valid_scripts)} valid script(s).")
+        return valid_scripts
+
+
+class GenerateChaptersFromScripts(NovelCompose, Action):
+    """Generate full chapter contents from scripts and characters."""
+
+    novel_draft: Optional[NovelDraft] = None
+    """
+    The novel draft (for language, metadata).
+    """
+
+    novel_scripts: Optional[List[Script]] = None  # ← renamed
+    """
+    The list of chapter scripts to expand into full text.
+    """
+
+    novel_characters: Optional[List[CharacterCard]] = None  # ← renamed
+    """
+    The list of characters to provide context.
+    """
+    chapter_guidance: Optional[str] = None
+    """
+    Guidance for writing chapter.
+    """
+
+    output_key: str = "novel_chapter_contents"
+    """
+    Key under which the generated list of chapter content strings will be stored in context.
+    """
+
+    ctx_override: ClassVar[bool] = True
+
+    async def _execute(self, *_: Any, **cxt) -> List[str] | List[str | None] | None:
+        draft = ok(self.novel_draft)
+        scripts = ok(self.novel_scripts)
+        characters = ok(self.novel_characters)
+
+        logger.info(f"Generating {len(scripts)} chapter contents for '{draft.title}'.")
+        chapter_contents = await self.create_chapters(draft, scripts, characters, self.chapter_guidance)
+        if not chapter_contents:
+            logger.warn("Chapter content generation returned empty or None.")
+            return None
+        logger.info(f"Successfully generated {len(chapter_contents)} chapter content(s).")
+        return chapter_contents
+
+
+class AssembleNovelFromComponents(NovelCompose, Action):
+    """Assemble final Novel object from draft, scripts, and chapter contents."""
+
+    novel_draft: Optional[NovelDraft] = None
+    """
+    The original draft containing title, synopsis, etc.
+    """
+
+    novel_scripts: Optional[List[Script]] = None  # ← renamed
+    """
+    Scripts containing chapter titles and metadata.
+    """
+
+    novel_chapter_contents: Optional[List[str]] = None  # ← renamed
+    """
+    Generated full text for each chapter.
+    """
+
+    output_key: str = "novel"
+    """
+    Key under which the assembled Novel object will be stored in context.
+    """
+
+    ctx_override: ClassVar[bool] = True
+
+    async def _execute(self, *_: Any, **cxt) -> Novel:
+        draft = ok(self.novel_draft)
+        scripts = ok(self.novel_scripts)
+        chapter_contents = ok(self.novel_chapter_contents)
+
+        logger.info("Assembling final novel from components...")
+        novel = self.assemble_novel(draft, scripts, chapter_contents)
+        logger.info(f"Novel '{novel.title}' assembled with {len(novel.chapters)} chapters.")
+        return novel
+
+
+class ValidateNovel(Action):
+    """Validate the generated novel for compliance and structure."""
+
+    novel: Optional[Novel] = None
+    """
+    The novel to validate.
+    """
+
+    output_key: str = "novel_is_valid"
+    """
+    Key under which the validation result (bool) will be stored in context.
+    """
+
+    min_chapters: int = 1
+    min_total_words: int = 1000
+    min_compliance_ratio: float = 0.8
+
+    ctx_override: ClassVar[bool] = True
+
+    async def _execute(self, *_: Any, **cxt) -> bool:
+        novel = ok(self.novel)
+
+        issues = []
+
+        if len(novel.chapters) < self.min_chapters:
+            issues.append(f"Too few chapters: {len(novel.chapters)} < {self.min_chapters}")
+
+        if novel.exact_word_count < self.min_total_words:
+            issues.append(f"Too few words: {novel.exact_word_count} < {self.min_total_words}")
+
+        if novel.word_count_compliance_ratio < self.min_compliance_ratio:
+            issues.append(
+                f"Low compliance ratio: {novel.word_count_compliance_ratio:.2%} < {self.min_compliance_ratio:.2%}"
+            )
+
+        if issues:
+            logger.warn(f"Novel validation failed for '{novel.title}': {'; '.join(issues)}")
+            return False
+        logger.info(f"Novel '{novel.title}' passed validation.")
+        return True
+
+
+class GenerateNovelDraft(NovelCompose, Action):
+    """Generate a novel draft from a prompt."""
+
+    novel_outline: Optional[str] = None
+    """
+    The prompt used to generate the novel. If not provided, execution will fail.
+    """
+
+    novel_language: Optional[str] = None
+    """
+    The language of the novel. If not provided, will infer from the prompt.
+    """
+
+    output_key: str = "novel_draft"
+    """
+    Key under which the generated NovelDraft will be stored in context.
+    """
+
+    ctx_override: ClassVar[bool] = True
+
+    async def _execute(self, *_: Any, **cxt) -> NovelDraft | None:
+        return await self.create_draft(outline=ok(self.novel_outline), language=self.novel_language)
+
+
+class GenerateNovel(NovelCompose, Action):
+    """An action that generates a novel based on a provided prompt.
+
+    This class inherits from NovelCompose and Action, and is responsible for
+    generating a novel using the underlying novel generation capability.
+    The generated novel is returned as a Novel object.
+    """
+
+    novel_outline: Optional[str] = None
+    """
+    The prompt used to generate the novel. If not provided, execution will fail.
+    """
+
+    novel_language: Optional[str] = None
+    """
+    The language of the novel. If not provided, will infer from the prompt.
+    """
+
+    chapter_guidance: Optional[str] = None
+    """
+    Guidance for writing chapter.
+    """
+
+    output_key: str = "novel"
+    """
+    The key under which the generated novel will be stored in the context.
+    """
+
+    ctx_override: ClassVar[bool] = True
+
+    async def _execute(self, **cxt) -> Novel | None:
+        """Execute the novel generation process.
+
+        Uses the provided novel_prompt to generate a novel via the inherited
+        novel() method from NovelCompose. Returns the generated Novel object.
+
+        Parameters:
+            **cxt: Contextual keyword arguments passed from the execution environment.
+
+        Returns:
+            Novel | None: The generated novel object, or None if generation fails.
+        """
+        return await self.compose_novel(ok(self.novel_outline), self.novel_language, self.chapter_guidance)
+
+
+class DumpNovel(Action):
+    """An action that saves a generated novel to a specified file path.
+
+    This class takes a Novel object and writes its content to a file at the
+    specified path.
+    """
+
+    output_path: Optional[Path] = None
+    """
+    The file system path where the novel should be saved. Required for execution.
+    """
+
+    novel_font_file: Optional[Path] = None
+    """
+    The file system path to the novel font file. like .ttf file.
+    """
+
+    novel: Optional[Novel] = None
+    """
+    The novel object to be saved. Must be provided for successful execution.
+    """
+
+    cover_image: Optional[Path] = None
+    """
+    The file system path to the novel cover image.
+    """
+
+    output_key: str = "novel_path"
+    """
+    The key under which the output path will be stored in the context.
+    """
+
+    ctx_override: ClassVar[bool] = True
+
+    async def _execute(self, *_: Any, **cxt) -> Path:
+        novel = ok(self.novel)
+        path = ok(self.output_path)
+        logger.info(
+            f"Novel word count: [{novel.exact_word_count}/{novel.expected_word_count}] | Compliance ratio: {novel.word_count_compliance_ratio:.2%}"
+        )
+        logger.info(f"Novel Chapter count: {len(novel.chapters)}")
+        logger.info(f"Dumping novel {novel.title} to {path}")
+
+        builder = (
+            NovelBuilder()
+            .new_novel()
+            .set_title(novel.title)
+            .set_description(novel.synopsis)
+            .add_css("p { text-indent: 2em; margin: 1em 0; line-height: 1.5; text-align: justify; }")
+        )
+
+        if self.novel_font_file:
+            (
+                builder.add_font(self.novel_font_file.stem, self.novel_font_file).add_css(
+                    f"p {{ font-family: '{self.novel_font_file.stem}', 'sans-serif'; }}"
+                )
+            )
+
+        if self.cover_image:
+            builder.add_cover_image(self.cover_image.name, self.cover_image)
+
+        for chapter in novel.chapters:
+            builder.add_chapter(chapter.title, chapter.to_xhtml())
+
+        builder.export(path)
+        return path

fabricatio_novel/capabilities/__init__.py

@@ -0,0 +1 @@
+"""Capabilities defined in fabricatio-novel."""

fabricatio_novel/capabilities/novel.py

@@ -0,0 +1,225 @@
+"""This module contains the capabilities for the novel."""
+
+from abc import ABC
+from typing import List, Optional, Unpack
+
+from fabricatio_character.capabilities.character import CharacterCompose
+from fabricatio_character.models.character import CharacterCard
+from fabricatio_character.utils import dump_card
+from fabricatio_core import TEMPLATE_MANAGER, logger
+from fabricatio_core.capabilities.propose import Propose
+from fabricatio_core.capabilities.usages import UseLLM
+from fabricatio_core.models.kwargs_types import ValidateKwargs
+from fabricatio_core.rust import detect_language
+from fabricatio_core.utils import ok, override_kwargs
+
+from fabricatio_novel.config import novel_config
+from fabricatio_novel.models.novel import Chapter, Novel, NovelDraft
+from fabricatio_novel.models.scripting import Script
+from fabricatio_novel.rust import text_to_xhtml_paragraphs
+
+
+class NovelCompose(CharacterCompose, Propose, UseLLM, ABC):
+    """This class contains the capabilities for the novel."""
+
+    async def compose_novel(
+        self,
+        outline: str,
+        language: Optional[str] = None,
+        chapter_guidance: Optional[str] = None,
+        **kwargs: Unpack[ValidateKwargs[Novel]],
+    ) -> Novel | None:
+        """Main novel composition pipeline."""
+        logger.info(f"Starting novel generation for outline: {outline[:100]}...")
+        okwargs = override_kwargs(kwargs, default=None)
+
+        # Step 1: Generate draft
+        logger.debug("Step 1: Generating novel draft from outline")
+        draft = ok(await self.create_draft(outline, language, **okwargs))
+        if not draft:
+            logger.warn("Failed to generate novel draft.")
+            return None
+        logger.info(f"Draft generated successfully: '{draft.title}' in {draft.language}")
+
+        # Step 2: Generate characters
+        logger.debug("Step 2: Generating character cards from draft")
+        characters: List[CharacterCard] = [
+            c for c in ok(await self.create_characters(draft, **okwargs)) if c is not None
+        ]
+        logger.info(f"Generated {len(characters)} valid character(s)")
+
+        # Step 3: Generate scripts
+        logger.debug("Step 3: Generating chapter scripts using draft and characters")
+        scripts = ok(await self.create_scripts(draft, characters, **okwargs))
+        clean_scripts = [s for s in scripts if s is not None]
+        if not clean_scripts:
+            logger.warn("No valid scripts were generated from the draft and characters.")
+            return None
+        logger.info(f"Successfully generated {len(clean_scripts)} script(s) for chapters")
+
+        # Step 4: Generate chapter contents
+        logger.debug("Step 4: Generating full chapter contents from scripts")
+        chapter_contents = await self.create_chapters(draft, clean_scripts, characters, chapter_guidance, **okwargs)
+        if not chapter_contents:
+            logger.warn("Chapter content generation returned no results.")
+            return None
+        logger.info(f"Generated {len(chapter_contents)} chapter content(s)")
+
+        # Step 5: Assemble final novel
+        logger.debug("Step 5: Assembling final novel from components")
+        novel = self.assemble_novel(draft, clean_scripts, chapter_contents)
+        logger.info(f"Novel assembly complete: '{novel.title}', {len(novel.chapters)} chapters")
+        return novel
+
+    async def create_draft(
+        self, outline: str, language: Optional[str] = None, **kwargs: Unpack[ValidateKwargs[NovelDraft]]
+    ) -> NovelDraft | None:
+        """Generate a draft for the novel based on the provided outline."""
+        logger.debug(f"Creating draft with outline: {outline[:200]}...")
+        detected_language = language or detect_language(outline)
+        logger.debug(f"Detected language: {detected_language}")
+
+        prompt = TEMPLATE_MANAGER.render_template(
+            novel_config.novel_draft_requirement_template,
+            {"outline": outline, "language": detected_language},
+        )
+        logger.debug(f"Rendered draft prompt:\n{prompt}")
+
+        result = await self.propose(NovelDraft, prompt, **kwargs)
+        if result:
+            logger.info(f"Draft created successfully: '{result.title}' ({result.expected_word_count} words)")
+        else:
+            logger.warn("Draft generation returned None.")
+        return result
+
+    async def create_characters(
+        self, draft: NovelDraft, **kwargs: Unpack[ValidateKwargs[CharacterCard]]
+    ) -> None | List[CharacterCard] | List[CharacterCard | None]:
+        """Generate characters based on draft."""
+        logger.debug(f"Generating characters for novel: '{draft.title}'")
+        if not draft.character_descriptions:
+            logger.warn("No character descriptions found in draft.")
+            return []
+
+        character_prompts = [
+            {
+                "novel_title": draft.title,
+                "synopsis": draft.synopsis,
+                "character_desc": c,
+                "language": draft.language,
+            }
+            for c in draft.character_descriptions
+        ]
+        logger.debug(f"Prepared {len(character_prompts)} character prompts")
+
+        character_requirement = TEMPLATE_MANAGER.render_template(
+            novel_config.character_requirement_template, character_prompts
+        )
+        logger.debug(f"Character requirement template rendered (length: {len(character_requirement)})")
+
+        result = await self.compose_characters(character_requirement, **kwargs)
+        valid_chars = [c for c in (ok(result) or []) if c is not None]
+        logger.info(f"Generated {len(valid_chars)} valid character(s) out of {len(result or [])}")
+        return result
+
+    async def create_scripts(
+        self, draft: NovelDraft, characters: List[CharacterCard], **kwargs: Unpack[ValidateKwargs[Script]]
+    ) -> List[Script] | List[Script | None] | None:
+        """Generate chapter scripts based on draft and characters."""
+        logger.debug(f"Generating {len(draft.chapter_synopses)} chapter scripts for '{draft.title}'")
+        if not characters:
+            logger.warn("No characters provided for script generation.")
+            return []
+        if not draft.chapter_synopses:
+            logger.warn("No chapter synopses in draft.")
+            return []
+
+        character_prompt = dump_card(*characters)
+        logger.debug(f"Serialized {len(characters)} character(s) into prompt format")
+
+        script_prompts = [
+            {
+                "novel_title": draft.title,
+                "characters": character_prompt,
+                "synopsis": s,
+                "language": draft.language,
+                "expected_word_count": c,
+            }
+            for (s, c) in zip(draft.chapter_synopses, draft.chapter_expected_word_counts, strict=False)
+        ]
+        logger.debug(f"Created {len(script_prompts)} script input prompts")
+
+        script_requirement = TEMPLATE_MANAGER.render_template(novel_config.script_requirement_template, script_prompts)
+        logger.debug(f"Script requirement template rendered (length: {len(script_requirement)})")
+
+        result = await self.propose(Script, script_requirement, **kwargs)
+        if result is None:
+            logger.warn("Script proposal returned None.")
+        else:
+            valid_scripts = [s for s in result if s is not None]
+            logger.info(f"Generated {len(valid_scripts)} valid script(s) out of {len(result)}")
+        return result
+
+    async def create_chapters(
+        self,
+        draft: NovelDraft,
+        scripts: List[Script],
+        characters: List[CharacterCard],
+        guidance: Optional[str] = None,
+        **kwargs: Unpack[ValidateKwargs[str]],
+    ) -> List[str] | List[str | None]:
+        """Generate actual chapter contents from scripts."""
+        logger.debug(f"Generating chapter contents for {len(scripts)} script(s)")
+        if not scripts:
+            logger.warn("No scripts provided for chapter generation.")
+            return []
+
+        character_prompt = dump_card(*characters)
+        logger.debug(f"Using {len(characters)} character(s) context for chapter generation")
+
+        chapter_prompts = [
+            {
+                "script": s.as_prompt(),
+                "characters": character_prompt,
+                "language": draft.language,
+                "guidance": guidance,
+                "expected_word_count": s.expected_word_count,
+            }
+            for s in scripts
+        ]
+        logger.debug(f"Prepared {len(chapter_prompts)} chapter generation prompts")
+
+        chapter_requirement: List[str] = TEMPLATE_MANAGER.render_template(
+            novel_config.chapter_requirement_template, chapter_prompts
+        )
+        logger.debug(f"Chapter requirement template length: {len(chapter_requirement)}")
+
+        response = ok(await self.aask(chapter_requirement, **kwargs))
+
+        logger.info(f"Generated {len(response)} chapter content(s)")
+        return response
+
+    @staticmethod
+    def assemble_novel(draft: NovelDraft, scripts: List[Script], chapter_contents: List[str]) -> Novel:
+        """Assemble the final novel from components."""
+        logger.debug("Assembling final novel from draft, scripts, and chapter contents")
+        if len(chapter_contents) != len(scripts):
+            logger.warn(
+                f"Mismatch between number of scripts ({len(scripts)}) and chapter contents ({len(chapter_contents)})"
+            )
+
+        chapters = []
+        for i, (content, script) in enumerate(zip(chapter_contents, scripts, strict=False)):
+            title = script.title or f"Chapter {i + 1}"
+            cleaned_content = text_to_xhtml_paragraphs(content)
+            chapters.append(Chapter(title=title, content=cleaned_content, expected_word_count=0))
+        logger.info(f"Assembled {len(chapters)} chapter(s) into the final novel structure")
+
+        novel = Novel(
+            title=draft.title,
+            chapters=chapters,
+            synopsis=draft.synopsis,
+            expected_word_count=draft.expected_word_count,
+        )
+        logger.debug(f"Final novel assembled: '{novel.title}', total chapters: {len(novel.chapters)}")
+        return novel

fabricatio_novel/cli.py

@@ -0,0 +1,148 @@
+"""Fabricatio Novel CLI.
+
+This module provides a command-line interface to generate novels using AI-driven workflows.
+It utilizes the Fabricatio Core library and includes functionality for generating novels
+with customizable outlines, chapter guidance, language options, styling, and more.
+"""
+
+from pathlib import Path
+from typing import NoReturn
+
+from fabricatio_core.utils import cfg
+
+cfg("fabricatio_novel.workflows", "questionary", "typer", feats=["cli"])
+import typer
+from fabricatio_core import Event, Role, Task
+
+from fabricatio_novel.workflows.novel import DebugNovelWorkflow
+
+app = typer.Typer(help="A CLI tool to generate novels using AI-driven workflows.")
+
+# Register the writer role and workflow
+writer_role = (
+    Role(name="writer").register_workflow(Event.quick_instantiate(ns := "write"), DebugNovelWorkflow).dispatch()
+)
+
+
+def _exit_on_error(message: str) -> NoReturn:
+    """Helper to display error and exit."""
+    typer.secho(message, fg=typer.colors.RED, bold=True)
+    raise typer.Exit(code=1) from None
+
+
+@app.command(name="w")
+def write_novel(  # noqa: PLR0913
+    outline: str = typer.Option(
+        None, "--outline", "-o", help="The novel's outline or premise.", envvar="NOVEL_OUTLINE"
+    ),
+    outline_file: Path = typer.Option(
+        None,
+        "--outline-file",
+        "-of",
+        exists=True,
+        file_okay=True,
+        dir_okay=False,
+        resolve_path=True,
+        help="Path to a text file containing the novel outline.",
+        envvar="NOVEL_OUTLINE_FILE",
+    ),
+    output_path: Path = typer.Option(
+        "./novel.epub", "--output", "-out", dir_okay=False, help="Output EPUB file path.", envvar="NOVEL_OUTPUT_PATH"
+    ),
+    font_file: Path = typer.Option(
+        None,
+        "--font",
+        "-f",
+        exists=True,
+        dir_okay=False,
+        help="Path to custom font file (TTF).",
+        envvar="NOVEL_FONT_FILE",
+    ),
+    cover_image: Path = typer.Option(
+        None,
+        "--cover",
+        "-c",
+        exists=True,
+        dir_okay=False,
+        help="Path to cover image (PNG/JPG/WEBP).",
+        envvar="NOVEL_COVER_IMAGE",
+    ),
+    language: str = typer.Option(
+        "English", "--lang", "-l", help="Language of the novel (e.g., 简体中文, English, jp).", envvar="NOVEL_LANGUAGE"
+    ),
+    chapter_guidance: str = typer.Option(
+        None, "--guidance", "-g", help="Guidelines for chapter generation.", envvar="NOVEL_CHAPTER_GUIDANCE"
+    ),
+    guidance_file: Path = typer.Option(
+        None,
+        "--guidance-file",
+        "-gf",
+        exists=True,
+        file_okay=True,
+        dir_okay=False,
+        resolve_path=True,
+        help="Path to a text file containing chapter generation guidelines.",
+        envvar="NOVEL_GUIDANCE_FILE",
+    ),
+    persist_dir: Path = typer.Option(
+        "./persist", "--persist-dir", help="Directory to save intermediate states.", envvar="NOVEL_PERSIST_DIR"
+    ),
+) -> None:
+    """Generate a novel based on the provided outline and settings."""
+    # Check mutual exclusivity for outline
+    if outline is not None and outline_file is not None:
+        _exit_on_error("❌ Cannot use both --outline and --outline-file. Please use only one.")
+
+    if outline is None and outline_file is None:
+        _exit_on_error("❌ Either --outline or --outline-file must be provided.")
+
+    # Read outline
+    try:
+        outline_content = outline_file.read_text(encoding="utf-8").strip() if outline_file else outline.strip()
+    except (OSError, IOError) as e:
+        _exit_on_error(f"❌ Failed to read outline file: {e}")
+
+    # Check mutual exclusivity for guidance
+    if chapter_guidance is not None and guidance_file is not None:
+        _exit_on_error("❌ Cannot use both --guidance and --guidance-file. Please use only one.")
+
+    # Read guidance
+    try:
+        if guidance_file:
+            guidance_content = guidance_file.read_text(encoding="utf-8").strip()
+        elif chapter_guidance is not None:
+            guidance_content = chapter_guidance.strip()
+        else:
+            guidance_content = ""
+    except (OSError, IOError) as e:
+        _exit_on_error(f"❌ Failed to read guidance file: {e}")
+
+    typer.echo(f"Starting novel generation: '{outline_content[:30]}...'")
+
+    task = Task(name="Write novel").update_init_context(
+        novel_outline=outline_content,
+        output_path=output_path,
+        novel_font_file=font_file,
+        cover_image=cover_image,
+        novel_language=language,
+        chapter_guidance=guidance_content,
+        persist_dir=persist_dir,
+    )
+
+    result = task.delegate_blocking(ns)
+
+    if result:
+        typer.secho(f"✅ Novel successfully generated: {result}", fg=typer.colors.GREEN, bold=True)
+    else:
+        _exit_on_error("❌ Failed to generate novel.")
+
+
+@app.command()
+def info() -> None:
+    """Show information about this CLI tool."""
+    typer.echo("📘 Fabricatio Novel Generator CLI")
+    typer.echo("Generate AI-assisted novels in various languages with customizable styling.")
+    typer.echo("Powered by Fabricatio Core & DebugNovelWorkflow.")
+
+
+__all__ = ["app"]

fabricatio_novel/config.py

@@ -0,0 +1,30 @@
+"""Module containing configuration classes for fabricatio-novel."""
+
+from dataclasses import dataclass
+
+from fabricatio_core import CONFIG
+
+
+@dataclass(frozen=True)
+class NovelConfig:
+    """Configuration for fabricatio-novel."""
+
+    render_script_template: str = "render_script"
+    """template used to render scripts."""
+
+    character_requirement_template: str = "character_requirement"
+    """template used to render character requirements."""
+    script_requirement_template: str = "script_requirement"
+    """template used to render script requirements."""
+    chapter_requirement_template: str = "chapter_requirement"
+    """template used to render chapter requirements."""
+    render_chapter_xhtml_template: str = "render_chapter_xhtml"
+    """template used to render chapter xhtml."""
+    novel_draft_requirement_template: str = "novel_draft_requirement"
+    """template used to render novel draft requirements."""
+
+
+novel_config = CONFIG.load("novel", NovelConfig)
+
+
+__all__ = ["novel_config"]

fabricatio_novel/models/__init__.py

@@ -0,0 +1 @@
+"""Models defined in fabricatio-novel."""

fabricatio_novel/models/novel.py

@@ -0,0 +1,96 @@
+"""This module contains the models for the novel."""
+
+from typing import Any, List
+
+from fabricatio_capabilities.models.generic import PersistentAble, WordCount
+from fabricatio_core import TEMPLATE_MANAGER
+from fabricatio_core.models.generic import Language, SketchedAble, Titled
+from fabricatio_core.rust import logger, word_count
+
+from fabricatio_novel.config import novel_config
+
+
+class NovelDraft(SketchedAble, Titled, Language, PersistentAble, WordCount):
+    """A draft representing a novel, including its title, genre, characters, chapters, and synopsis."""
+
+    title: str
+    """The title of the novel."""
+    genre: List[str]
+    """The genres of the novel. Comprehensive coverage is preferred than few ones."""
+
+    synopsis: str
+    """A summary of the novel's plot."""
+
+    character_descriptions: List[str]
+    """
+    Every string in this list MUST be at least 180 words.
+    Super detailed descriptions for each main character.
+    Include: looks, personality, backstory, goals, relationships, inner struggles, and their role in the story.
+    Goal: Make every character feel real, consistent, and fully fleshed out — no vague or shallow summaries.
+    """
+
+    chapter_synopses: List[str]
+    """
+    Every string in this list MUST be at least 270 words.
+    Super detailed summaries for each chapter.
+    Cover: what happens, how characters change, key scenes/dialogue, setting shifts, emotional tone, and hints or themes.
+    Goal: Lock in every important detail so nothing gets lost later — like a mini-script for each chapter.
+    """
+    expected_word_count: int
+    """The expected word count of the novel."""
+
+    chapter_expected_word_counts: List[int]
+    """List of expected word counts for each chapter in the novel. should be the same length as chapter_synopses."""
+
+    def model_post_init(self, context: Any, /) -> None:
+        """Make sure that the chapter expected word counts are aligned with the chapter synopses."""
+        if len(self.chapter_synopses) != len(self.chapter_expected_word_counts):
+            if self.chapter_expected_word_counts:
+                logger.warn(
+                    "Chapter expected word counts are not aligned with chapter synopses, using the last valid one to fill the rest."
+                )
+                # If word counts are not aligned, copy the last valid chapter's word count
+                last_valid_wc = self.chapter_expected_word_counts[-1]
+                self.chapter_expected_word_counts.extend(
+                    [last_valid_wc] * (len(self.chapter_synopses) - len(self.chapter_expected_word_counts))
+                )
+            else:
+                logger.warn("No chapter expected word counts provided, using the expected word count to fill the list.")
+                # If the word count list is totally empty, distribute the expected word count evenly
+                avg_wc = self.expected_word_count // len(self.chapter_synopses)
+                self.chapter_expected_word_counts = [avg_wc] * len(self.chapter_synopses)
+
+
+class Chapter(SketchedAble, PersistentAble, Titled, WordCount):
+    """A chapter in a novel."""
+
+    content: str
+    """The content of the chapter."""
+
+    def to_xhtml(self) -> str:
+        """Convert the chapter to XHTML format."""
+        return TEMPLATE_MANAGER.render_template(novel_config.render_chapter_xhtml_template, self.model_dump())
+
+    @property
+    def exact_word_count(self) -> int:
+        """Calculate the exact word count of the chapter."""
+        return word_count(self.content)
+
+
+class Novel(SketchedAble, PersistentAble, Titled, WordCount):
+    """A novel."""
+
+    synopsis: str
+    """A summary of the novel's plot."""
+    chapters: List[Chapter]
+    """List of chapters in the novel."""
+
+    @property
+    def exact_word_count(self) -> int:
+        """Calculate the exact word count of the novel."""
+        return sum(chapter.exact_word_count for chapter in self.chapters)
+
+    @property
+    def word_count_compliance_ratio(self) -> float:
+        """Calculate the compliance ratio of the novel's word count."""
+        return self.exact_word_count / self.expected_word_count

fabricatio_novel/models/scripting.py

@@ -0,0 +1,76 @@
+"""This module defines the core data structures for narrative scenes and scripts.
+
+Together, these classes form a foundation for creating structured yet flexible narrative content.
+"""
+
+from typing import Any, ClassVar, Dict, List, Self
+
+from fabricatio_capabilities.models.generic import AsPrompt, PersistentAble, WordCount
+from fabricatio_core.models.generic import SketchedAble, Titled
+from pydantic import Field
+
+from fabricatio_novel.config import novel_config
+
+
+class Scene(PersistentAble, SketchedAble, WordCount):
+    """The most basic narrative unit."""
+
+    expected_word_count: int
+    """Expected word count when writing the content that the Scene is narrating."""
+
+    tags: List[str]
+    """free-form semantic labels for filtering, grouping, or post-processing."""
+
+    prompt: str
+    """natural language guidance for tone, style, or constraint."""
+
+    narrative: str
+    """dialogue, description, log, poem, monologue, etc."""
+
+    def append_prompt(self, prompt: str) -> Self:
+        """Add a prompt to the scene.
+
+        Args:
+            prompt (str): The prompt to add.
+        """
+        self.prompt += f"\n{prompt}"
+        return self
+
+
+class Script(SketchedAble, PersistentAble, Titled, AsPrompt, WordCount):
+    """A sequence of scenes forming a cohesive narrative unit especially for a novel chapter."""
+
+    title: str = Field(examples=["Ch1: A Chapter Title For Example", "Ch1: 一个示例章节标题"])
+    """Title of the chapter."""
+
+    expected_word_count: int
+    """Expected word count for this chapter."""
+
+    global_prompt: str
+    """global writing guidance applied to all scenes."""
+
+    scenes: List[Scene]
+    """Ordered list of scenes. Must contain at least one scene. Sequence implies narrative flow."""
+
+    rendering_template: ClassVar[str] = novel_config.render_script_template
+
+    def _as_prompt_inner(self) -> Dict[str, str] | Dict[str, Any] | Any:
+        return self.model_dump()
+
+    def append_global_prompt(self, prompt: str) -> Self:
+        """Add a global prompt to the script.
+
+        Args:
+            prompt (str): The global prompt to add.
+        """
+        self.global_prompt += f"\n{prompt}"
+        return self
+
+    def set_expected_word_count(self, word_count: int) -> Self:
+        """Set the expected word count for the script.
+
+        Args:
+            word_count (int): The expected word count.
+        """
+        self.expected_word_count = word_count
+        return self

fabricatio_novel/rust.pyi

@@ -0,0 +1,120 @@
+"""Rust bindings for the Rust API of fabricatio-novel."""
+
+from pathlib import Path
+from typing import Self
+
+class NovelBuilder:
+    """A Python-exposed builder for creating EPUB novels."""
+
+    def __init__(self) -> None:
+        """Creates a new uninitialized NovelBuilder instance."""
+
+    def new_novel(self) -> Self:
+        """Initializes a new EPUB novel builder.
+
+        Raises:
+            RuntimeError: If initialization fails.
+        """
+
+    def set_title(self, title: str) -> Self:
+        """Sets the novel title.
+
+        Raises:
+            RuntimeError: If novel is not initialized.
+        """
+    def add_author(self, author: str) -> Self:
+        """Adds an author to the novel metadata.
+
+        Raises:
+            RuntimeError: If novel is not initialized.
+        """
+
+    def add_chapter(self, title: str, content: str) -> Self:
+        """Adds a chapter with given title and content.
+
+        Raises:
+            RuntimeError: If novel is not initialized or chapter creation fails.
+        """
+
+    def set_description(self, description: str) -> Self:
+        """Sets the novel description.
+
+        Raises:
+            RuntimeError: If novel is not initialized.
+        """
+
+    def add_cover_image(self, path: str | Path, source: str | Path) -> Self:
+        """Adds a cover image from the given file path.
+
+        Args:
+            path: Path inside EPUB where image will be stored (e.g., "cover.png").
+            source: Filesystem path to the image file to read.
+
+        Raises:
+            RuntimeError: If novel not initialized, file read fails, or adding image fails.
+        """
+
+    def add_metadata(self, key: str, value: str) -> Self:
+        """Adds custom metadata key-value pair to the novel.
+
+        Raises:
+            RuntimeError: If novel is not initialized or metadata is invalid.
+        """
+
+    def add_css(self, css: str) -> Self:
+        """Adds custom CSS to the novel.
+
+        Args:
+            css: A string containing the CSS content to be added.
+
+        Raises:
+            RuntimeError: If novel is not initialized or CSS addition fails.
+        """
+
+    def add_resource(self, path: str | Path, source: str | Path) -> Self:
+        """Add a resource to the EPUB.
+
+        Args:
+            path: Internal EPUB path (e.g. 'images/cover.jpg').
+            source: Filesystem path to read from.
+
+        Returns:
+            Self for chaining.
+        """
+
+    def add_font(self, font_family: str, source: str | Path) -> Self:
+        """Embed a font and add @font-face CSS rule.
+
+        Font saved as 'fonts/{font_family}.ttf'.
+
+        Args:
+            font_family: Name used in CSS and filename.
+            source: TTF font file on disk.
+
+        Returns:
+            Self for chaining.
+        """
+
+    def add_inline_toc(self) -> Self:
+        """Enables inline table of contents generation.
+
+        Raises:
+            RuntimeError: If novel is not initialized.
+        """
+
+    def export(self, path: str | Path) -> Self:
+        """Exports the built novel to the specified file path.
+
+        Raises:
+            RuntimeError: If novel not initialized, generation fails, or file write fails.
+        """
+
+def text_to_xhtml_paragraphs(source: str) -> str:
+    """Converts plain text to XHTML paragraphs.
+
+    Args:
+        source: Plain text to convert.
+
+    Returns:
+        XHTML string with paragraphs.
+    """

fabricatio_novel/workflows/__init__.py

@@ -0,0 +1 @@
+"""Workflows defined in fabricatio-novel."""

fabricatio_novel/workflows/novel.py

@@ -0,0 +1,135 @@
+"""This module defines various workflows for novel generation, from full pipelines to granular steps.
+
+Each workflow is designed for specific use cases: full generation, debugging, component regeneration, validation, etc.
+"""
+
+from fabricatio_core.utils import cfg
+
+cfg("fabricatio_actions", feats=["workflows"])
+from pathlib import Path
+
+from fabricatio_actions.actions.output import PersistentAll
+from fabricatio_core import WorkFlow
+
+from fabricatio_novel.actions.novel import (
+    AssembleNovelFromComponents,
+    DumpNovel,
+    GenerateChaptersFromScripts,
+    GenerateCharactersFromDraft,
+    GenerateNovel,  # One-step full pipeline
+    GenerateNovelDraft,
+    GenerateScriptsFromDraftAndCharacters,
+    ValidateNovel,
+)
+
+# ==============================
+# 🚀 One-Step Full Novel Generation (Existing, standardized)
+# ==============================
+WriteNovelWorkflow = WorkFlow(
+    name="WriteNovelWorkflow",
+    description="Generate and dump a novel from outline in one go.",
+    steps=(GenerateNovel, DumpNovel().to_task_output(), PersistentAll),
+)
+"""Generate a novel from outline and dump it to file."""
+
+# ==============================
+# 🧩 Step-by-Step Debug Workflow (Recommended for development)
+# ==============================
+DebugNovelWorkflow = WorkFlow(
+    name="DebugNovelWorkflow",
+    description="Step-by-step novel generation for inspection and debugging.",
+    steps=(
+        GenerateNovelDraft,
+        PersistentAll,
+        GenerateCharactersFromDraft,
+        PersistentAll,
+        GenerateScriptsFromDraftAndCharacters,
+        PersistentAll,
+        GenerateChaptersFromScripts,
+        PersistentAll,
+        AssembleNovelFromComponents,
+        DumpNovel().to_task_output(),
+        PersistentAll,
+    ),
+)
+"""Use this workflow to debug each stage of novel generation."""
+
+
+# ==============================
+# 🎭 Generate Characters Only (For character design phase)
+# ==============================
+GenerateOnlyCharactersWorkflow = WorkFlow(
+    name="GenerateOnlyCharactersWorkflow",
+    description="Generate character cards from a given novel draft.",
+    steps=(
+        GenerateNovelDraft,
+        GenerateCharactersFromDraft,
+        PersistentAll,
+    ),
+)
+"""Useful for iterating on character design before full generation."""
+
+
+# ==============================
+# 📖 Rewrite Chapters Only (Reuse scripts + characters → regenerate prose)
+# ==============================
+RewriteChaptersOnlyWorkflow = WorkFlow(
+    name="RewriteChaptersOnlyWorkflow",
+    description="Regenerate chapter contents from existing scripts and characters.",
+    steps=(
+        GenerateChaptersFromScripts,  # expects draft, scripts, characters in context
+        AssembleNovelFromComponents,
+        DumpNovel().to_task_output(),
+        PersistentAll,
+    ),
+)
+"""Use when you want to rewrite chapter prose without changing plot or characters."""
+
+
+# ==============================
+# ✅ Validated Full Pipeline (Production-grade with quality checks)
+# ==============================
+ValidatedNovelWorkflow = WorkFlow(
+    name="ValidatedNovelWorkflow",
+    description="Generate novel with post-generation validation for quality control.",
+    steps=(
+        GenerateNovel,
+        ValidateNovel,  # Halts or warns if validation fails (depends on engine)
+        DumpNovel().to_task_output(),
+        PersistentAll,
+    ),
+)
+"""Ideal for production: ensures minimum chapters, word count, and compliance ratio."""
+
+
+# ==============================
+# 🔄 Regenerate with New Characters (A/B test character impact)
+# ==============================
+RegenerateWithNewCharactersWorkflow = WorkFlow(
+    name="RegenerateWithNewCharactersWorkflow",
+    description="Reuse existing draft but regenerate story with new characters.",
+    steps=(
+        GenerateNovelDraft,  # Or inject pre-existing draft via context
+        GenerateCharactersFromDraft,  # May yield different characters
+        GenerateScriptsFromDraftAndCharacters,
+        GenerateChaptersFromScripts,
+        AssembleNovelFromComponents,
+        DumpNovel(output_path=Path("output_with_new_characters.epub")).to_task_output(),
+        PersistentAll,
+    ),
+)
+"""Use to explore how different character sets affect narrative outcomes."""
+
+
+# ==============================
+# 💾 Dump Only Workflow (For pre-generated Novel objects)
+# ==============================
+DumpOnlyWorkflow = WorkFlow(
+    name="DumpOnlyWorkflow",
+    description="Only dump an existing Novel object to file (no generation).",
+    steps=(
+        DumpNovel,
+        PersistentAll,
+    ),
+)
+"""Use when Novel is pre-generated or loaded from DB/cache."""

fabricatio_novel-0.1.1.dist-info/METADATA

@@ -0,0 +1,88 @@
+Metadata-Version: 2.4
+Name: fabricatio-novel
+Version: 0.1.1
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: Implementation :: CPython
+Classifier: Typing :: Typed
+Requires-Dist: fabricatio-character
+Requires-Dist: fabricatio-core
+Requires-Dist: pydantic>=2.11.9
+Requires-Dist: fabricatio-novel[workflows,cli] ; extra == 'full'
+Requires-Dist: fabricatio-actions ; extra == 'workflows'
+Requires-Dist: fabricatio-novel[workflows] ; extra == 'cli'
+Requires-Dist: questionary>=2.1.0 ; extra == 'cli'
+Requires-Dist: typer-slim[standard]>=0.15.2 ; extra == 'cli'
+Provides-Extra: full
+Provides-Extra: workflows
+Provides-Extra: cli
+Summary: An extension of fabricatio
+Author-email: Whth <zettainspector@foxmail.com>
+License-Expression: MIT
+Requires-Python: >=3.12, <3.14
+Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
+Project-URL: Homepage, https://github.com/Whth/fabricatio
+Project-URL: Repository, https://github.com/Whth/fabricatio
+Project-URL: Issues, https://github.com/Whth/fabricatio/issues
+
+# `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)
+
+
+
+An extension of fabricatio.
+
+---
+
+## 📦 Installation
+
+
+This package is part of the `fabricatio` monorepo and can be installed as an optional dependency:
+
+```bash
+pip install fabricatio[novel]
+
+# or with uv
+# uv pip install fabricatio[novel]
+```
+
+Or install `fabricatio-diff` along with all other components of `fabricatio`:
+
+```bash
+pip install fabricatio[full]
+
+# or with uv
+# uv pip install fabricatio[full]
+```
+
+## 🔍 Overview
+
+Provides essential tools for:
+
+...
+
+
+
+## 🧩 Key Features
+
+...
+
+
+## 🔗 Dependencies
+
+Core dependencies:
+
+- `fabricatio-core` - Core interfaces and utilities
+...
+
+## 📄 License
+
+This project is licensed under the MIT License.

fabricatio_novel-0.1.1.dist-info/RECORD

@@ -0,0 +1,19 @@
+fabricatio_novel-0.1.1.dist-info/METADATA,sha256=NPEHr0pTAgav75aj_sgcjdQzruZvedzs6RH8mUtHfDc,2560
+fabricatio_novel-0.1.1.dist-info/WHEEL,sha256=dMy2teuP-PSJJ9D8IjLXBMRWYNMh-F_X_I-9plY-tIo,108
+fabricatio_novel-0.1.1.dist-info/entry_points.txt,sha256=Yv1aMQSZeRVHkj1KGkwUrYmNBdIt0F0a_rCdW0KxUco,49
+fabricatio_novel/__init__.py,sha256=2gnAk79LxfdFJxrioPkl-DyZJ4mm9CnYVZNz7o7iz4g,34
+fabricatio_novel/actions/__init__.py,sha256=HBG2V0J0RgYrqWygcA5VV39y33JwRHyeYMTxnrNJkZs,43
+fabricatio_novel/actions/novel.py,sha256=Jnrz9D2CYrLkSAVXiNfW7C8hKSdMOnI7GT3Poj-5BEY,11191
+fabricatio_novel/capabilities/__init__.py,sha256=fDDWl7Sskw3A3344Utctn6rb7513caADquP2nv2CQ3c,48
+fabricatio_novel/capabilities/novel.py,sha256=3Y6dCbSBNMoDP1cwvU0l50IMqDMlskWsI_Mhq_7p0P8,10148
+fabricatio_novel/cli.py,sha256=AbFeavbJ9HMYzMq8sLUCwzvifW8vvpkyI3xMCUsHy0w,5104
+fabricatio_novel/config.py,sha256=tquQs21El4YrEx5Hmxdzx5aMAV8ruKvTXBnHQ0n1M_s,1005
+fabricatio_novel/models/__init__.py,sha256=spyN6xd8hHPIuFhU_QDAxMDapD4yO5NQjiXqOAeY2fA,42
+fabricatio_novel/models/novel.py,sha256=AppZ9_4woxh5-fzvh7EyPcNDAAxfPUmhDVXCMwmDhYc,4128
+fabricatio_novel/models/scripting.py,sha256=uuCG8ge0kHksimz3kO5nyQnrKfrzXoFk-qRmJRSG9CE,2453
+fabricatio_novel/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+fabricatio_novel/rust.cpython-313-x86_64-linux-gnu.so,sha256=22a-xgiJCAIQmQS-exM-QxOp_rN_M_w7Bu8pVpkj-0c,7162360
+fabricatio_novel/rust.pyi,sha256=bPhZMS5Zdkvh1o2ghaI2RiUWqEWZ3iXVxNjzHfgjUkc,3389
+fabricatio_novel/workflows/__init__.py,sha256=NGOA4UgpPkUjKtXrzh4JDhRb6P7VqpCUqzxh-eduj9Y,45
+fabricatio_novel/workflows/novel.py,sha256=rKuuqnMptq9F4nbOOZJZU_O1GxI4UlJJvliFcEoDji0,4632
+fabricatio_novel-0.1.1.dist-info/RECORD,,

fabricatio_novel-0.1.1.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: maturin (1.9.4)
+Root-Is-Purelib: false
+Tag: cp313-cp313-manylinux_2_34_x86_64

fabricatio_novel-0.1.1.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+fanvl=fabricatio_novel.cli:app