Metadata-Version: 2.4
Name: novelscribe
Version: 8.4.13
Summary: Programmatic AI novel-generation library for the NovelScribe Pipeline
Author-email: NovelScribe Team <huangjien@gmail.com>
License-Expression: MIT
Project-URL: Homepage, https://github.com/huangjien/wst
Project-URL: Documentation, https://github.com/huangjien/wst#readme
Project-URL: Repository, https://github.com/huangjien/wst
Project-URL: Issues, https://github.com/huangjien/wst/issues
Project-URL: Changelog, https://github.com/huangjien/wst/releases
Keywords: novel,writing,ai,llm,gpt,autonomous,agents,fiction,creative,scribe
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: End Users/Desktop
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Text Processing :: General
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: <3.15,>=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: openai>=2.52.0
Requires-Dist: anthropic>=0.120.2
Requires-Dist: google-generativeai>=0.8.6
Requires-Dist: pyyaml>=6.0.3
Requires-Dist: gitpython>=3.1.57
Requires-Dist: click>=8.4.2
Requires-Dist: pydantic>=2.13.4
Requires-Dist: python-dotenv>=1.2.2
Requires-Dist: toml>=0.10.2
Requires-Dist: requests>=2.34.2
Requires-Dist: packaging>=26.2
Requires-Dist: inquirer3>=0.6.1
Requires-Dist: rich>=15.0.0
Requires-Dist: fpdf2>=2.8.7
Requires-Dist: python-docx>=1.2.0
Requires-Dist: mistletoe>=1.6.0
Requires-Dist: google-genai>=2.16.0
Requires-Dist: fastapi>=0.141.1
Requires-Dist: uvicorn[standard]>=0.52.1
Requires-Dist: websockets>=16.1.1
Provides-Extra: dev
Requires-Dist: pytest>=9.1.1; extra == "dev"
Requires-Dist: pytest-asyncio>=1.4.0; extra == "dev"
Requires-Dist: pytest-cov>=7.1.0; extra == "dev"
Requires-Dist: pytest-xdist>=3.8.0; extra == "dev"
Requires-Dist: pytest-cache>=1.0; extra == "dev"
Requires-Dist: black>=26.5.1; extra == "dev"
Requires-Dist: ruff>=0.16.1; extra == "dev"
Requires-Dist: mypy>=2.3.0; extra == "dev"
Requires-Dist: pre-commit>=4.6.1; extra == "dev"
Requires-Dist: types-PyYAML>=6.0.12.20260724; extra == "dev"
Provides-Extra: sync
Requires-Dist: sqlalchemy>=2.0.36; extra == "sync"
Requires-Dist: pyjwt>=2.10.1; extra == "sync"
Requires-Dist: bcrypt>=4.2.1; extra == "sync"
Requires-Dist: httpx>=0.28.1; extra == "sync"
Requires-Dist: email-validator>=2.2.0; extra == "sync"
Provides-Extra: search
Requires-Dist: sentence-transformers>=5.6.1; extra == "search"
Requires-Dist: onnxruntime<1.24,>=1.23.2; python_version < "3.11" and extra == "search"
Requires-Dist: onnxruntime>=1.24.3; python_version >= "3.11" and extra == "search"
Dynamic: license-file

# NovelScribe

[![CI](https://github.com/huangjien/wst/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/huangjien/wst/actions/workflows/ci.yml)
[![PyPI version](https://img.shields.io/pypi/v/novelscribe.svg)](https://pypi.org/project/novelscribe/)
[![Python versions](https://img.shields.io/pypi/pyversions/novelscribe.svg)](https://pypi.org/project/novelscribe/)
[![License](https://img.shields.io/github/license/huangjien/wst.svg)](../LICENSE)

An AI-powered autonomous novel generation agent. Give it a concept, pick a genre,
and it writes a full novel — outline, characters, world-building, chapters, and
all.

> **v8.0 (Pipeline-to-Frontend Port):** the Python `scribe` CLI and TUI have
> been removed (cutover shipped in Phase 11, code-side removal in Phase 12).
> Novel generation now runs in **NovelScribe Studio** — the Flutter app under
> `frontend/`. The Python pipeline is also available as a library (`pip install
> novelscribe`) for programmatic use; the thin cross-device sync service lives
> in `novel_harness/sync_backend/` (FastAPI, port 8001).

> **Language / 语言 / 語言:** [English](./docs/getting-started/QUICK_START.md) |
> [简体中文](https://github.com/huangjien/wst/blob/main/novel_harness/docs/getting-started/QUICK_START.zh-CN.md) |
> [繁體中文](https://github.com/huangjien/wst/blob/main/novel_harness/docs/getting-started/QUICK_START.zh-TW.md)

---

## What runs where

| Component | Path | Run as |
|---|---|---|
| **NovelScribe Studio** (Flutter app) | `frontend/` | `cd frontend && flutter run -d chrome` |
| **sync_backend** (thin FastAPI sync) | `novel_harness/sync_backend/` | `make start-sync-backend` (port 8001) |
| **Python pipeline** (library) | `novel_harness/agents/`, `workflows/`, `core/` | `pip install novelscribe` |

Install and configuration: [Quick Start](./docs/getting-started/QUICK_START.md).

The Flutter app talks to the pipeline locally via `RuntimeKernel` (BYOK keys
configured in-app). `sync_backend` is the cross-device mirror for projects,
chapters, reading state, and the agent/workflow catalog.

## What NovelScribe does

Nine specialised AI agents chained into an autonomous pipeline:

```
discuss → genre → characters → world-building → outline → chapter-planning → writing → continuity → editing
```

Each agent is a Markdown file with a system prompt and model config. The
orchestrator runs them step-by-step through YAML-defined workflows, with
verification loops that auto-fix issues until quality passes.

### Pipeline capabilities (library-level)

- **9 specialized agents** — writer, editor, character designer, world-builder,
  continuity checker, etc.
- **Verification loops** — auto-detect and fix plot holes, inconsistencies,
  and quality issues
- **Hook lifecycle framework** — YAML-declared hooks with required vs optional
  semantics and strict guardrails
- **Resilience** — step retry/timeout, DAG parallel execution with rollback,
  exponential+jitter backoff, trigger API
- **Quality gates** — Bronze / Silver / Gold / Platinum tiers with metrics and
  benchmarks
- **Parallel execution** — runs independent agents concurrently for 2-4x
  speedup
- **LLM streaming** — real-time token streaming across all providers
- **Circuit breakers** — automatic failover between LLM providers
- **Run logging** — structured JSONL logs per project
- **Knowledge graph** — entity relationships (characters, locations, events)
  with consistency checking
- **Schema versioning** — forward-compatible agent/workflow definitions with
  migration support
- **Scales to 3M words** — hierarchical summaries, memory optimization,
  chapter pagination, phase-level caching
- **Multi-language** — English, 简体中文, 繁體中文 (with fallback)
- **8 LLM providers** — OpenAI, Claude, Gemini, Ollama, LM Studio, MiniMax,
  ZhipuAI (z.ai), Moonshot (Kimi) — all configurable via BYOK in the Studio

## Library use

Install the Python package:

```bash
pipx install novelscribe        # isolated env
# or
pip install --user novelscribe
```

Use the Pipeline programmatically:

```python
from pathlib import Path

from novelscribe import GenerationRequest, Pipeline, PipelineSettings

pipeline = Pipeline(
    PipelineSettings(
        provider="openai",
        model="gpt-5",
        project_root=Path("./novels"),
    )
)

result = pipeline.generate(
    GenerationRequest(
        project_name="the-lighthouse",
        concept="An engineer discovers the lighthouse is sending impossible signals.",
        genre="mystery",
        chapter_count=24,
    )
)

print(result.status)
print(result.project_path)
```

`Pipeline.generate()` creates a new project and never overwrites existing
state. Use `Pipeline.resume(project_name)` to continue an interrupted
project. `Pipeline.run_workflow()` is the secondary escape hatch for one
named Workflow.

Generation is unattended by default. For checkpoint approval, inject an
`ApprovalHandler`; the Library never reads terminal input. A custom
`LLMAdapter` can replace the built-in provider adapters.

Set provider keys via environment (only needed for direct library use; the
Studio manages BYOK itself):

```bash
export OPENAI_API_KEY=sk-...
export ANTHROPIC_API_KEY=sk-ant-...
export GOOGLE_API_KEY=...
```

## sync_backend (cross-device sync)

A thin FastAPI service that mirrors projects, chapters, reading state, and the
agent/workflow catalog for cross-device use.

```bash
make start-sync-backend    # http://0.0.0.0:8001
```

Endpoints live under `/api/v1/...` and are documented in
[`openapi.json`](./openapi.json). The Flutter Studio is the primary client.

## Development

```bash
git clone https://github.com/huangjien/wst.git
cd wst/novel_harness
uv sync --all-extras

# Run quality checks
make check

# Individual
make format      # ruff format
make lint        # ruff check --fix
make type-check  # mypy
make test        # pytest with coverage
make build       # uv build → dist/
```

## License

[MIT](https://github.com/huangjien/wst/blob/main/LICENSE) — the full text ships
with the installed package (`novelscribe-*.dist-info/licenses/LICENSE`).
