medagentrx 0.1.0__py3-none-any.whl

medagentrx/__init__.py

@@ -0,0 +1,30 @@
+# SPDX-FileCopyrightText: 2026 Ahmed Hemedan
+# SPDX-License-Identifier: Apache-2.0
+"""MedAgentRx: an executable gate for changes to clinical prediction models.
+
+Every model update, by an engineer, a pipeline or an AI agent, is checked
+against its approved change plan and receives one verdict: ACCEPTED, FAILED
+or OUTSIDE_PLAN.
+"""
+
+__version__ = "0.1.0"
+
+from medagentrx.api import CheckResult, check
+from medagentrx.engine import Evaluation, Verdict, evaluate
+from medagentrx.errors import InputError, MedAgentRxError, PlanError, StatsError
+from medagentrx.plan import ChangePlan, load_plan
+
+__all__ = [
+    "ChangePlan",
+    "CheckResult",
+    "Evaluation",
+    "InputError",
+    "MedAgentRxError",
+    "PlanError",
+    "StatsError",
+    "Verdict",
+    "__version__",
+    "check",
+    "evaluate",
+    "load_plan",
+]

medagentrx/__main__.py

@@ -0,0 +1,8 @@
+# SPDX-FileCopyrightText: 2026 Ahmed Hemedan
+# SPDX-License-Identifier: Apache-2.0
+"""Allow ``python -m medagentrx``."""
+
+from medagentrx.cli import run
+
+if __name__ == "__main__":
+    run()

medagentrx/api.py

@@ -0,0 +1,109 @@
+# SPDX-FileCopyrightText: 2026 Ahmed Hemedan
+# SPDX-License-Identifier: Apache-2.0
+"""Python API: check one update and record it, as ``medagentrx check`` does.
+
+from medagentrx import check, Verdict
+
+result = check(plan="change-plan.yaml", candidate="cand.parquet",
+               previous="prev.parquet", anchor="anchor.parquet",
+               manifest="train_manifest.parquet", model_meta="model.yaml",
+               ledger="ledger.jsonl", out="report/")
+assert result.verdict is Verdict.ACCEPTED
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterable
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+from medagentrx.engine import Evaluation, Verdict, evaluate
+from medagentrx.errors import PlanError
+from medagentrx.io.limits import Limits
+from medagentrx.ledger import append, exclusive, load_history, read_entries, signing_policy
+from medagentrx.plan import load_plan
+from medagentrx.report.writer import FORMATS, write_reports
+from medagentrx.stats.bootstrap import DEFAULT_REPLICATES
+
+
+@dataclass(frozen=True)
+class CheckResult:
+    """Outcome of ``check``.
+
+    Attributes:
+        evaluation: Every finding and number behind the verdict.
+        ledger_entry: The entry written to the ledger, or None for an invalid plan.
+        reports: Written report files by format.
+    """
+
+    evaluation: Evaluation
+    ledger_entry: dict[str, Any] | None
+    reports: dict[str, Path] = field(default_factory=dict)
+
+    @property
+    def verdict(self) -> Verdict:
+        """ACCEPTED, FAILED or OUTSIDE_PLAN."""
+        return self.evaluation.verdict
+
+    @property
+    def exit_code(self) -> int:
+        """0 ACCEPTED, 1 FAILED, 2 OUTSIDE_PLAN."""
+        return int(self.evaluation.exit_code)
+
+
+def check(
+    *,
+    plan: str | Path,
+    candidate: str | Path,
+    previous: str | Path,
+    anchor: str | Path,
+    manifest: str | Path,
+    model_meta: str | Path,
+    ledger: str | Path,
+    out: str | Path,
+    seed: int = 0,
+    n_replicates: int = DEFAULT_REPLICATES,
+    formats: Iterable[str] = tuple(FORMATS),
+    limits: Limits | None = None,
+    signing_key: str | Path | None = None,
+) -> CheckResult:
+    """Check one update against its plan, record it in the ledger and write reports.
+
+    The ledger is locked from reading its budgets until the new entry is
+    written. An invalid plan gives OUTSIDE_PLAN and is not recorded. When the
+    plan names a ledger signing key, ``signing_key`` must be that private key;
+    the existing head is verified with it and the new head is signed.
+
+    Raises:
+        InputError: If an input file other than the plan is missing or invalid.
+        LedgerError: If the ledger fails verification.
+    """
+    ledger_path = Path(ledger)
+    try:
+        change_plan = load_plan(plan)
+    except PlanError:
+        change_plan = None
+    key = signing_policy(change_plan, Path(signing_key) if signing_key is not None else None)
+    public_key = key.public_key() if key is not None else None
+    ledger_path.parent.mkdir(parents=True, exist_ok=True)
+    with exclusive(ledger_path):
+        evaluation = evaluate(
+            plan=plan,
+            candidate=candidate,
+            previous=previous,
+            anchor=anchor,
+            manifest=manifest,
+            model_meta=model_meta,
+            history=load_history(ledger_path, public_key=public_key),
+            seed=seed,
+            n_replicates=n_replicates,
+            limits=limits,
+        )
+        entry = None
+        if evaluation.plan_id is not None:
+            entry = append(ledger_path, evaluation, already_locked=True, signing_key=key)
+    reports = write_reports(
+        Path(out), evaluation, formats=formats, entry=entry, entries=read_entries(ledger_path)
+    )
+    return CheckResult(evaluation=evaluation, ledger_entry=entry, reports=reports)

medagentrx/card.py

@@ -0,0 +1,152 @@
+# SPDX-FileCopyrightText: 2026 Ahmed Hemedan
+# SPDX-License-Identifier: Apache-2.0
+"""Model card sections built from an accepted report.
+
+Each version gets one Markdown section between markers. Running the command
+again for the same version replaces that section, so the card never holds
+two copies. Only accepted versions are written, because only they may be
+released.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+from functools import cache
+from importlib import resources
+from pathlib import Path
+from typing import Any
+
+import jsonschema
+
+from medagentrx.errors import InputError
+from medagentrx.io.paths import resolve_input
+from medagentrx.io.text import read_text_limited
+from medagentrx.plan import plan_fingerprint
+from medagentrx.plan.models import ChangePlan
+from medagentrx.report.build import check
+from medagentrx.report.figures import signed
+
+MAX_REPORT_BYTES = 50_000_000
+
+
+@cache
+def report_schema() -> dict[str, Any]:
+    """The published JSON Schema of ``report.json``."""
+    text = (resources.files("medagentrx.report") / "report.schema.json").read_text(encoding="utf-8")
+    schema: dict[str, Any] = json.loads(text)
+    return schema
+
+
+def _reject_constant(name: str) -> None:
+    raise ValueError(f"non-standard JSON constant {name}")
+
+
+def load_report(path: str | Path) -> dict[str, Any]:
+    """Read and validate a ``report.json``.
+
+    Raises:
+        InputError: If the file is unsafe, not JSON, or does not match the schema.
+    """
+    real = resolve_input(path)
+    text = read_text_limited(real, max_bytes=MAX_REPORT_BYTES)
+    try:
+        data = json.loads(text, parse_constant=_reject_constant)
+    except (json.JSONDecodeError, ValueError) as exc:
+        raise InputError(f"{path}: not valid JSON ({exc})") from None
+    errors = sorted(jsonschema.Draft202012Validator(report_schema()).iter_errors(data), key=str)
+    if errors:
+        raise InputError(
+            f"{path}: not a MedAgentRx report",
+            [
+                f"{'.'.join(map(str, e.absolute_path)) or '<root>'}: {e.message}"
+                for e in errors[:10]
+            ],
+        )
+    result: dict[str, Any] = data
+    return result
+
+
+def _markers(version: str) -> tuple[str, str]:
+    return (
+        f"<!-- medagentrx:begin version={version} -->",
+        f"<!-- medagentrx:end version={version} -->",
+    )
+
+
+def card_section(report: dict[str, Any]) -> str:
+    """Markdown section for the report's candidate version."""
+    card = check(report, "DOC-001")["details"].get("card")
+    if card is None:
+        raise InputError("the report has no model card data (DOC-001 did not run)")
+    version = report["candidate_version"]
+    begin, end = _markers(version)
+    low, high = card["auroc_ci"]
+    rows = [
+        ("AUROC (95% CI)", f"{card['auroc']:.3f} ({low:.3f} to {high:.3f})"),
+        ("Calibration slope", f"{card['calibration_slope']:.3f}"),
+        ("Calibration intercept", signed(card["calibration_intercept"], 3)),
+        ("Brier score", f"{card['brier']:.4f}"),
+        (f"Sensitivity at threshold {card['threshold']:g}", f"{card['sensitivity']:.3f}"),
+        (f"Specificity at threshold {card['threshold']:g}", f"{card['specificity']:.3f}"),
+        ("Locked test set", f"{card['n']} rows, {card['n_pos']} positive"),
+    ]
+    for name, test in check(report, "PERF-001")["details"].get("tests", {}).items():
+        label = name.replace("vs_", "AUROC change against ")
+        rows.append(
+            (label, f"{signed(test['delta'], 4)} (lower bound {signed(test['ci_lower'], 4)})")
+        )
+    ledger = report.get("ledger") or {}
+    entry = f" Ledger entry {ledger['seq']} ({ledger['hash'][:16]})." if ledger.get("hash") else ""
+    lines = [
+        begin,
+        f"## Version {version}",
+        "",
+        (
+            f"Accepted under plan {report['plan']['id']} revision {report['plan']['revision']} "
+            f"as modification {report['modification_id']}, replacing {report['previous_version']}. "
+            f"Evaluated {report['evaluated_at'][:10]}.{entry}"
+        ),
+        "",
+        "| Measure | Value |",
+        "|---|---|",
+        *(f"| {k} | {v} |" for k, v in rows),
+        "",
+        end,
+    ]
+    return "\n".join(lines) + "\n"
+
+
+def update_card(card_path: Path, plan: ChangePlan, report: dict[str, Any]) -> Path:
+    """Insert or replace the report's version section in the model card.
+
+    Raises:
+        InputError: If the report is not accepted, belongs to another plan, or
+            the card path is unsafe.
+    """
+    if report["verdict"] != "ACCEPTED":
+        raise InputError(
+            f"only accepted versions go on the model card; this report is {report['verdict']}"
+        )
+    if report["plan"]["fingerprint"] != plan_fingerprint(plan):
+        raise InputError("the report was produced under a different plan or plan revision")
+    if card_path.is_symlink() or (card_path.exists() and not card_path.is_file()):
+        raise InputError(f"{card_path}: the model card must be a regular file")
+    section = card_section(report)
+    begin, end = _markers(report["candidate_version"])
+    if card_path.exists():
+        text = card_path.read_text(encoding="utf-8")
+    else:
+        text = (
+            f"# Model card: {plan.plan.device}\n\n"
+            "Performance of each released version on the locked test set, "
+            "recorded by MedAgentRx.\n\n"
+        )
+    pattern = re.compile(re.escape(begin) + r".*?" + re.escape(end) + r"\n?", re.S)
+    if pattern.search(text):
+        text = pattern.sub(lambda _: section, text, count=1)
+    else:
+        text = text.rstrip("\n") + "\n\n" + section
+    card_path.parent.mkdir(parents=True, exist_ok=True)
+    card_path.write_text(text, encoding="utf-8")
+    return card_path

medagentrx/checks/__init__.py

@@ -0,0 +1,14 @@
+# SPDX-FileCopyrightText: 2026 Ahmed Hemedan
+# SPDX-License-Identifier: Apache-2.0
+"""Check families. Importing this package registers every check."""
+
+from medagentrx.checks import (  # noqa: F401
+    data_checks,
+    doc_checks,
+    life_checks,
+    perf_checks,
+    plan_checks,
+)
+from medagentrx.checks.registry import REGISTRY, Breaks, Family, Finding, Status, catalogue
+
+__all__ = ["REGISTRY", "Breaks", "Family", "Finding", "Status", "catalogue"]

medagentrx/checks/context.py

@@ -0,0 +1,111 @@
+# SPDX-FileCopyrightText: 2026 Ahmed Hemedan
+# SPDX-License-Identifier: Apache-2.0
+"""Everything the checks read, gathered once per evaluation."""
+
+from __future__ import annotations
+
+import datetime as dt
+from dataclasses import dataclass, field
+from functools import cached_property
+
+from medagentrx.history import History
+from medagentrx.io.manifest import Manifest
+from medagentrx.io.metadata import ModelMeta
+from medagentrx.io.predictions import Predictions, RowMismatch
+from medagentrx.plan.models import ChangePlan
+from medagentrx.stats.alpha import AlphaState
+from medagentrx.stats.delong import AucCovariance, delong
+
+
+@dataclass(frozen=True)
+class Versions:
+    """Candidate, previous and anchor predictions aligned on the same rows."""
+
+    candidate: Predictions
+    previous: Predictions
+    anchor: Predictions
+
+
+@dataclass
+class Context:
+    """Inputs and shared results for one evaluation.
+
+    Attributes:
+        plan: The validated change plan.
+        plan_fingerprint: Fingerprint of the plan.
+        meta: Candidate model metadata.
+        candidate: Candidate predictions as loaded.
+        test_fingerprint: Fingerprint of the candidate's test rows and labels.
+        versions: Aligned predictions, or None if rows or labels differ.
+        mismatches: Row mismatch per comparator file, empty when aligned.
+        manifest: Training data manifest.
+        manifest_sha256: SHA-256 of the manifest file.
+        prediction_sha256: SHA-256 of the candidate, previous and anchor files, by role.
+        test_features: Feature columns present in both the manifest and the test file.
+        history: Budgets used by earlier evaluations.
+        alpha_state: Alpha accounting before this evaluation.
+        alpha: One-sided level for this evaluation, or None if the budget is exhausted.
+        seed: Seed for every resampling step.
+        n_replicates: Bootstrap replicates.
+        now: Time of the evaluation.
+    """
+
+    plan: ChangePlan
+    plan_fingerprint: str
+    meta: ModelMeta
+    candidate: Predictions
+    test_fingerprint: str
+    versions: Versions | None
+    mismatches: dict[str, RowMismatch]
+    manifest: Manifest
+    manifest_sha256: str
+    prediction_sha256: dict[str, str]
+    test_features: dict[str, tuple[str, ...]]
+    history: History
+    alpha_state: AlphaState
+    alpha: float | None
+    seed: int
+    n_replicates: int
+    now: dt.datetime
+    notes: list[str] = field(default_factory=list)
+    outside_plan_failures: list[str] = field(default_factory=list)
+
+    @property
+    def test_set_is_locked(self) -> bool:
+        """True when the candidate's test rows match the plan's fingerprint."""
+        return self.test_fingerprint == self.plan.data_management.locked_test_set.sha256
+
+    @property
+    def performance_blocker(self) -> str | None:
+        """Why performance cannot be assessed, or None when it can.
+
+        An update already outside the plan is not evaluated on the locked
+        test set, so it spends no look.
+        """
+        if self.outside_plan_failures:
+            return f"the update is outside the plan ({', '.join(self.outside_plan_failures)})"
+        if not self.test_set_is_locked:
+            return "the test set is not the locked test set (DATA-001)"
+        if self.versions is None:
+            return "prediction files do not share the same rows and labels (DATA-001)"
+        if self.alpha is None:
+            return "the alpha budget is exhausted (LIFE-002)"
+        return None
+
+    def require_versions(self) -> Versions:
+        """Aligned predictions. Only call after ``performance_blocker`` is None."""
+        if self.versions is None:  # pragma: no cover  # guarded by performance_blocker
+            raise RuntimeError("predictions are not aligned")
+        return self.versions
+
+    def require_alpha(self) -> float:
+        """Level for this evaluation. Only call after ``performance_blocker`` is None."""
+        if self.alpha is None:  # pragma: no cover  # guarded by performance_blocker
+            raise RuntimeError("alpha budget exhausted")
+        return self.alpha
+
+    @cached_property
+    def aucs(self) -> AucCovariance:
+        """DeLong AUROC and covariance of candidate, previous and anchor, in that order."""
+        v = self.require_versions()
+        return delong(v.candidate.y_true, v.candidate.y_score, v.previous.y_score, v.anchor.y_score)

medagentrx/checks/data_checks.py

@@ -0,0 +1,265 @@
+# SPDX-FileCopyrightText: 2026 Ahmed Hemedan
+# SPDX-License-Identifier: Apache-2.0
+"""DATA checks: was the update trained and tested on the data the plan allows?"""
+
+from __future__ import annotations
+
+import math
+from collections.abc import Sequence
+
+import numpy as np
+
+from medagentrx.checks.context import Context
+from medagentrx.checks.registry import Breaks, Family, Finding, Status, check
+from medagentrx.io.predictions import ROW_ID
+from medagentrx.plan.conditions import evaluate_columns
+from medagentrx.stats.smd import SMD_WARNING, categorical_smd, numeric_smd
+
+EXAMPLES = 5
+MAX_LEVELS = 50
+"""Categorical columns with more levels are identifiers, not features, and are skipped."""
+
+
+@check(
+    "DATA-001",
+    Family.DATA,
+    "Locked test set is unchanged",
+    Breaks.OUTSIDE_PLAN,
+    "Modification Protocol, data management",
+)
+def locked_test_set(ctx: Context) -> Finding:
+    """Fingerprint must match the plan, and all versions must share rows and labels."""
+    planned = ctx.plan.data_management.locked_test_set.sha256
+    details: dict[str, object] = {
+        "plan_fingerprint": planned,
+        "candidate_fingerprint": ctx.test_fingerprint,
+        "rows": ctx.candidate.n,
+        "mismatches": {name: m.describe() for name, m in ctx.mismatches.items()},
+    }
+    if not ctx.test_set_is_locked:
+        return Finding(
+            "DATA-001",
+            Status.FAIL,
+            "Test set fingerprint does not match the plan; rows or labels have changed",
+            details,
+        )
+    if ctx.mismatches:
+        names = ", ".join(sorted(ctx.mismatches))
+        return Finding(
+            "DATA-001",
+            Status.FAIL,
+            f"Prediction files for {names} do not have the same rows and labels as the candidate",
+            details,
+        )
+    return Finding(
+        "DATA-001", Status.PASS, f"Locked test set matches ({ctx.candidate.n} rows)", details
+    )
+
+
+def _test_keys(ctx: Context, key: str) -> set[str]:
+    if key == ROW_ID:
+        return set(ctx.candidate.row_id.tolist())
+    return set(ctx.candidate.subgroups[key].tolist())
+
+
+def _train_keys(ctx: Context, key: str) -> set[str]:
+    manifest = ctx.manifest
+    if key == ROW_ID:
+        return set(manifest.row_id)
+    if key == "patient_id":
+        return set(manifest.patient_id)
+    return {str(v) for v in manifest.columns[key] if v is not None}
+
+
+@check(
+    "DATA-002",
+    Family.DATA,
+    "No overlap between training and test data",
+    Breaks.FAILED,
+    "Data management; test data sequestration",
+)
+def no_overlap(ctx: Context) -> Finding:
+    """No value of a ``forbid_overlap_on`` key may occur in both training and test data."""
+    overlaps: dict[str, dict[str, object]] = {}
+    for key in ctx.plan.data_management.forbid_overlap_on:
+        shared = sorted(_test_keys(ctx, key) & _train_keys(ctx, key))
+        if shared:
+            overlaps[key] = {"count": len(shared), "examples": shared[:EXAMPLES]}
+    details = {"keys": list(ctx.plan.data_management.forbid_overlap_on), "overlaps": overlaps}
+    if overlaps:
+        summary = "; ".join(f"{k}: {v['count']}" for k, v in overlaps.items())
+        return Finding(
+            "DATA-002", Status.FAIL, f"Training data overlaps the test set ({summary})", details
+        )
+    return Finding(
+        "DATA-002", Status.PASS, "No training row shares a key with the test set", details
+    )
+
+
+@check(
+    "DATA-003",
+    Family.DATA,
+    "Every training row meets the inclusion criteria",
+    Breaks.OUTSIDE_PLAN,
+    "Data management; AI Act Art. 10",
+)
+def training_inclusion(ctx: Context) -> Finding:
+    """Every manifest row must satisfy ``training_inclusion``.
+
+    The manifest must also be the one named in the model metadata, or the
+    training data cannot be verified.
+    """
+    manifest = ctx.manifest
+    if ctx.manifest_sha256 != ctx.meta.training_manifest_sha256:
+        return Finding(
+            "DATA-003",
+            Status.FAIL,
+            "Training manifest does not match training_manifest_sha256 in the model metadata",
+            {"manifest_sha256": ctx.manifest_sha256, "metadata": ctx.meta.training_manifest_sha256},
+        )
+    condition = ctx.plan.data_management.training_inclusion
+    meets = evaluate_columns(condition, manifest.columns, manifest.n)
+    failing = [manifest.row_id[i] for i in np.flatnonzero(~meets)]
+    details = {"rows": manifest.n, "failing": len(failing), "examples": failing[:EXAMPLES]}
+    if failing:
+        return Finding(
+            "DATA-003",
+            Status.FAIL,
+            f"{len(failing)} of {manifest.n} training rows do not meet the inclusion criteria",
+            details,
+        )
+    return Finding(
+        "DATA-003",
+        Status.PASS,
+        f"All {manifest.n} training rows meet the inclusion criteria",
+        details,
+    )
+
+
+@check(
+    "DATA-004",
+    Family.DATA,
+    "Test-set evaluation budget is not exceeded",
+    Breaks.OUTSIDE_PLAN,
+    "Test data sequestration; adaptive overfitting (Dwork et al. 2015)",
+)
+def evaluation_budget(ctx: Context) -> Finding:
+    """This look must fit inside ``max_evaluations``."""
+    limit = ctx.plan.data_management.locked_test_set.max_evaluations
+    used = ctx.history.looks_used
+    details = {"looks_used_before": used, "max_evaluations": limit, "this_look": used + 1}
+    if used >= limit:
+        return Finding(
+            "DATA-004",
+            Status.FAIL,
+            f"All {limit} looks at the locked test set have been used",
+            details,
+        )
+    return Finding(
+        "DATA-004", Status.PASS, f"Look {used + 1} of {limit} at the locked test set", details
+    )
+
+
+def _numeric(values: Sequence[object]) -> list[float] | None:
+    out: list[float] = []
+    for value in values:
+        if isinstance(value, bool):
+            return None
+        if isinstance(value, int | float):
+            out.append(float(value))
+            continue
+        try:
+            number = float(str(value))
+        except ValueError:
+            return None
+        if not math.isfinite(number):
+            return None
+        out.append(number)
+    return out
+
+
+@check(
+    "DATA-005",
+    Family.DATA,
+    "Population shift between training and test data",
+    Breaks.WARNING,
+    "Evidence-based principle",
+)
+def population_shift(ctx: Context) -> Finding:
+    """Warn when a shared feature has |SMD| above 0.1 between training and test data."""
+    if not ctx.test_features:
+        return Finding(
+            "DATA-005",
+            Status.NOT_APPLICABLE,
+            "No feature columns shared by training and test files",
+        )
+    smds: dict[str, float] = {}
+    too_many_levels: list[str] = []
+    for name, test_values in ctx.test_features.items():
+        train = [v for v in ctx.manifest.columns[name] if v is not None and v != ""]
+        test = [v for v in test_values if v != ""]
+        if len(train) < 2 or len(test) < 2:
+            continue
+        train_num, test_num = _numeric(train), _numeric(test)
+        if train_num is not None and test_num is not None:
+            smds[name] = numeric_smd(train_num, test_num)
+        else:
+            train_text, test_text = [str(v) for v in train], [str(v) for v in test]
+            if len(set(train_text) | set(test_text)) > MAX_LEVELS:
+                too_many_levels.append(name)
+                continue
+            smds[name] = categorical_smd(train_text, test_text)
+    shifted = {k: v for k, v in smds.items() if abs(v) > SMD_WARNING}
+    details = {
+        "smd": smds,
+        "threshold": SMD_WARNING,
+        "shifted": sorted(shifted),
+        "skipped_high_cardinality": too_many_levels,
+    }
+    if shifted:
+        listed = ", ".join(f"{k} ({v:+.2f})" for k, v in sorted(shifted.items()))
+        return Finding(
+            "DATA-005", Status.WARN, f"Population shift above {SMD_WARNING}: {listed}", details
+        )
+    return Finding(
+        "DATA-005", Status.PASS, f"No feature shifts by more than {SMD_WARNING} SMD", details
+    )
+
+
+@check(
+    "DATA-006",
+    Family.DATA,
+    "Prediction files are the ones the models produced",
+    Breaks.OUTSIDE_PLAN,
+    "Traceability; Modification Protocol, update procedures",
+)
+def prediction_provenance(ctx: Context) -> Finding:
+    """Bind each prediction file to its model.
+
+    The candidate file must match ``predictions_sha256`` in its metadata. The
+    previous file must match the predictions recorded when that version was
+    released, if the ledger holds them. The anchor file must match
+    ``anchor_predictions_sha256`` in the plan, if the plan records it.
+    """
+    actual = ctx.prediction_sha256
+    expected: dict[str, str | None] = {
+        "candidate": ctx.meta.predictions_sha256,
+        "previous": ctx.history.released_predictions.get(ctx.meta.previous_version),
+        "anchor": ctx.plan.anchor_predictions_sha256,
+    }
+    mismatched = [
+        role for role, want in expected.items() if want is not None and actual[role] != want
+    ]
+    unchecked = [role for role, want in expected.items() if want is None]
+    details = {"expected": expected, "actual": actual, "not_bound": unchecked}
+    if mismatched:
+        return Finding(
+            "DATA-006",
+            Status.FAIL,
+            "Prediction file(s) differ from the recorded model output: " + ", ".join(mismatched),
+            details,
+        )
+    text = "Prediction files match the recorded model outputs"
+    if unchecked:
+        text += f" ({', '.join(unchecked)} not yet bound)"
+    return Finding("DATA-006", Status.PASS, text, details)