{
  "schema_version": 1,
  "name": "pcq",
  "version": "4.1.0",
  "pcq_version": "4.6",
  "description": "pcq is the contract for agent-run ML experiments — cq.yaml format, JSON contracts, MCP tool surface, strictness gates, and run-evidence schema. This package is the reference Python implementation of that contract. Other-language implementations (notably the CQ Go service worker) target the same contract.",
  "license": "Apache-2.0",
  "package": {
    "pypi": "pcq",
    "install": "uv add pcq",
    "install_with_mcp": "uv add 'pcq[mcp]'",
    "import": "pcq",
    "cli": "pcq"
  },
  "links": {
    "website": "https://playidea-lab.github.io/pcq/",
    "repository": "https://github.com/playidea-lab/pcq",
    "pypi": "https://pypi.org/project/pcq/",
    "llms": "https://playidea-lab.github.io/pcq/llms.txt",
    "llms_full": "https://playidea-lab.github.io/pcq/llms-full.txt",
    "v4_direction": "https://github.com/playidea-lab/pcq/blob/main/docs/V4_DIRECTION.md",
    "json_contracts": "https://github.com/playidea-lab/pcq/blob/main/docs/JSON_CONTRACTS.md",
    "agent_operating_guide": "https://github.com/playidea-lab/pcq/blob/main/docs/AGENT_OPERATING_GUIDE.md",
    "mcp_integration": "https://github.com/playidea-lab/pcq/blob/main/docs/MCP_INTEGRATION.md"
  },
  "contract": {
    "project_file": "cq.yaml",
    "runtime_env": "CQ_CONFIG_JSON",
    "uri_scheme": "cq://",
    "standard_artifacts": [
      "config.json",
      "metrics.json",
      "manifest.json",
      "run_summary.json",
      "run_record.json",
      "validation_report.json"
    ]
  },
  "commands": [
    {"name": "resolve", "argv": ["pcq", "resolve", "--json"], "mode": "snapshot"},
    {"name": "inspect", "argv": ["pcq", "inspect", ".", "--json"], "mode": "snapshot"},
    {"name": "validate", "argv": ["pcq", "validate", ".", "--strictness", "2", "--json"], "mode": "snapshot"},
    {"name": "run_json", "argv": ["pcq", "run", "--path", ".", "--json"], "mode": "snapshot"},
    {"name": "run_jsonl", "argv": ["pcq", "run", "--path", ".", "--jsonl"], "mode": "stream"},
    {"name": "validate_run", "argv": ["pcq", "validate-run", "output", "--strictness", "3", "--json"], "mode": "snapshot"},
    {"name": "describe_run", "argv": ["pcq", "describe-run", "output", "--json"], "mode": "snapshot"},
    {"name": "compare_runs", "argv": ["pcq", "compare-runs", "A", "B", "--json"], "mode": "snapshot"},
    {"name": "lineage", "argv": ["pcq", "lineage", "output", "--json"], "mode": "snapshot"},
    {"name": "mcp_serve", "argv": ["pcq", "mcp", "serve"], "mode": "stream"}
  ],
  "json_contracts": [
    "pcq.run.envelope",
    "pcq.run.event",
    "pcq.describe_run.record",
    "pcq.compare_runs.diff",
    "pcq.validation_report",
    "pcq.agent_install.result",
    "pcq.agent_status.result"
  ],
  "mcp": {
    "available": true,
    "since_version": "4.1.0",
    "extras": "pcq[mcp]",
    "transports": ["stdio", "sse"],
    "default_transport": "stdio",
    "wire_up_command": "pcq agent install --target claude --path . --mcp",
    "config_file": ".mcp.json",
    "config_example": {
      "mcpServers": {
        "pcq": {
          "command": "pcq",
          "args": ["mcp", "serve"]
        }
      }
    },
    "tools": [
      {"name": "resolve_project", "read_only": true,  "maps_to": "pcq resolve"},
      {"name": "inspect_project", "read_only": true,  "maps_to": "pcq inspect"},
      {"name": "validate_project", "read_only": true, "maps_to": "pcq validate"},
      {"name": "validate_run", "read_only": true,     "maps_to": "pcq validate-run"},
      {"name": "describe_run", "read_only": true,     "maps_to": "pcq describe-run"},
      {"name": "compare_runs", "read_only": true,     "maps_to": "pcq compare-runs"},
      {"name": "lineage_chain", "read_only": true,    "maps_to": "pcq lineage"},
      {"name": "apply_plan", "read_only": false,      "maps_to": "pcq apply-plan"},
      {"name": "apply_planset", "read_only": false,   "maps_to": "pcq apply-planset"},
      {"name": "init_experiment", "read_only": false, "maps_to": "pcq init-experiment"},
      {"name": "finalize_run", "read_only": false,    "maps_to": "pcq finalize"},
      {"name": "agent_install", "read_only": false,   "maps_to": "pcq agent install"},
      {"name": "agent_status", "read_only": true,     "maps_to": "pcq agent status"},
      {"name": "run_experiment", "read_only": false,  "maps_to": "pcq run"}
    ],
    "guarantees": {
      "read_only_tools_never_mkdir": true,
      "read_only_tools_never_mutate_cq_yaml": true,
      "read_only_tools_never_spawn_subprocess": true,
      "schema_frozen_since": "v2.13"
    }
  },
  "case_studies": [
    {
      "slug": "mnist-dogfood-2026-05-08",
      "title": "MNIST Dogfood",
      "date": "2026-05-08",
      "library_version": "pcq 2.11.0",
      "domain": "ml-vision-classification",
      "outcome": "9 fresh agent generations, eval_acc 0.9583 → 1.0; first end-to-end dogfood; drove v2.12 fixes",
      "url": "https://github.com/playidea-lab/pcq/blob/main/docs/case-studies/mnist-dogfood-2026-05-08.md"
    },
    {
      "slug": "tabular-dogfood-2026-05-09",
      "title": "Tabular Dogfood",
      "date": "2026-05-09",
      "library_version": "pcq 3.0.1",
      "domain": "tabular-classification",
      "outcome": "first post-PyPI install path; TabPFN/PyCaret/FLAML/XGBoost/sklearn diversity",
      "url": "https://github.com/playidea-lab/pcq/blob/main/docs/case-studies/tabular-dogfood-2026-05-09.md"
    },
    {
      "slug": "mcp-dogfood-2026-05-10",
      "title": "MCP Dogfood",
      "date": "2026-05-10",
      "library_version": "pcq[mcp] 4.1.0",
      "domain": "agent-mcp-loop",
      "outcome": "first v4.1.0 MCP loop end-to-end via mcp__pcq__* tools (no subprocess CLI); 3 sequential generations",
      "url": "https://github.com/playidea-lab/pcq/blob/main/docs/case-studies/mcp-dogfood-2026-05-10.md"
    },
    {
      "slug": "cq-worker-dogfood-2026-05-10",
      "title": "CQ Worker Dogfood",
      "date": "2026-05-10",
      "library_version": "pcq[mcp] 4.2.0",
      "domain": "cq-service-integration",
      "outcome": "first production CQ Go worker dispatch end-to-end; verified cq.yaml + CQ_CONFIG_JSON + 6-artifact protocol",
      "url": "https://github.com/playidea-lab/pcq/blob/main/docs/case-studies/cq-worker-dogfood-2026-05-10.md"
    }
  ],
  "roadmap_url": "https://github.com/playidea-lab/pcq/blob/main/docs/PCQ_COMPLETION_ROADMAP.md",
  "v4_direction_url": "https://github.com/playidea-lab/pcq/blob/main/docs/V4_DIRECTION.md",
  "spec_url": "https://github.com/playidea-lab/pcq/tree/main/spec",
  "spec_index_url": "https://github.com/playidea-lab/pcq/blob/main/spec/INDEX.md",
  "spec_schemas_url": "https://github.com/playidea-lab/pcq/tree/main/spec/schemas",
  "spec_versioning_url": "https://github.com/playidea-lab/pcq/blob/main/spec/VERSIONING.md",
  "spec_conformance_url": "https://github.com/playidea-lab/pcq/blob/main/spec/CONFORMANCE.md",
  "spec_implementations_url": "https://github.com/playidea-lab/pcq/blob/main/spec/IMPLEMENTATIONS.md",
  "implementations": [
    {
      "slug": "pcq-py",
      "label": "Reference (Python)",
      "language": "python",
      "pypi": "pcq",
      "install": "uv add pcq",
      "source_url": "https://github.com/playidea-lab/pcq/tree/main/src/pcq",
      "license": "Apache-2.0",
      "schema_version": 1,
      "conformance": "automated suite",
      "conformance_url": "https://github.com/playidea-lab/pcq/tree/main/tests/conformance",
      "maintainer": "playidea-lab"
    },
    {
      "slug": "cq-go-worker",
      "label": "Production (CQ Go service worker)",
      "language": "go",
      "source_url": null,
      "schema_version": 1,
      "conformance": "production dogfood",
      "evidence_url": "https://github.com/playidea-lab/pcq/blob/main/docs/case-studies/cq-worker-dogfood-2026-05-10.md",
      "maintainer": "playidea-lab"
    }
  ],
  "tool_response_samples": [
    {
      "name": "describe_run",
      "command": "pcq describe-run output --json",
      "mcp_tool": "mcp__pcq__describe_run",
      "sample_anchor": "https://playidea-lab.github.io/pcq/#tools-catalog-describe_run",
      "captured_from": "examples/contract_sklearn (real run, volatile fields elided)",
      "purpose": "Compact RunRecord summary — best/last metric, artifacts, decision_facts."
    },
    {
      "name": "compare_runs",
      "command": "pcq compare-runs output_a output_b --json",
      "mcp_tool": "mcp__pcq__compare_runs",
      "sample_anchor": "https://playidea-lab.github.io/pcq/#tools-catalog-compare_runs",
      "captured_from": "examples/contract_sklearn (two real runs, output_a vs output_b)",
      "purpose": "Diff two RunRecords — metric delta/direction, validation, source identity, decision_facts."
    },
    {
      "name": "validate_run",
      "command": "pcq validate-run output --strictness 3 --json",
      "mcp_tool": "mcp__pcq__validate_run",
      "sample_anchor": "https://playidea-lab.github.io/pcq/#tools-catalog-validate_run",
      "captured_from": "examples/contract_sklearn (real run at strictness=3 reproducible)",
      "purpose": "Post-run validation gates — pass/warn/fail, per-check evidence, blocking_count."
    },
    {
      "name": "lineage_chain",
      "command": "pcq lineage output --json",
      "mcp_tool": "mcp__pcq__lineage_chain",
      "sample_anchor": "https://playidea-lab.github.io/pcq/#tools-catalog-lineage_chain",
      "captured_from": "examples/contract_sklearn (real run, single-node chain)",
      "purpose": "Walk parent chain — chain[].run_id/depth/best_value, truncated flag."
    }
  ],
  "examples": [
    {
      "name": "sklearn-iris",
      "framework": "scikit-learn",
      "cq_yaml_url": "https://github.com/playidea-lab/pcq/blob/main/examples/contract_sklearn.cq.yaml",
      "script_url": "https://github.com/playidea-lab/pcq/blob/main/examples/contract_sklearn.py"
    },
    {
      "name": "numpy-zero-deps",
      "framework": "numpy",
      "cq_yaml_url": "https://github.com/playidea-lab/pcq/blob/main/examples/contract_numpy.cq.yaml",
      "script_url": "https://github.com/playidea-lab/pcq/blob/main/examples/contract_numpy.py"
    }
  ],
  "agent_policy": {
    "prefer_machine_surfaces": true,
    "do_not_scrape_human_output": true,
    "pcq_reports_facts_not_decisions": true,
    "cq_service_required": false,
    "framework_adapters_required": false,
    "training_loop_owned_by_pcq": false,
    "project_local_training_code_first_class": true,
    "prefer_mcp_when_available": true
  },
  "features": [
    {
      "name": "attribution",
      "version": "4.4",
      "kind": "metadata_field",
      "json_path": "$.attribution",
      "purpose": "Record who ran the experiment (author/committer/operator)",
      "agent_fillable": true,
      "env_prefix": "CQ_ATTRIBUTION_",
      "spec_ref": "spec/SPEC.md#attribution"
    },
    {
      "name": "worker_spec",
      "version": "4.5",
      "kind": "metadata_field",
      "json_path": "$.worker_spec",
      "purpose": "Record where the experiment ran (cpu/gpu/memory/os, host-view)",
      "agent_fillable": true,
      "env_prefix": "CQ_WORKER_",
      "spec_ref": "spec/SPEC.md#worker-spec",
      "pii_safe": true
    },
    {
      "name": "fingerprint",
      "version": "4.6",
      "kind": "metadata_field",
      "json_path": "$.fingerprint",
      "purpose": "PII-safe data fingerprint (modality/task_kind/size/distribution)",
      "agent_fillable": true,
      "env_prefix": "CQ_FINGERPRINT_",
      "spec_ref": "spec/SPEC.md#fingerprint",
      "pii_layered": true
    }
  ]
}