Metadata-Version: 2.4
Name: triad-base
Version: 0.2.0
Summary: Primitives for thinker / doer / checker agent triads — types, prompt builders, preflight gates, agent-state schemas
License: MIT
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Development Status :: 4 - Beta
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pydantic>=2.0
Requires-Dist: pyyaml>=6.0
Provides-Extra: dev
Requires-Dist: pytest>=9.0.3; extra == "dev"
Requires-Dist: pytest-cov>=4.0; extra == "dev"
Dynamic: license-file

# triad-base

Primitives for building thinker / doer / checker agent triads with Claude (or any LLM).

## What's in the box

| Module | What it gives you |
|---|---|
| `triad_base.types` | `AgentType` / `PlanStatus` enums; `Plan`, `AgentMetadata`, `ExecutionResult` dataclasses; `parse_agent_metadata()` parser |
| `triad_base.state.schema` | Pydantic v2 models for agent state JSON (`ThinkerState` / `DoerState` / `CheckerState` / `Heartbeat` / `ExecutionRecord` / interventions) + `load_state` / `save_state` / `validate_state_file` |
| `triad_base.state.validation` | `validate_file` / `validate_directory` / `migrate_file` / `migrate_directory` / `check_schema_compatibility` |
| `triad_base.preflight` | `HealthChecker` (disk space · state-dir writable · stale locks · optional config valid · Claude CLI present) + `create_checkpoint` / `restore_checkpoint` / `clear_checkpoint` (git-stash rollback) |
| `triad_base.orchestrator` | `TriadContext` + `build_thinker_prompt` / `build_doer_prompt` / `build_checker_prompt` + `format_prior_suggestions` |
| `triad_base.verdict` | Typed gate/judge verdict contract (schema v1) — Verdict / Finding / ReviewerError / ReviewerResult + to_json_schema(); pool-pure, pydantic-only |

## Design

**Pure plumbing, no transport.** The library assembles prompts and parses output; it does not call Claude. Consumers wire the prompts to their own transport (CLI subprocess, Anthropic SDK, direct API). Transport is intentionally out of scope so different consumers can diverge in dispatch (CLI vs SDK vs API) without dragging shared transport glue along.

**Narrow surface.** Five small modules. No CLI, no `__main__`, no opinionated workflow. You compose the parts you need.

## Install

```bash
pip install triad-base
```

## Usage sketch

```python
from pathlib import Path
from triad_base.types import AgentType, Plan, PlanStatus
from triad_base.orchestrator import TriadContext, build_thinker_prompt
from triad_base.preflight import HealthChecker

# Preflight before kicking off
report = HealthChecker(
    portfolio_root=Path("/repo"),
    state_dir=Path("/repo/.state"),
).run_all_checks()
if not report.ok:
    raise RuntimeError(report.summary())

# Build a thinker prompt
plan = Plan(id="ex-001", target_project="myproject", status=PlanStatus.READY, ...)
ctx = TriadContext(
    plan=plan,
    state_dir=Path("/repo/.state"),
    working_dir=Path("/repo"),
    prior_suggestions=None,
    test_output="",
    thinking_context="",
    execution_context_tail="",  # add your own logging / state-persistence block
)
prompt = build_thinker_prompt(ctx)

# Hand `prompt` to your Claude transport of choice; you own that part.
```

## Versioning

Semantic versioning. `0.x.y` series — interface may change between minor versions during early use; pin in your consumer's `requirements.txt` or `pyproject.toml` accordingly.

## Dependencies

- `pydantic>=2.0`
- `pyyaml>=6.0`

## License

MIT
