PromptCadence

A plan-approved, tier-routed agent loop over LoadCoach in which every step is proposed in a plan, the plan is approved against governance policy and remaining budget before any step executes, and every turn that does execute is fully reconstructable afterwards — which model ran it, on which tier, on what data, at what cost, under whose approval.

Status: 1.0.0 (M12). Every phase of the development plan is built and gated: planning with corrective retries and three approval modes, the ExecutionIntent every turn runs under, sandboxed tools under ToolYard's isolation ladder, the budget over LoadLedger with three ceilings, egress governance over Commissioner with a durable decision per turn, per-step retry, context compaction as a view, the composed and materialized explanation, the operator console, the retention sweep, the security checklist and the prompt-injection corpus as release gates, and every spec §15 budget asserted. Remote tiers refuse honestly until LoadCoach has a registration declaring remote = true and the tier is priced (ADR-0098). See docs/ for the operator set and the development plan for what each phase added.

Part of the Local AI Suite. Reaches a model only through LoadCoach's HTTP API — it never imports a model provider directly (ADR-0045 in the suite's shared documentation).

Install

pip install promptcadence
promptcadence serve

Starts on 127.0.0.1:8768 with zero configuration. Health reports the loadcoach component degraded (not unavailable) when no LoadCoach is reachable — PromptCadence requires LoadCoach for execution, never for startup. See docs/apps/promptcadence/spec.md §12 for the full configuration surface and PROMPTCADENCE_* environment variables.

Quickstart

pip install promptcadence
promptcadence serve            # starts the API on 127.0.0.1:8768
promptcadence health --json    # same health data the API reports, from the CLI
promptcadence run "summarize the files in ./notes" --follow     # plan, approve, execute, explain
promptcadence run "summarize the files in ./notes" --bypass-planning --follow
promptcadence trajectory explain <id>                           # every model, tier, tool call, debit, egress verdict
promptcadence --help

Open http://127.0.0.1:8768/ for the console. Read docs/quickstart.md next.

PromptCadence 1.0 is tested against LoadCoach 1.1.0 and needs ≥ 1.1: the declared finish reason on the wire (spec §11 contract 6 — an undeclared finish is never read as success), tool definitions and tool_calls on /generate, and the serving registration's is_remote on every response. See docs/upgrading.md for the compatibility table.

Documentation

Development

python -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"
pre-commit install
pytest -m "not live and not performance"

See SECURITY.md for how to report a vulnerability.

License

Apache-2.0 — see LICENSE.