Metadata-Version: 2.5
Name: promptcadence
Version: 1.0.1
Summary: A plan-approved, tier-routed agent loop over LoadCoach, in which every step is proposed, approved against governance policy and remaining budget before it executes, and fully reconstructable afterwards.
Project-URL: Homepage, https://github.com/JPKell/PromptCadence
Project-URL: Documentation, https://github.com/JPKell/PromptCadence/tree/main/docs
Project-URL: Changelog, https://github.com/JPKell/PromptCadence/blob/main/CHANGELOG.md
Author: Local AI Suite contributors
License-Expression: Apache-2.0
License-File: LICENSE
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Typing :: Typed
Requires-Python: >=3.12
Requires-Dist: alembic<2,>=1.13
Requires-Dist: baseaicore<0.5,>=0.4.1
Requires-Dist: commissioner[sql]<0.2,>=0.1
Requires-Dist: cutctx<0.2,>=0.1
Requires-Dist: fastapi<1,>=0.115
Requires-Dist: httpx<1,>=0.27
Requires-Dist: jinja2<4,>=3.1
Requires-Dist: loadledger[sql]<0.3,>=0.2
Requires-Dist: mirrorwall<0.3,>=0.2
Requires-Dist: pydantic-settings<3,>=2.4
Requires-Dist: pydantic<3,>=2.9
Requires-Dist: setspec<0.7,>=0.5
Requires-Dist: sqlalchemy<3,>=2.0.30
Requires-Dist: toolyard<0.2,>=0.1.1
Requires-Dist: typer<1,>=0.12
Requires-Dist: uvicorn[standard]<1,>=0.30
Requires-Dist: weightsdb<0.3,>=0.2
Provides-Extra: dev
Requires-Dist: import-linter<3,>=2.0; extra == 'dev'
Requires-Dist: mypy<2,>=1.11; extra == 'dev'
Requires-Dist: pytest-cov<6,>=5; extra == 'dev'
Requires-Dist: pytest-randomly<4,>=3; extra == 'dev'
Requires-Dist: pytest<10,>=9.0.3; extra == 'dev'
Requires-Dist: respx<1,>=0.21; extra == 'dev'
Requires-Dist: ruff<1,>=0.6; extra == 'dev'
Provides-Extra: postgres
Requires-Dist: psycopg[binary]<4,>=3.2; extra == 'postgres'
Description-Content-Type: text/markdown

# 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/](docs/README.md) for the operator
set and the [development plan](docs/apps/promptcadence/development-plan.md) for what each phase
added.

Part of the **Local AI Suite**. Reaches a model only through [LoadCoach](https://github.com/JPKell/LoadCoach)'s
HTTP API — it never imports a model provider directly ([ADR-0045](docs/adr/0045-promptcadence-reaches-models-only-through-loadcoach.md)
in the suite's shared documentation).

## Install

```bash
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](docs/apps/promptcadence/spec.md) §12 for the full configuration
surface and `PROMPTCADENCE_*` environment variables.

## Quickstart

```bash
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](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](docs/upgrading.md) for the compatibility table.

## Documentation

| Read this | For |
|---|---|
| [docs/README.md](docs/README.md) | The operator set: quickstart, configuration reference, tiers, security, operations, troubleshooting, upgrading, the OpenAPI snapshot |
| [docs/apps/promptcadence/spec.md](docs/apps/promptcadence/spec.md) | Purpose, scope, non-goals, public contracts, configuration, acceptance criteria |
| [docs/apps/promptcadence/lifecycle.md](docs/apps/promptcadence/lifecycle.md) | The trajectory state machine, deviation categories and estimator |
| [docs/apps/promptcadence/development-plan.md](docs/apps/promptcadence/development-plan.md) | The phased build plan: goals, work, tests, acceptance criteria per phase |

## Development

```bash
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`](SECURITY.md) for how to report a vulnerability.

## License

Apache-2.0 — see [`LICENSE`](LICENSE).
