Metadata-Version: 2.4
Name: stackwright-pro-raft
Version: 1.0.0a13
Summary: Clarification Protocol for Otter Raft orchestration
Requires-Python: >=3.11
Requires-Dist: code-puppy
Requires-Dist: pydantic>=2.0
Requires-Dist: rich>=13.0
Provides-Extra: dev
Requires-Dist: pytest-asyncio>=0.21; extra == 'dev'
Requires-Dist: pytest>=7.0; extra == 'dev'
Requires-Dist: ruff>=0.1; extra == 'dev'
Description-Content-Type: text/markdown

# Stackwright Pro - Otter Raft Python SDK

Python orchestration layer implementing the Clarification Protocol for Pro Otter Raft.

## Hybrid Architecture

The otter raft uses a **Python + code-puppy hybrid** approach:

```
┌─────────────────────────────────────────────────────────────┐
│                   CLI Adapter (Python)                       │
│                                                              │
│   --spawn (default)  →  Spawns code-puppy with foreman prompt │
│   --phases           →  Executes via ForemanSession (debug)  │
└─────────────────────────────────────────────────────────────┘
```

**SPAWN mode** (default) gives you the full interactive code-puppy experience with:

- Rich TUI for asking questions
- Specialist otter coordination
- Certificate pinning for approved tools only

**PHASES mode** is a legacy debugging mode that runs the Python state machine directly.

## Installation

```bash
cd python
pip install -e .
```

Or with uv:

```bash
cd python
uv pip install -e .
```

## Quick Start

```python
from stackwright_pro.raft import ClarificationOrchestrator, ClarificationConfig

config = ClarificationConfig(
    defaults={"brand.tone": "Professional"},
    allow_dont_know=True,
)

orchestrator = ClarificationOrchestrator(config=config)

# Ask user for clarification
response = orchestrator.router.ask(request)
```

## Components

- **Clarification Protocol**: Human-in-the-loop for LLMs
- **Channel Router**: TUI → CLI args → Config → Defaults
- **Conflict Detector**: Detects preference vs. choice conflicts
- **Escalation Handler**: Handles stubborn users

## Documentation

- [Clarification Protocol Design](docs/CLARIFICATION_PROTOCOL.md)
- [Otter Raft Design](docs/OTTER_RAFT_DESIGN.md)

## Development

```bash
# Install dev dependencies
pip install pytest pydantic rich

# Run tests
cd python
python -m pytest tests/ -v
```

## License

Proprietary - Per Aspera LLC
