# qiniu **Repository Path**: how-yang/qiniu ## Basic Information - **Project Name**: qiniu - **Description**: No description available - **Primary Language**: Unknown - **License**: MIT - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2026-06-04 - **Last Updated**: 2026-06-07 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # NovelToScript AI **AI-powered novel-to-script conversion tool** — transform 3+ chapters of novel text into structured, editable YAML screenplays. [![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/) [![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE) --- ## What It Does NovelToScript AI reads your novel (3+ chapters) and produces a **structured YAML screenplay** — complete with: - **Character profiles** — identified, deduplicated, with aliases and relationships - **Scene breakdown** — each chapter split into scenes with slug lines - **Formatted dialogue** — attributed, with parentheticals and stage directions - **Action lines** — present-tense visual descriptions - **Adaptation notes** — the AI explains its creative choices - **Uncertainty flags** — honest indicators of what to double-check The output is **editable YAML** — you can refine, restructure, and polish before converting to Final Draft or Fountain for submission. > **Read [`SCHEMA.md`](SCHEMA.md)** for the complete YAML schema reference with design rationale. --- ## Quickstart ### 1. Install ```bash pip install noveltoscript ``` Or from source: ```bash git clone https://github.com/noveltoscript/noveltoscript-ai.git cd noveltoscript-ai pip install -e . ``` ### 2. Set Your API Key ```bash # Anthropic Claude (recommended) export ANTHROPIC_API_KEY="sk-ant-..." # Or OpenAI export OPENAI_API_KEY="sk-..." ``` ### 3. Prepare Your Novel Save your novel as a plain text file (`.txt`) with clear chapter markers: ``` Chapter 1: The Beginning It was a dark and stormy night... Chapter 2: The Journey The morning sun revealed a changed landscape... ``` Supported chapter formats: `Chapter 1`, `CHAPTER I`, `第一章`, `1. Title`, and more. ### 4. Convert ```bash noveltoscript convert my_novel.txt --output script.yaml --title "My Adaptation" --author "Original Author" ``` ### 5. Edit & Polish Open `script.yaml` in any text editor. Review items flagged in `uncertainty_flags` first, then refine dialogue, scene structure, and action lines. --- ## CLI Reference ``` noveltoscript convert INPUT [OPTIONS] ``` | Option | Description | Default | |--------|-------------|---------| | `--output, -o PATH` | Output YAML file path | `./output/script.yaml` | | `--title, -t TEXT` | Script title | Auto-detected from chapter heading | | `--author, -a TEXT` | Original novel author | `Unknown` | | `--source, -s TEXT` | Original novel title | None | | `--provider TEXT` | LLM provider (`anthropic` or `openai`) | `anthropic` | | `--model TEXT` | LLM model name | `claude-sonnet-4-20250514` | | `--temperature FLOAT` | LLM temperature (0.0–1.0) | `0.5` | | `--concurrency INT` | Max parallel processing (1–10) | `3` | | `--dry-run` | Parse only, no LLM calls | — | | `--schema-doc` | Also generate SCHEMA.md | — | | `--verbose, -v` | Verbose logging | — | | `--config, -c PATH` | YAML config file | — | ### Other Commands ```bash noveltoscript schema-doc --output SCHEMA.md # Generate schema documentation noveltoscript info # Show configuration and API key status noveltoscript --version # Show version noveltoscript --help # Show help ``` --- ## Programmatic Usage ```python import asyncio from pathlib import Path from noveltoscript.main import run_conversion async def main(): result = await run_conversion( input_path=Path("my_novel.txt"), output_path=Path("output/script.yaml"), title="My Screenplay", author="Author Name", ) # Access the script programmatically script = result.script for act in script.acts: print(f"Act {act.act_number}: {act.title}") for scene in act.scenes: dialogue_count = sum( 1 for e in scene.content if e.type == "dialogue" ) print(f" Scene {scene.scene_number}: {dialogue_count} lines") asyncio.run(main()) ``` --- ## How It Works NovelToScript AI uses a **6-stage pipeline** with Anthropic Claude (or OpenAI) at key stages: ``` novel.txt → Stage 1: Parse (chapter detection, text cleaning) → Stage 2: Character Extraction (LLM per chapter → cross-chapter merge) → Stage 3: Setting Extraction (LLM per chapter → deduplication) → Stage 4: Scene Breakdown (LLM per chapter → scene boundaries) → Stage 5: Script Generation (LLM per scene → action/dialogue/transitions) → Stage 6: Assembly & Validation (merge, cross-reference, serialize) → script.yaml ``` **Key design features:** - **Multi-stage pipeline**: Each stage has a focused task, yielding higher quality than a single LLM call - **Prompt caching**: Shared context (character profiles, schema) is cached, reducing costs ~90% after the first scene - **Parallel processing**: Chapters are processed concurrently within each stage - **Explicit uncertainty**: The AI flags what it's unsure about rather than guessing silently --- ## Configuration Settings are loaded in this order (highest to lowest priority): 1. CLI arguments 2. Environment variables (`NOVELTOSCRIPT_*` prefix) 3. Config file (YAML) 4. Default values ### Environment Variables ```bash NOVELTOSCRIPT_LLM__PROVIDER=anthropic NOVELTOSCRIPT_LLM__MODEL=claude-sonnet-4-20250514 NOVELTOSCRIPT_LLM__EXTRACTION_MODEL=claude-haiku-4-5-20251001 NOVELTOSCRIPT_CONCURRENCY=3 NOVELTOSCRIPT_VERBOSE=false ``` ### Config File (`noveltoscript.yaml`) ```yaml llm: provider: anthropic model: claude-sonnet-4-20250514 extraction_model: claude-haiku-4-5-20251001 temperature_extraction: 0.3 temperature_generation: 0.5 max_retries: 3 chunking: max_chapter_tokens: 180000 max_scene_tokens: 50000 output: output_dir: ./output generate_processing_report: true concurrency: 3 ``` --- ## Requirements - Python 3.11+ - Anthropic API key (recommended) or OpenAI API key - Novel text file with 3+ chapters and clear chapter markers --- ## Project Structure ``` NovelToScript_AI/ ├── pyproject.toml # Package metadata and dependencies ├── README.md # This file ├── SCHEMA.md # YAML Schema reference with design rationale ├── .env.example # Environment variable template │ ├── src/noveltoscript/ # Main package │ ├── cli.py # Typer CLI definition │ ├── main.py # Top-level conversion entry point │ ├── config/settings.py # Pydantic Settings management │ ├── schema/models.py # Pydantic models (YAML schema source of truth) │ ├── schema/validators.py # Script validation logic │ ├── schema/templates.py # LLM prompt templates │ ├── pipeline/ # 6-stage conversion pipeline │ │ ├── orchestrator.py # Pipeline coordinator │ │ ├── stage_01_parse.py # Chapter detection │ │ ├── stage_02_characters.py # Character extraction │ │ ├── stage_03_settings.py # Setting extraction │ │ ├── stage_04_scenes.py # Scene breakdown │ │ ├── stage_05_script.py # Script generation (core) │ │ └── stage_06_assemble.py # Assembly & validation │ ├── llm/ # LLM abstraction layer │ │ ├── client.py # Anthropic + OpenAI client wrapper │ │ ├── prompts.py # Prompt builders │ │ ├── cache.py # Prompt caching management │ │ └── retry.py # Exponential backoff retry │ ├── parsing/ # Text processing (local, no LLM) │ │ ├── chapter_splitter.py # Chapter boundary detection │ │ ├── text_cleaner.py # Whitespace & encoding normalization │ │ └── chunker.py # Token-aware text chunking │ ├── output/ # Output formatting │ │ ├── yaml_writer.py # ruamel.yaml serialization │ │ └── schema_doc.py # SCHEMA.md auto-generator │ └── utils/ # Shared utilities │ ├── file_io.py # File I/O with encoding detection │ ├── logging.py # Structured logging │ ├── progress.py # Rich progress bars │ └── token_counter.py # Token estimation │ ├── tests/ # Test suite │ ├── conftest.py # Shared fixtures │ └── fixtures/ # Sample novel files │ └── docs/ # User documentation (mkdocs) ``` --- ## License MIT License — see [LICENSE](LICENSE) for details. --- ## Acknowledgments Built with: - [Anthropic Claude](https://www.anthropic.com/) — primary LLM provider - [LiteLLM](https://github.com/BerriAI/litellm) — provider abstraction - [Typer](https://typer.tiangolo.com/) + [Rich](https://rich.readthedocs.io/) — beautiful CLI - [Pydantic](https://docs.pydantic.dev/) — schema validation - [ruamel.yaml](https://yaml.readthedocs.io/) — human-friendly YAML