playidea-lab/pcq

> **pcq is the contract for agent-run ML experiments.**
> This repository hosts the contract specification under spec/
> and the reference Python implementation under src/pcq/.
> Install the reference impl: uv add pcq (Apache-2.0).
The contract turns a project with cq.yaml into a reproducible experiment
unit. The reference Python implementation loads config, resolves output
paths, captures metrics, writes standard artifacts, finalizes run evidence,
and exposes JSON/JSONL/MCP surfaces that coding agents, CI jobs, notebooks,
and services can consume. See spec/IMPLEMENTATIONS.md
for the registered implementation list (Python reference + CQ Go production
worker today) and the procedure for adding yours.
pcq is **not** a training framework, model zoo, adapter matrix, or CQ-only
client. Use PyTorch, Hugging Face Trainer, Lightning, sklearn, TabPFN, PyCaret,
XGBoost, shell scripts, remote jobs, or project-local research code. The
contract is the integration layer.
SITE |
INTRODUCTION |
V4_DIRECTION |
VISION |
AGENT_OPERABILITY |
RUN_RECORD |
AGENT_OPERATING_GUIDE |
CHANGELOG
Contract specification (single source of truth):
spec/INDEX.md |
SPEC |
CQ_YAML_RUNTIME_CONTRACT |
JSON_CONTRACTS |
STRICTNESS |
CQ_MCP_SPEC |
VERSIONING |
CONFORMANCE |
schemas/ (auto-exported via scripts/export_schemas.py)
Case studies (external evidence):
mnist-dogfood |
tabular-dogfood |
mcp-dogfood |
cq-worker-dogfood
Agent-readable site files:
llms.txt,
llms-full.txt,
agent-manifest.json.
Identity
CQ service is one managed consumer of the contract. pcq remains useful without
CQ: locally, in CI, in notebooks, and inside third-party orchestrators.
Why pcq
- **Framework-neutral** — keep the training stack that fits the problem.
- **Agent-readable** — use JSON/JSONL instead of terminal scraping.
- **Agent-verifiable** — validate source, config, environment, metrics,
artifacts, and run records.
- **Agent-operable** — run, observe, validate, describe, compare, lineage, and
iterate through stable commands.
- **Service-ready** — CQ can consume the same contract for managed execution and
automatic experiment loops.
What's New (v4.4 – v4.6)
Three agent-fillable metadata fields were added to run_record.json across the
last three minor releases, making each run's evidence richer with zero extra
code in most cases.
| Field | Since | Captures | Auto-filled? |
|---|---|---|---|
| attribution | v4.4 | author / committer / operator — **who** ran the experiment | Yes (agent identity injected at runtime) |
| worker_spec | v4.5 | cpu / gpu / memory / os — **where** it ran | Yes (pcq.worker_spec() auto-detects hardware) |
| fingerprint | v4.6 | modality / task_kind / shape / PII-safe stats — **what** data | Semi-auto (pcq.fingerprint(X, y) detects most fields) |
attribution — who
Records the human author, the AI committer, and the operator that launched the
run. Coding agents (Claude Code, Codex) fill this automatically from their
identity context.
Spec: spec/SPEC.md § Attribution
worker_spec — where
Records CPU model, core count, GPU kind/VRAM, total memory, and OS. Called with
no arguments for a full auto-detection pass.
Spec: spec/SPEC.md § Worker Spec
fingerprint — what
Records dataset modality, task kind, sample count, size class, domain, and
PII-safe summary statistics. Accepts a NumPy/pandas array or DataFrame and