Metadata-Version: 2.4
Name: scrivai
Version: 0.2.2
Summary: Configurable document generation & audit framework built on Claude Agent SDK
Author-email: chengzhang yu <iomgaaycz@gmail.com>
License: Apache-2.0
Project-URL: Homepage, https://github.com/iomgaa-ycz/Scrivai
Project-URL: Documentation, https://iomgaa-ycz.github.io/Scrivai/
Project-URL: Repository, https://github.com/iomgaa-ycz/Scrivai
Project-URL: Issues, https://github.com/iomgaa-ycz/Scrivai/issues
Project-URL: Changelog, https://github.com/iomgaa-ycz/Scrivai/blob/main/CHANGELOG.md
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pydantic>=2.6
Requires-Dist: pyyaml>=6.0
Requires-Dist: python-dotenv>=1.0
Requires-Dist: qmd>=0.1.2
Requires-Dist: pluggy>=1.4
Requires-Dist: requests>=2.28
Requires-Dist: docxtpl>=0.16
Requires-Dist: claude-agent-sdk>=0.1.61
Requires-Dist: jinja2>=3.1
Requires-Dist: pypdf>=4.0
Requires-Dist: markitdown[docx]>=0.1.5
Provides-Extra: dev
Requires-Dist: ruff>=0.4; extra == "dev"
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: pytest-cov>=5.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
Requires-Dist: mypy>=1.10; extra == "dev"
Requires-Dist: types-PyYAML>=6.0; extra == "dev"
Provides-Extra: docs
Requires-Dist: mkdocs-material>=9.5; extra == "docs"
Requires-Dist: mkdocstrings[python]>=0.24; extra == "docs"
Provides-Extra: mineru
Requires-Dist: mineru[all]; extra == "mineru"
Dynamic: license-file

# Scrivai

[中文](README.zh-CN.md)

[![PyPI version](https://img.shields.io/pypi/v/scrivai.svg)](https://pypi.org/project/scrivai/)
[![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)
[![License](https://img.shields.io/badge/license-Apache%202.0-green.svg)](LICENSE)

Configurable document generation & audit framework built on Claude Agent SDK.

Scrivai wraps the Claude Agent SDK in a three-phase execution engine called **PES** (Plan→Execute→Summarize), where each phase produces file-contract outputs that the framework validates automatically. It ships three built-in agents — `ExtractorPES`, `AuditorPES`, and `GeneratorPES` — and includes a self-improving skill system that proposes, evaluates, and promotes better agent behaviors from trajectory feedback.

## Install

```bash
pip install scrivai
```

## Quick Start

```python
import asyncio
from pathlib import Path
from pydantic import BaseModel
from scrivai import (
    ExtractorPES,
    ModelConfig,
    WorkspaceSpec,
    build_workspace_manager,
    load_pes_config,
)


class KeyItems(BaseModel):
    items: list[str]


async def main():
    ws_mgr = build_workspace_manager()
    ws = ws_mgr.create(WorkspaceSpec(run_id="demo", project_root=Path.cwd(), force=True))
    config = load_pes_config(Path("scrivai/agents/extractor.yaml"))

    pes = ExtractorPES(
        config=config,
        model=ModelConfig(model="claude-sonnet-4-20250514"),
        workspace=ws,
        runtime_context={"output_schema": KeyItems},
    )
    run = await pes.run("Extract all key items from data/source.md")
    print(run.final_output)


asyncio.run(main())
```

## Core Concepts

Every agent in Scrivai follows the same three-phase contract:

```
┌──────┐      ┌─────────┐      ┌───────────┐
│ plan │ ───▶ │ execute │ ───▶ │ summarize │
└──────┘      └─────────┘      └───────────┘
    │               │                │
    ▼               ▼                ▼
plan.json    findings/*.json    output.json
```

Each phase declares `required_outputs` in a YAML config. The framework checks those file contracts at phase exit and automatically retries up to `max_retries` times on failure. This makes every PES unit testable and auditable without extra instrumentation.

## Key APIs

| Symbol | Description |
|--------|-------------|
| `BasePES` | Three-phase execution engine base class |
| `ExtractorPES` | Extract structured data from documents |
| `AuditorPES` | Audit documents against checkpoints |
| `GeneratorPES` | Generate documents from templates |
| `ModelConfig` | LLM provider configuration |
| `load_pes_config()` | Load PES config from YAML |
| `build_workspace_manager()` | Create isolated workspaces |

## Examples

| Script | Covers | Estimated time |
|--------|--------|----------------|
| `examples/01_audit_single_doc.py` | `AuditorPES` checkpoint audit | ~2–3 min |
| `examples/02_generate_with_revision.py` | `GeneratorPES` template generation | ~1–2 min |
| `examples/03_evolve_skill_workflow.py` | Skill evolution end-to-end | ~3–5 min |

## Documentation

Full API reference and guides: **https://iomgaa-ycz.github.io/Scrivai/**

## Configuration

**Required**

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

**Gateway override** (optional — for private endpoints or alternative models)

```bash
export ANTHROPIC_BASE_URL=https://your-gateway.example.com
export SCRIVAI_DEFAULT_MODEL=your-model-name
```

These environment variables are read automatically at startup. You can also pass `base_url`, `model`, and `api_key` directly to `ModelConfig` to override them at the code level.

## Contributing

See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup, coding standards, and the pull-request workflow.

## License

Apache 2.0 — see [LICENSE](LICENSE) for details.
