AI Evals

Make evaluation an authoritative, versioned decision system. Prefer deterministic evidence, fail closed on contract ambiguity, and preserve provenance from row through release gate.

Design the eval

1. State the product decision the eval must support. Define the target, evaluation unit, population, critical failures, practical effect, and release consequence before choosing metrics.
2. Model realistic scenarios. Cover success paths, edge cases, adversarial behavior, tool errors, handoffs, long context, ambiguity, and recovery. Evaluate components and end-to-end behavior without mistaking one for the other.
3. Define strict input, output, variable, operation, and grader schemas. Version the target, prompt, dataset, evaluator, thresholds, and run plan.
4. Build immutable sample manifests with unique stable row_id values. Seal the exact ordered row hashes in sample_manifest_id and record the governing data_policy_fingerprint; reject mismatches. Join results by ID, never list position. Separate train, validation, holdout, and blind holdout before optimization.
5. Compose the narrowest graders that measure the real requirement. Prefer exact, contains, regex, schema, executable, tool-call, latency, cost, and policy checks before model judges. Use all, any, not, weighted, and hard-gate operations to preserve field-level meaning.
6. Calibrate model or human graders against representative human labels. Measure disagreement, false negatives on critical cases, expected-output leakage, judge-version drift, and model-family dependence. Require concise user-visible rationales; never request or persist hidden chain-of-thought.
7. Persist the gate cascade: field → item-row → row → dataset → eval set → target → criticality group → run. Let downstream systems consume the official decision instead of recomputing averages.
8. Compare candidates on the same manifest. Report sample size, uncertainty interval, paired effect, practical threshold, critical regressions, cost, and latency. Use repeated trials for stochastic targets and do not claim a winner when evidence is inconclusive.

Optimize only after calibration