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

cd python
pip install -e .

Or with uv:

cd python
uv pip install -e .

Quick Start

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
• Otter Raft Design

Development

# Install dev dependencies
pip install pytest pydantic rich

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

License

Proprietary - Per Aspera LLC