novelscribe 0.2.0

AI-powered autonomous novel generation system — install with 'pip install novelscribe', run with 'scribe'

Novel Writing Harness

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

Language / 语言 / 語言: English | 简体中文 | 繁體中文

Quick Start

Installation

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:

# 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

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

Quick Examples

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

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

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

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

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

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

All commands will automatically use this language:

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:

scribe config set language zh-CN

This applies to all new projects.

Override with CLI Option

Temporarily override the project or user setting:

# 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):

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

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

$ 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:

   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 (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

   # 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):

# Automatically starts FastAPI server on localhost:8000
# RESTful API with full feature support

CLI Fallback Mode:

# Direct CLI commands when API unavailable
# Automatic fallback for maximum reliability

Documentation

See docs/ for full documentation:

Getting Started:

• Quick Start Guide
• Installation Guide
• User Guide

Guides:

• Template Creation Guide
• Translation Guide
• Skill Usage Guide

Development:

• CI/CD Guide
• Deployment Guide

Reference:

• UV Guide
• PyPI Setup

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:

[![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

# 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 for detailed setup instructions.