triad-base 0.2.0

Primitives for thinker / doer / checker agent triads — types, prompt builders, preflight gates, agent-state schemas

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

pip install triad-base

Usage sketch

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