pcq experiment contracts

Apache-2.0 Python library

Run anything. Standardize the evidence.

pcq turns ML experiments into agent-operable, reproducible units. Keep your existing training stack; pcq standardizes the run boundary: contract, live evidence, validation, comparison, lineage, and final run record.

Install from PyPI Read the v4 direction
uv add pcq

Why pcq

Not another trainer. Control around the run.

Framework-neutral

Use PyTorch, Hugging Face Trainer, Lightning, sklearn, TabPFN, PyCaret, XGBoost, shell scripts, or custom Python. pcq standardizes the surrounding evidence instead of replacing the training loop.

Agent-readable

JSON CLI surfaces, strictness gates, manifests, lineage, and run summaries are designed for coding agents, CI jobs, and services that need facts rather than prose.

Reproducible boundary

Config, metrics, source identity, environment, inputs, artifacts, validation, and best/last results converge into one run_record.json.

Core contract

A small set of files that every run can explain.

pcq keeps the model code free-form and makes the run boundary explicit. The project declares intent in cq.yaml, the script emits metrics, and pcq finalizes the standard artifacts.

  • cq.yaml declares command, config, metrics, inputs, and artifacts.
  • pcq.log() emits structured metric history.
  • pcq.save_all() writes the standard artifact set.
  • pcq finalize turns a run directory into evidence.
config.json metrics.json manifest.json run_summary.json run_record.json validation_report.json

Agent-operable by design

Enough structure for an agent to inspect, run, validate, and decide.

pcq gives agents stable machine-readable surfaces while leaving policy to the agent or service. The library reports facts: what ran, what changed, what passed, what failed, which artifacts exist, and how a candidate compares with its parent.

inspect validate run run --jsonl validate-run describe-run compare-runs lineage agent status

Quickstart

Create a contract project and produce a run record.

uv add pcq
pcq init-experiment --style script --output ./my-exp --with-pyproject
cd ./my-exp
uv sync
pcq run --json
pcq validate-run output --json
pcq describe-run output --json

Relationship with CQ

pcq is the open contract. CQ is one managed consumer.

pcq

Open-source authoring, validation, artifact, and run-evidence library.

CQ

Managed execution, queueing, artifact collection, dashboards, and agent loops.