Metadata-Version: 2.4
Name: novelscribe
Version: 0.2.23
Summary: AI-powered autonomous novel generation system — install with 'pip install novelscribe', run with 'scribe'
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
Requires-Dist: openai>=1.0.0
Requires-Dist: anthropic>=0.18.0
Requires-Dist: google-generativeai>=0.3.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: gitpython>=3.1.40
Requires-Dist: click>=8.1.0
Requires-Dist: pydantic>=2.0.0
Requires-Dist: python-dotenv>=1.0.0
Requires-Dist: toml>=0.10.2
Requires-Dist: requests>=2.31.0
Requires-Dist: packaging>=23.0
Requires-Dist: inquirer3>=0.3.0
Requires-Dist: rich>=13.0.0
Provides-Extra: dev
Requires-Dist: pytest>=8.0.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.23.0; extra == "dev"
Requires-Dist: pytest-cov>=5.0.0; extra == "dev"
Requires-Dist: pytest-xdist>=3.5.0; extra == "dev"
Requires-Dist: pytest-cache; extra == "dev"
Requires-Dist: black>=23.0.0; extra == "dev"
Requires-Dist: ruff>=0.1.0; extra == "dev"
Requires-Dist: mypy>=1.5.0; extra == "dev"
Requires-Dist: pre-commit>=3.0.0; extra == "dev"
Provides-Extra: api
Requires-Dist: fastapi>=0.104.0; extra == "api"
Requires-Dist: uvicorn[standard]>=0.24.0; extra == "api"
Requires-Dist: websockets>=12.0; extra == "api"

# 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.

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

---

## Install

```bash
pipx install novelscribe
```

That's it. The `scribe` command is now available.

> **Why pipx?** On macOS and many Linux distros, `pip install` is blocked by the system Python (`externally-managed-environment` error). `pipx` installs into an isolated virtualenv, avoiding this entirely. Install pipx first if you don't have it: `brew install pipx && pipx ensurepath` (macOS) or `sudo apt install pipx && pipx ensurepath` (Linux).

<details>
<summary>Other install methods</summary>

```bash
pip install --user novelscribe    # user-level (may warn on macOS)
```

Or the one-liner script (auto-detects pipx/pip):

```bash
curl -sSL https://raw.githubusercontent.com/huangjien/wst/main/novel_harness/install.sh | bash
```

</details>

## 30-Second Demo

```bash
# Create a new novel project
scribe new my-novel

# Run fully autonomous generation (outline → characters → world → chapters)
scribe autonomous start my-novel

# Check progress
scribe --help
```

## What It Does

NovelScribe chains 9 specialized AI agents 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.

### Key Features

- **Autonomous generation** — one command produces a complete novel
- **9 specialized agents** — writer, editor, character designer, world-builder, continuity checker, etc.
- **Verification loops** — auto-detects and fixes plot holes, inconsistencies, and quality issues
- **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 on all 5 providers
- **Circuit breakers** — automatic failover between LLM providers on persistent failures
- **Schema versioning** — forward-compatible agent/workflow definitions with migration support
- **Run logging** — structured JSONL logs with `scribe logs run <project>` command
- **Scales to 3M words** — hierarchical summaries, memory optimization, chapter pagination, phase-level caching
- **Multi-language** — English, 简体中文, 繁體中文 (with fallback)
- **5 LLM providers** — OpenAI, Claude, Gemini, Ollama, LM Studio

## Usage

### Create a Novel

```bash
scribe new my-novel --provider openai --model gpt-4
```

### Run Autonomous Generation

```bash
scribe autonomous start my-novel
```

### Run Individual Phases

```bash
# Generate the outline
scribe run workflow outline --project my-novel

# Run a single agent
scribe run agent writer_agent --project my-novel

# Preview without executing
scribe run workflow writing --project my-novel --dry-run
```

### Explore Agents & Workflows

```bash
scribe agents list
scribe agents show writer_agent

scribe workflows list
scribe workflows show outline
```

### Templates

```bash
scribe templates list
scribe templates show heros_journey --category plot
scribe template-create plot -n "My Structure" -d "Description" -b "0:Hook:Description"
```

### Version & Updates

```bash
scribe version info              # current version
scribe version check             # check PyPI for updates
scribe version update            # self-update to latest
scribe version update --yes      # skip confirmation
```

### Run Logs

```bash
scribe logs run <project>        # view structured run logs
```

NovelScribe checks for updates on startup (once per 24h) and shows a notification when a new version is available.

## Multi-Language Support

| Language | Code |
|----------|------|
| English | `en` |
| Simplified Chinese | `zh-CN` |
| Traditional Chinese | `zh-TW` |

Set per-project in `META.yaml`:

```yaml
project_name: my_novel
language: zh-CN
genre: fantasy
target_word_count: 80000
```

Or per-command:

```bash
scribe --lang zh-TW agents list
```

Language resolution priority: `--lang` flag > `META.yaml` > user config > `SCRIBE_LANGUAGE` env > system locale > English fallback.

## Configuration

Set your LLM provider:

```bash
# Interactive setup
scribe config setup

# Or set directly
export OPENAI_API_KEY=sk-...
export ANTHROPIC_API_KEY=sk-ant-...
```

Supported providers:

| Provider | Env Var | Notes |
|----------|---------|-------|
| OpenAI | `OPENAI_API_KEY` | Best quality |
| Anthropic | `ANTHROPIC_API_KEY` | Long context |
| Google Gemini | `GOOGLE_API_KEY` | Free tier available |
| Ollama | — | Local, no API key needed |
| LM Studio | — | Local, no API key needed |

## Architecture

```
novel_harness/
├── cli.py                 # Entry point (registered as 'scribe')
├── cli_*.py               # Command modules (agents, workflows, run, autonomous, logs, etc.)
├── core/                  # Core engine
│   ├── orchestrator.py    # Central coordinator
│   ├── llm_client.py      # Multi-provider LLM abstraction (with streaming)
│   ├── circuit_breaker.py # Per-provider circuit breakers with auto-fallback
│   ├── optimizing_llm_client.py # LLM call wrapper with cache + cost tracking
│   ├── model_registry.py  # Per-model token limit registry
│   ├── schema_versions.py # Schema versioning for agent/workflow definitions
│   ├── run_logger.py      # Structured JSONL run logging
│   ├── phase_context_cache.py # Per-phase artifact pre-loading
│   ├── storage.py         # File-based storage
│   ├── version.py         # Update checker & self-updater
│   ├── performance_profiler.py        # Profiling facade
│   ├── performance_profiler_core.py   # Profiling implementation
│   ├── performance_profiler_types.py  # Profiling data types
│   └── ...
├── agents/                # Agent definitions (Markdown, schema_version: 1)
├── workflows/             # Workflow definitions (YAML, schema_version: 1)
├── api/                   # FastAPI server with WebSocket streaming (optional)
└── tests/                 # Test suite (5187 tests, 96% coverage)
```

## LLM Providers

NovelScribe supports any OpenAI-compatible API. Configure via environment variables or `scribe config setup`:

```bash
# .env file
OPENAI_API_KEY=sk-...
LLM_PROVIDER=openai
LLM_MODEL=gpt-4-turbo-preview
```

## API Server (Optional)

For web UI integration or programmatic access:

```bash
pip install "novelscribe[api]"
uvicorn api.app:app --host 0.0.0.0 --port 8000
```

## Development

```bash
git clone https://github.com/huangjien/wst.git
cd novelscribe/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](LICENSE)
