annotide-training 0.1.0__py3-none-any.whl

annotide_training/pipeline.py

@@ -0,0 +1,274 @@
+"""prepare → split → train → evaluate → [quantize → evaluate] → register (ML-9, EXP-8).
+
+Each registered version names how it came to be (`derivation`): `trained`,
+or `distilled` from a teacher version when the run says the snapshot was
+pre-labelled by one, and `quantized` for the int8 copy, whose parent is the
+version this run just registered. The UI draws that as the model's family.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import platform
+import random
+import tempfile
+import uuid
+from collections.abc import Mapping, Sequence
+from dataclasses import dataclass
+from datetime import UTC, datetime
+from pathlib import Path
+from typing import Any
+
+from annotide import Client
+
+from annotide_training import __version__
+from annotide_training.dataset import DatasetError, SplitConfig, SplitName, load_export
+from annotide_training.evaluate import evaluate
+from annotide_training.tracking import MlflowSettings, log_run
+from annotide_training.trainers import (
+    QUANTIZE_DTYPES,
+    Quantizer,
+    Record,
+    TrainedModel,
+    Trainer,
+)
+from annotide_training.webhook import RetrainRequest
+
+log = logging.getLogger("annotide_training")
+
+
+@dataclass(frozen=True, slots=True)
+class RunResult:
+    run_id: str
+    artifact_path: Path
+    metrics: dict[str, Any]
+    #: The registered version, or `None` for a `register=False` (dry) run.
+    version: dict[str, Any] | None
+    #: The lower-precision copy when the run was asked to `quantize`.
+    quantized: QuantizedResult | None = None
+
+
+@dataclass(frozen=True, slots=True)
+class QuantizedResult:
+    artifact_path: Path
+    metrics: dict[str, Any]
+    version: dict[str, Any] | None
+
+
+def run_pipeline(
+    request: RetrainRequest,
+    client: Client,
+    trainer: Trainer,
+    *,
+    out_dir: Path,
+    model_id: str | None = None,
+    params: Mapping[str, Any] | None = None,
+    split: SplitConfig | None = None,
+    register: bool = True,
+    job_timeout: float = 600.0,
+    mlflow: MlflowSettings | None = None,
+    quantize: str | None = None,
+    teacher_version_id: str | None = None,
+) -> RunResult:
+    """Train on the snapshot the request names and register the result.
+
+    `model_id` is the model to add a version to when the event did not name
+    one. With `register=False` everything runs except the registration, so a
+    trainer can be tried against real data without touching the registry.
+    With `mlflow`, the run is also recorded there (API-6) before the version
+    is registered, and `training_run["mlflow"]` names it.
+
+    `quantize="int8"` also stores the trained model at that precision (the
+    trainer must implement `Quantizer`), scores it on the same held-out
+    split and registers it as a `quantized` child of the version trained
+    here. `teacher_version_id` registers the trained version as `distilled`
+    from that version: the model whose pre-labels, corrected by people, are
+    the snapshot this run trained on.
+    """
+    target_model = request.model_id or model_id
+    if register and not target_model:
+        raise ValueError("no model to register a version for: the event names none")
+    quantizer: Quantizer | None = None
+    if quantize is not None:
+        if quantize not in QUANTIZE_DTYPES:
+            raise ValueError(f"cannot quantize to {quantize!r}: use one of {QUANTIZE_DTYPES}")
+        if not isinstance(trainer, Quantizer):
+            raise ValueError(f"trainer {trainer.name} cannot quantize (no quantize method)")
+        quantizer = trainer
+    run_params = dict(params or {})
+    run_id = str(uuid.uuid4())
+    started_at = datetime.now(UTC)
+
+    # prepare: the snapshot row first, so a stale or forged digest fails before
+    # an export is queued.
+    snapshot = client.get_snapshot(request.project_id, request.snapshot_id)
+    if snapshot.get("digest") != request.snapshot_digest:
+        raise DatasetError(
+            f"snapshot {request.snapshot_id} has digest {snapshot.get('digest')}, "
+            f"the request says {request.snapshot_digest}"
+        )
+    export_job = client.create_export(
+        request.project_id, "native", snapshot_id=request.snapshot_id
+    )["id"]
+    client.wait_for_job(export_job, timeout=job_timeout)
+    with tempfile.TemporaryDirectory() as tmp:
+        archive = client.download_export(export_job, Path(tmp) / "export.zip").read_bytes()
+
+    # split: the platform's partition when the snapshot has one (EXP-3).
+    dataset = load_export(
+        archive,
+        snapshot_id=request.snapshot_id,
+        snapshot_digest=request.snapshot_digest,
+        split=split,
+    )
+    log.info("prepared run=%s counts=%s source=%s", run_id, dataset.counts, dataset.split_source)
+    if not dataset.records["train"]:
+        raise DatasetError("the train split is empty; nothing to train on")
+
+    # train
+    model = trainer.train(dataset.records["train"], dataset.records["val"], run_params)
+
+    # evaluate: on test, or val when the split left test empty.
+    held_out: SplitName = "test" if dataset.records["test"] else "val"
+    metrics = _metrics(trainer, model, dataset.records[held_out], held_out)
+    finished_at = datetime.now(UTC)
+
+    run_dir = out_dir / run_id
+    artifact_path = _write(model, run_dir)
+    training_run = {
+        "id": run_id,
+        "pipeline": f"annotide-training {__version__}",
+        "trainer": trainer.name,
+        "params": run_params,
+        "started_at": started_at.isoformat(),
+        "finished_at": finished_at.isoformat(),
+        "export_job_id": export_job,
+        "split_source": dataset.split_source,
+        "split_counts": dataset.counts,
+        "classes": model.classes,
+        "artifact": str(artifact_path),
+        "info": model.info,
+        "delivery_id": request.delivery_id,
+        "note": request.note,
+    }
+    if teacher_version_id is not None:
+        training_run["teacher_version_id"] = teacher_version_id
+    if mlflow is not None:
+        training_run["mlflow"] = log_run(
+            mlflow,
+            project_id=request.project_id,
+            snapshot_id=request.snapshot_id,
+            snapshot_digest=request.snapshot_digest,
+            run_name=f"train {trainer.name} {run_id[:8]}",
+            params=run_params,
+            metrics=metrics,
+            run_dir=run_dir,
+        )
+    (run_dir / "run.json").write_text(
+        json.dumps({"training_run": training_run, "metrics": metrics}, indent=2, sort_keys=True)
+    )
+
+    version: dict[str, Any] | None = None
+    if register and target_model:
+        # register: the platform re-checks the digest against the row (409).
+        registered = client.create_model_version(
+            target_model,
+            {
+                "class_mapping": {},
+                "snapshot_id": request.snapshot_id,
+                "snapshot_digest": request.snapshot_digest,
+                "training_run": training_run,
+                "metrics": metrics,
+                "parent_version_id": teacher_version_id,
+                "derivation": "distilled" if teacher_version_id else "trained",
+            },
+        )
+        version = dict(registered)
+        log.info("registered run=%s model=%s version=%s", run_id, target_model, version["version"])
+
+    quantized: QuantizedResult | None = None
+    if quantizer is not None and quantize is not None:
+        # Calibrate on a fixed-seed sample of train, not its first rows.
+        calibration = list(dataset.records["train"])
+        random.Random(0).shuffle(calibration)
+        small = quantizer.quantize(model, calibration, quantize)
+        small_metrics = _metrics(trainer, small, dataset.records[held_out], held_out)
+        small_dir = run_dir / quantize
+        small_path = _write(small, small_dir)
+        small_run = {
+            **training_run,
+            "quantized_from": str(artifact_path),
+            "artifact": str(small_path),
+            "info": small.info,
+            "finished_at": datetime.now(UTC).isoformat(),
+        }
+        small_run.pop("mlflow", None)
+        small_run.pop("teacher_version_id", None)
+        if mlflow is not None:
+            small_run["mlflow"] = log_run(
+                mlflow,
+                project_id=request.project_id,
+                snapshot_id=request.snapshot_id,
+                snapshot_digest=request.snapshot_digest,
+                run_name=f"quantize {quantize} {trainer.name} {run_id[:8]}",
+                params={**run_params, "quantize": quantize},
+                metrics=small_metrics,
+                run_dir=small_dir,
+            )
+        (small_dir / "run.json").write_text(
+            json.dumps(
+                {"training_run": small_run, "metrics": small_metrics}, indent=2, sort_keys=True
+            )
+        )
+        small_version: dict[str, Any] | None = None
+        if version is not None and target_model:
+            small_version = dict(
+                client.create_model_version(
+                    target_model,
+                    {
+                        "class_mapping": {},
+                        "snapshot_id": request.snapshot_id,
+                        "snapshot_digest": request.snapshot_digest,
+                        "training_run": small_run,
+                        "metrics": small_metrics,
+                        "parent_version_id": version["id"],
+                        "derivation": "quantized",
+                    },
+                )
+            )
+            log.info(
+                "registered %s copy run=%s version=%s", quantize, run_id, small_version["version"]
+            )
+        quantized = QuantizedResult(
+            artifact_path=small_path, metrics=small_metrics, version=small_version
+        )
+    return RunResult(
+        run_id=run_id,
+        artifact_path=artifact_path,
+        metrics=metrics,
+        version=version,
+        quantized=quantized,
+    )
+
+
+def _metrics(
+    trainer: Trainer, model: TrainedModel, records: Sequence[Record], split: SplitName
+) -> dict[str, Any]:
+    """The held-out scores plus what the UI compares versions on (size, dtype)."""
+    metrics: dict[str, Any] = {"split": split, **evaluate(trainer, model, records)}
+    metrics["size_bytes"] = len(model.artifact)
+    metrics["latency_device"] = f"{platform.system()} {platform.machine()}".strip()
+    if "dtype" in model.info:
+        metrics["dtype"] = model.info["dtype"]
+    return metrics
+
+
+def _write(model: TrainedModel, run_dir: Path) -> Path:
+    """The artifact and its sibling files, never outside `run_dir`."""
+    run_dir.mkdir(parents=True, exist_ok=True)
+    artifact_path = run_dir / model.filename
+    artifact_path.write_bytes(model.artifact)
+    for name, data in model.extra_files.items():
+        (run_dir / Path(name).name).write_bytes(data)
+    return artifact_path

annotide_training/tracking.py

@@ -0,0 +1,110 @@
+"""Optional MLflow tracking for a training run (API-6, EXP-8).
+
+With `--mlflow-experiment`, the pipeline also records its run in the
+customer's MLflow — a local server, Databricks or Azure ML, wherever
+`MLFLOW_TRACKING_URI` (or `--mlflow-uri`) points and however that
+environment authenticates — with the snapshot as the run's dataset input in
+exactly the shape the platform publishes (`source_type`
+`annotation-snapshot`) and the `annotation.snapshot_*` tags. The platform's
+`POST /models/{id}/versions/import` reads the lineage back from either, so a
+version imported from this run, or from the registered model it creates, is
+linked to its snapshot without a separate step.
+
+Needs the `mlflow` extra (`mlflow-skinny`); imported only when used.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+SNAPSHOT_SOURCE_TYPE = "annotation-snapshot"
+
+
+@dataclass(frozen=True, slots=True)
+class MlflowSettings:
+    experiment: str
+    tracking_uri: str | None = None
+    #: Register the run's artifacts as a new version of this registered model.
+    registered_model: str | None = None
+
+
+def _numeric(metrics: dict[str, Any], prefix: str = "") -> dict[str, float]:
+    """MLflow takes numbers only; nested dicts are flattened with dots."""
+    flat: dict[str, float] = {}
+    for key, value in metrics.items():
+        name = f"{prefix}{key}"
+        if isinstance(value, bool):
+            continue
+        if isinstance(value, int | float):
+            flat[name] = float(value)
+        elif isinstance(value, dict):
+            flat.update(_numeric(value, f"{name}."))
+    return flat
+
+
+def log_run(
+    settings: MlflowSettings,
+    *,
+    project_id: str,
+    snapshot_id: str,
+    snapshot_digest: str,
+    run_name: str,
+    params: dict[str, Any],
+    metrics: dict[str, Any],
+    run_dir: Path,
+) -> dict[str, Any]:
+    """Record the finished run in MLflow; what to keep in `training_run["mlflow"]`."""
+    os.environ.setdefault("MLFLOW_DISABLE_AGENT_HINT", "1")
+    try:
+        import mlflow
+        from mlflow.entities import Dataset, DatasetInput, InputTag
+        from mlflow.tracking import MlflowClient
+    except ImportError as exc:  # pragma: no cover - depends on the install
+        raise RuntimeError("--mlflow-* needs the `mlflow` extra (mlflow-skinny)") from exc
+
+    if settings.tracking_uri:
+        mlflow.set_tracking_uri(settings.tracking_uri)
+    experiment = mlflow.set_experiment(settings.experiment)
+    with mlflow.start_run(run_name=run_name) as run:
+        run_id = run.info.run_id
+        mlflow.set_tags(
+            {
+                "annotation.project_id": project_id,
+                "annotation.snapshot_id": snapshot_id,
+                "annotation.snapshot_digest": snapshot_digest,
+            }
+        )
+        if params:
+            mlflow.log_params({key: str(value) for key, value in params.items()})
+        numbers = _numeric(metrics)
+        if numbers:
+            mlflow.log_metrics(numbers)
+        dataset = Dataset(
+            name=f"snapshot-{snapshot_id[:8]}",
+            digest=snapshot_digest[:16],
+            source_type=SNAPSHOT_SOURCE_TYPE,
+            source=json.dumps(
+                {"snapshot_id": snapshot_id, "project_id": project_id, "digest": snapshot_digest},
+                sort_keys=True,
+            ),
+        )
+        MlflowClient().log_inputs(
+            run_id,
+            datasets=[DatasetInput(dataset, tags=[InputTag("mlflow.data.context", "training")])],
+        )
+        mlflow.log_artifacts(str(run_dir), artifact_path="model")
+
+    record: dict[str, Any] = {
+        "run_id": run_id,
+        "experiment_id": experiment.experiment_id,
+        "tracking_uri": mlflow.get_tracking_uri(),
+    }
+    if settings.registered_model:
+        registered = mlflow.register_model(f"runs:/{run_id}/model", settings.registered_model)
+        record["registered_model"] = settings.registered_model
+        record["model_version"] = str(registered.version)
+    return record

annotide_training/trainers.py

@@ -0,0 +1,213 @@
+"""The pluggable part: a `Trainer` turns records into a model and predicts with it.
+
+A real trainer (a detector fine-tune exported to ONNX for
+`model-service`'s `onnx` backend, say) implements the same two methods and
+is loaded by `--trainer package.module:ClassName`; its framework is its own
+dependency. `BaselineTrainer` needs nothing: it learns where each class
+usually sits in the frame, which is enough to exercise every stage of the
+pipeline end to end and gives a floor any real model has to beat.
+"""
+
+from __future__ import annotations
+
+import importlib
+import json
+from collections.abc import Mapping, Sequence
+from dataclasses import dataclass, field
+from typing import Any, Protocol, runtime_checkable
+
+Record = Mapping[str, Any]
+Box = tuple[float, float, float, float]  # x1, y1, x2, y2 in pixels
+
+
+@dataclass(frozen=True, slots=True)
+class Prediction:
+    class_: str
+    bbox: Box
+    confidence: float
+
+
+@dataclass(slots=True)
+class TrainedModel:
+    """What a trainer hands back: an artifact to store and what it can emit."""
+
+    artifact: bytes
+    filename: str
+    classes: list[str]
+    info: dict[str, Any] = field(default_factory=dict)
+    #: Files written next to the artifact, by name (an ONNX model's `.names`).
+    extra_files: dict[str, bytes] = field(default_factory=dict)
+
+
+@runtime_checkable
+class Trainer(Protocol):
+    name: str
+
+    def train(
+        self, train: Sequence[Record], val: Sequence[Record], params: Mapping[str, Any]
+    ) -> TrainedModel: ...
+
+    def predict(self, model: TrainedModel, record: Record) -> list[Prediction]: ...
+
+
+#: What `--quantize` accepts. int8 is the one every CPU runtime speeds up.
+QUANTIZE_DTYPES = ("int8",)
+
+
+@runtime_checkable
+class Quantizer(Protocol):
+    """Optional: a trainer that can store a trained model at lower precision.
+
+    `calibration` is a sample of training records for static quantization
+    (activation ranges); the result must load and predict through the same
+    trainer's `predict`, so the pipeline scores it exactly like the original.
+    """
+
+    def quantize(
+        self, model: TrainedModel, calibration: Sequence[Record], dtype: str
+    ) -> TrainedModel: ...
+
+
+def record_boxes(record: Record) -> list[tuple[str, Box]]:
+    """The `bbox` shapes of a native export record, as (class, x1 y1 x2 y2)."""
+    boxes: list[tuple[str, Box]] = []
+    for shape in record.get("shapes", []):
+        bbox = shape.get("bbox")
+        if shape.get("type") == "bbox" and isinstance(bbox, list) and len(bbox) == 4:
+            x1, y1, x2, y2 = (float(v) for v in bbox)
+            boxes.append((str(shape.get("class")), (x1, y1, x2, y2)))
+    return boxes
+
+
+class BaselineTrainer:
+    """Per class: how often it appears and its mean normalised box.
+
+    Predicts, for every class seen in at least `min_frequency` of the
+    training images, one box at that mean position with the frequency as
+    its confidence. Deterministic, dependency-free, and honest about being
+    a baseline.
+    """
+
+    name = "baseline-class-prior"
+
+    def train(
+        self, train: Sequence[Record], val: Sequence[Record], params: Mapping[str, Any]
+    ) -> TrainedModel:
+        min_frequency = float(params.get("min_frequency", 0.0))
+        images = 0
+        present: dict[str, int] = {}
+        sums: dict[str, list[float]] = {}
+        counts: dict[str, int] = {}
+        for record in train:
+            width = float(record.get("width") or 0)
+            height = float(record.get("height") or 0)
+            if width <= 0 or height <= 0:
+                continue
+            images += 1
+            seen: set[str] = set()
+            for class_name, (x1, y1, x2, y2) in record_boxes(record):
+                acc = sums.setdefault(class_name, [0.0, 0.0, 0.0, 0.0])
+                for i, value in enumerate((x1 / width, y1 / height, x2 / width, y2 / height)):
+                    acc[i] += value
+                counts[class_name] = counts.get(class_name, 0) + 1
+                seen.add(class_name)
+            for class_name in seen:
+                present[class_name] = present.get(class_name, 0) + 1
+
+        priors: dict[str, dict[str, Any]] = {
+            name: {
+                "frequency": round(present.get(name, 0) / images, 6) if images else 0.0,
+                "box": [round(v / counts[name], 6) for v in sums[name]],
+            }
+            for name in sorted(sums)
+        }
+        emitted = sorted(n for n, p in priors.items() if p["frequency"] >= min_frequency)
+        body = {
+            "trainer": self.name,
+            "images": images,
+            "min_frequency": min_frequency,
+            "priors": {n: priors[n] for n in emitted},
+        }
+        return TrainedModel(
+            artifact=json.dumps(body, indent=2, sort_keys=True).encode(),
+            filename="baseline.json",
+            classes=emitted,
+            info={"train_images": images, "val_images": len(val), "dtype": "fp64"},
+        )
+
+    def quantize(
+        self, model: TrainedModel, calibration: Sequence[Record], dtype: str
+    ) -> TrainedModel:
+        """Each prior's box and frequency as an 8-bit fraction (k / 255).
+
+        The baseline's floats are already tiny; this exists so the
+        `--quantize` path runs end to end without the torch extra.
+        """
+        if dtype != "int8":
+            raise ValueError(f"{self.name} quantizes to int8 only, not {dtype!r}")
+        body = json.loads(model.artifact)
+        for prior in body["priors"].values():
+            prior["box"] = [_to_uint8(v) for v in prior["box"]]
+            prior["frequency"] = _to_uint8(prior["frequency"])
+        body["dtype"] = "int8"
+        return TrainedModel(
+            artifact=json.dumps(body, sort_keys=True, separators=(",", ":")).encode(),
+            filename=model.filename,
+            classes=list(model.classes),
+            info={**model.info, "dtype": "int8"},
+            extra_files=dict(model.extra_files),
+        )
+
+    def predict(self, model: TrainedModel, record: Record) -> list[Prediction]:
+        body = json.loads(model.artifact)
+        scale = 255.0 if body.get("dtype") == "int8" else 1.0
+        width = float(record.get("width") or 0)
+        height = float(record.get("height") or 0)
+        predictions: list[Prediction] = []
+        for class_name, prior in body["priors"].items():
+            nx1, ny1, nx2, ny2 = (v / scale for v in prior["box"])
+            predictions.append(
+                Prediction(
+                    class_=class_name,
+                    bbox=(nx1 * width, ny1 * height, nx2 * width, ny2 * height),
+                    confidence=float(prior["frequency"]) / scale,
+                )
+            )
+        return predictions
+
+
+def _to_uint8(value: float) -> int:
+    return max(0, min(255, round(value * 255)))
+
+
+# Built-ins by name. `fasterrcnn` needs the `torch` extra, so it is imported
+# only when asked for.
+BUILTIN_TRAINERS: dict[str, str] = {
+    "baseline": "annotide_training.trainers:BaselineTrainer",
+    "fasterrcnn": "annotide_training.detector:FasterRCNNTrainer",
+}
+_TORCH_EXTRA = {"torch", "torchvision", "onnx", "onnxruntime", "numpy", "PIL"}
+
+
+def load_trainer(spec: str) -> Trainer:
+    """`baseline`, `fasterrcnn`, or `package.module:ClassName` for your own."""
+    builtin = BUILTIN_TRAINERS.get(spec)
+    try:
+        return _load(builtin or spec)
+    except ModuleNotFoundError as exc:
+        if builtin and exc.name in _TORCH_EXTRA:
+            raise ValueError(
+                f"trainer {spec!r} needs the torch extra: pip install 'annotide-training[torch]'"
+            ) from exc
+        raise
+
+
+def _load(spec: str) -> Trainer:
+    module_name, sep, attr = spec.partition(":")
+    if not sep or not module_name or not attr:
+        raise ValueError(f"trainer {spec!r}: use a built-in name or 'module:ClassName'")
+    factory = getattr(importlib.import_module(module_name), attr)
+    trainer = factory()
+    if not isinstance(trainer, Trainer):
+        raise TypeError(f"{spec} does not implement Trainer (name, train, predict)")
+    return trainer

annotide_training/webhook.py

@@ -0,0 +1,94 @@
+"""Verify and parse `retrain.requested` deliveries (CONTRACTS.md, webhooks).
+
+Mirrors `backend/app/services/webhooks.py::verify`: the header is
+`t=<unix seconds>,v1=<hex HMAC-SHA256 of "{t}.{body}">`, stale timestamps
+are rejected and the comparison is constant-time.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import hmac
+import json
+import time
+from dataclasses import dataclass
+from typing import Any
+
+SIGNATURE_HEADER = "X-Annotation-Signature"
+EVENT_HEADER = "X-Annotation-Event"
+DELIVERY_HEADER = "X-Annotation-Delivery"
+RETRAIN_EVENT = "retrain.requested"
+TOLERANCE_SECONDS = 300
+
+
+class WebhookError(ValueError):
+    """The delivery is not one this pipeline acts on."""
+
+
+def sign(secret: str, timestamp: int, body: bytes) -> str:
+    mac = hmac.new(secret.encode(), f"{timestamp}.".encode() + body, hashlib.sha256)
+    return f"t={timestamp},v1={mac.hexdigest()}"
+
+
+def verify(
+    secret: str,
+    header: str,
+    body: bytes,
+    *,
+    now: float | None = None,
+    tolerance_seconds: int = TOLERANCE_SECONDS,
+) -> bool:
+    parts = dict(part.split("=", 1) for part in header.split(",") if "=" in part)
+    try:
+        timestamp = int(parts["t"])
+    except (KeyError, ValueError):
+        return False
+    current = int(time.time() if now is None else now)
+    if abs(current - timestamp) > tolerance_seconds:
+        return False
+    expected = sign(secret, timestamp, body).split("v1=", 1)[1]
+    return hmac.compare_digest(expected, parts.get("v1", ""))
+
+
+@dataclass(frozen=True, slots=True)
+class RetrainRequest:
+    """What one `retrain.requested` event asks for."""
+
+    project_id: str
+    snapshot_id: str
+    snapshot_digest: str
+    model_id: str | None
+    note: str | None
+    delivery_id: str | None
+
+
+def parse_retrain(body: bytes) -> RetrainRequest:
+    """Parse a verified delivery body; `WebhookError` unless it names a snapshot."""
+    try:
+        payload: Any = json.loads(body)
+    except json.JSONDecodeError as exc:
+        raise WebhookError("body is not JSON") from exc
+    if not isinstance(payload, dict) or payload.get("event") != RETRAIN_EVENT:
+        raise WebhookError(f"not a {RETRAIN_EVENT} event")
+    data = payload.get("data")
+    if not isinstance(data, dict):
+        raise WebhookError("event has no data")
+    snapshot = data.get("snapshot")
+    if not isinstance(snapshot, dict) or not snapshot.get("id") or not snapshot.get("digest"):
+        # The platform allows a retrain request without a snapshot; there is
+        # nothing to train on until someone freezes one.
+        raise WebhookError("retrain.requested names no snapshot")
+    project_id = data.get("project_id") or payload.get("project_id")
+    if not project_id:
+        raise WebhookError("event has no project_id")
+    model_id = data.get("model_id")
+    note = data.get("note")
+    delivery = payload.get("delivery_id")
+    return RetrainRequest(
+        project_id=str(project_id),
+        snapshot_id=str(snapshot["id"]),
+        snapshot_digest=str(snapshot["digest"]),
+        model_id=str(model_id) if model_id else None,
+        note=str(note) if note else None,
+        delivery_id=str(delivery) if delivery else None,
+    )