triad-base

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

Source is maintained in a private monorepo. Releases are built and published by GitHub Actions through a PyPI Trusted Publisher; provenance attestations are visible on the PyPI file listing.

What's in the box

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