Metadata-Version: 2.4
Name: novelscribe
Version: 0.2.0
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/novelscribe
Project-URL: Documentation, https://github.com/huangjien/novelscribe#readme
Project-URL: Repository, https://github.com/huangjien/novelscribe
Project-URL: Issues, https://github.com/huangjien/novelscribe/issues
Project-URL: Changelog, https://github.com/huangjien/novelscribe/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"

# Novel Writing Harness

[![CI](https://github.com/huangjien/wst/actions/workflows/ci.yml/badge.svg)](https://github.com/huangjien/wst/actions/workflows/ci.yml)
[![PyPI version](https://badge.fury.io/py/novel-harness.svg)](https://pypi.org/project/novel-harness/)
[![Python versions](https://img.shields.io/badge/python-3.10%20|%203.11%20|%203.12%20|%203.13%20|%203.14-blue.svg)](https://pypi.org/project/novel-harness/)
[![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)

An AI-powered autonomous novel generation system with multi-agent architecture.

> **Language / 语言 / 語言:** [English](README.md) | [简体中文](docs/getting-started/README.zh-CN.md) | [繁體中文](docs/getting-started/README.zh-TW.md)

## Quick Start

### Installation

```bash
cd wst/novel_harness
uv sync --all-extras
```

## Usage

### Method 1: Use the Wrapper Script (Recommended)

The project includes a `scribe` wrapper script that automatically uses the correct Python environment:

```bash
# From the project directory
./scribe --help

# Add to PATH for easy access
export PATH="/path/to/wst/novel_harness:$PATH"

# Then use from anywhere
scribe --help
scribe new my-novel
```

### Method 2: Using uv run

```bash
cd wst/novel_harness
uv run python cli.py --help
```

## Quick Examples

```bash
# Show help
./scribe --help

# Check version
./scribe version info

# Check for updates
./scribe version check

# Initialize a new novel
./scribe new my-novel --provider openai --model gpt-4

# Run autonomous generation
./scribe autonomous start my-novel

# Explore available agents
./scribe agents list
./scribe agents show writer_agent

# Explore available workflows
./scribe workflows list
./scribe workflows show outline

# Run agents/workflows
./scribe run agent writer_agent --project my-novel
./scribe run workflow outline --project my-novel
```

## CLI Commands

### Agent Commands

Explore and manage AI agents:

```bash
# List all available agents
scribe agents list

# Show detailed information about an agent
scribe agents show writer_agent

# Agents are grouped by category:
# - Analytical: Analysis, planning, and validation agents
# - Creative: Content generation and creative writing agents
# - Validation: Quality checking and verification agents
```

### Template Commands

Explore and manage story templates:

```bash
# List all available templates
scribe templates list

# Show template details
scribe templates show heros_journey --category plot

# Format template for prompts (optionally at position %)
scribe templates format heros_journey --position 50

# Export all templates
scribe templates export -o templates.json

# Show template system info
scribe templates info

# Show supported languages
scribe templates languages

# Create new templates
scribe template-create plot -n "My Structure" -d "Description" -b "0:Hook:Description"
scribe template-create character -n "My Archetype" -d "Description" -e "Want:Description"
scribe template-create scene -n "My Scene" -d "Description" -e "Element:Description"

# Clone and modify existing templates
scribe template-create clone heros_journey my_journey -c plot

# Validate template YAML
scribe template-create validate templates/en/plot/my_template.yaml

# Translate template to another language
scribe template-create translate heros_journey -c plot --source-language en --target-language zh-CN

# Show template creation help
scribe template-create help
```

### Workflow Commands

Explore and manage workflows:

```bash
# List all available workflows
scribe workflows list

# Show detailed information about a workflow
scribe workflows show new_novel

# Workflows are multi-step processes that combine agents
# Examples: new_novel, outline, writing, editing
```

### Run Commands

Execute agents and workflows:

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

# Run a workflow
scribe run workflow outline --project my-novel

# With verbose output
scribe -vv run agent character_agent --project my-novel

# Dry run (preview what would happen)
scribe run workflow writing --project my-novel --dry-run
```

## Multi-Language Support

The Novel Writing Harness supports multiple languages for agents, workflows, and system messages.

### Supported Languages

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

### Setting Your Language

#### Per-Project (Recommended)

Set the language in your project's `META.yaml`:

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

All commands will automatically use this language:

```bash
scribe agents list              # Uses zh-CN from META.yaml
scribe workflows show outline   # Uses zh-CN from META.yaml
scribe run workflow autonomous  # Uses zh-CN from META.yaml
```

#### User Default

Set your personal default language:

```bash
scribe config set language zh-CN
```

This applies to all new projects.

#### Override with CLI Option

Temporarily override the project or user setting:

```bash
# View agents in Traditional Chinese
scribe --lang zh-TW agents list

# Run workflow in English
scribe --lang en run workflow outline --project my-novel
```

#### Environment Variable

Set via environment variable (useful for CI/CD):

```bash
export SCRIBE_LANGUAGE=zh-CN
scribe agents list  # Uses zh-CN
```

### Language Resolution Priority

The system resolves language using this priority chain (highest to lowest):

1. **CLI option** `--lang` (highest priority)
2. **Project configuration** `META.yaml` field `language`
3. **User configuration** `~/.scribe/config.yaml`
4. **Environment variable** `SCRIBE_LANGUAGE`
5. **System locale** (auto-detected)
6. **English** `en` (fallback, always available)

### Examples

```bash
# Set default language to Simplified Chinese
scribe config set language zh-CN

# Create a new novel project
cd my-novel
echo "language: zh-TW" >> META.yaml

# List agents - shows Traditional Chinese
scribe agents list

# Temporarily view in English
scribe --lang en agents list

# Run workflow - uses Traditional Chinese from META.yaml
scribe run workflow outline

# Per-command override
scribe --lang zh-CN run agent writer_agent --project my-novel
```

### Fallback Behavior

If a language version is missing, the system automatically falls back to English:

```
Request: zh-CN → Check agents/zh-CN/ → Empty → Fallback to agents/en/
Request: zh-TW → Check workflows/zh-TW/ → Missing → Fallback to workflows/en/
```

This ensures all commands work even when translations are incomplete.

### Viewing Current Language

All commands display the current language in their output:

```bash
$ scribe agents list
Available Agents (12) [Language: zh-CN]:
...
```

### Adding New Languages

The system is designed to easily support additional languages. To add a new language:

1. Create language subdirectories:
   ```bash
   mkdir -p agents/{new-lang}
   mkdir -p workflows/{new-lang}
   ```

2. Add translated agent/workflow files

3. Update `LanguageCode` enum in `core/language_config.py`

4. Update CLI `--lang` option choices

For detailed translation guidelines, see [TRANSLATION_GUIDE.md](TRANSLATION_GUIDE.md) (to be created).

## IDE & Chatbot Integration

The Novel Harness now supports seamless integration with VS Code Copilot, Trae, and other AI chatbots through a dedicated skill.

### Quick Start with Chatbot

1. **Install the Skill**
   ```bash
   # The skill is packaged at: novel_harness_skill.skill
   # Copy to your skills directory
   cp novel_harness_skill.skill ~/.trae/skills/
   ```

2. **Use from Your Chatbot**
   
   Simply ask your chatbot to work with novels:
   
   - *"Create a new science fiction novel called 'The Last Algorithm'"*
   - *"Start autonomous generation for my_novel project"*
   - *"Check the status of the generation"*
   - *"Review chapter 5 of my_novel"*
   - *"Generate a progress report for my_novel"*

### Available Chatbot Commands

**Project Management:**
- Create/list/delete novel projects
- Set genre, word count, language
- View project status and details

**Content Generation:**
- Run autonomous generation (end-to-end)
- Generate individual chapters
- Execute specific workflows (outline, writing, editing)
- Run individual agents

**Review & Edit:**
- View generated chapters
- Access hierarchical summaries
- Edit content directly
- Run quality checks

**Monitoring:**
- Real-time progress tracking
- View execution logs
- Stream status updates
- Generate progress reports

### Integration Modes

**API Server Mode (Recommended):**
```python
# Automatically starts FastAPI server on localhost:8000
# RESTful API with full feature support
```

**CLI Fallback Mode:**
```python
# Direct CLI commands when API unavailable
# Automatic fallback for maximum reliability
```

### Documentation

See [docs/](docs/README.md) for full documentation:

**Getting Started:**
- [Quick Start Guide](docs/getting-started/QUICK_START.md)
- [Installation Guide](docs/getting-started/INSTALLATION_GUIDE.md)
- [User Guide](docs/getting-started/USER_GUIDE.md)

**Guides:**
- [Template Creation Guide](docs/guides/TEMPLATE_CREATION.md)
- [Translation Guide](docs/guides/TRANSLATION_GUIDE.md)
- [Skill Usage Guide](docs/guides/SKILL_USAGE.md)

**Development:**
- [CI/CD Guide](docs/development/CI_CD.md)
- [Deployment Guide](docs/development/DEPLOY.md)

**Reference:**
- [UV Guide](docs/reference/UV_GUIDE.md)
- [PyPI Setup](docs/reference/PYPI_SETUP.md)

## CI/CD

This project uses GitHub Actions for automated testing, linting, and deployment.

### Workflows

- **CI**: Runs tests, linting, and type checking on every push/PR
- **CD**: Builds and publishes package to PyPI on release
- **Pre-commit**: Runs quality checks on all branches

### Status Badges

Add status badges to your README:

```markdown
[![CI](https://github.com/huangjien/wst/actions/workflows/ci.yml/badge.svg)](https://github.com/huangjien/wst/actions/workflows/ci.yml)
[![PyPI version](https://badge.fury.io/py/novel-harness.svg)](https://pypi.org/project/novel-harness/)
```

### Local Development

```bash
# Install pre-commit hooks
pre-commit install

# Run all checks locally
make check

# Or individually
make format      # Format code
make lint       # Lint code
make type-check # Type check
make test       # Run tests
```

See [CI_CD.md](CI_CD.md) for detailed setup instructions.
