flashpdm 0.1.0__py3-none-any.whl

flashpdm/__init__.py

@@ -0,0 +1,6 @@
+"""Python access to the Flashmind forecasting API."""
+from .client import AsyncClient, Client
+from .types import APIError, Forecast, ForecastResponse
+
+__version__ = "0.1.0"
+__all__ = ["Client", "AsyncClient", "APIError", "Forecast", "ForecastResponse"]

flashpdm/arrays.py

@@ -0,0 +1,56 @@
+"""Optional NumPy adapter over the same public forecast API."""
+import numpy as np
+
+
+def series_from_arrays(context, horizon, past_covariates=None, future_covariates=None, *, numpy_values=False):
+    x = np.asarray(context, dtype=np.float32)
+    if x.ndim == 1:
+        x = x[None, None]
+    elif x.ndim == 2:
+        x = x[None]
+    if x.ndim != 3:
+        raise ValueError("context must have shape (N,V,T), (V,T), or (T,)")
+    n, v, full_t = x.shape
+    t = min(full_t, 16336)
+    def covariates(raw, future=False):
+        if raw is None:
+            return None
+        a = np.asarray(raw, dtype=np.float32)
+        if a.ndim == 2 and n == 1:
+            a = a[None]
+        if a.ndim != 3 or a.shape[0] != n or a.shape[2] != full_t + (horizon if future else 0):
+            raise ValueError("Covariate batch/time axes must match the context")
+        return a
+    past = covariates(past_covariates)
+    known = covariates(future_covariates, future=True)
+    def numbers(row):
+        if numpy_values:
+            return np.ascontiguousarray(row)
+        # Nine significant decimal digits preserve every float32 exactly and
+        # avoid sending a float64-length decimal representation of each value.
+        return [None if np.isnan(value) else float(format(float(value), ".9g")) for value in row]
+    rows = []
+    for b in range(n):
+        group = f"window-{b}"
+        for j in range(v):
+            rows.append({"id": f"{b}:target:{j}", "group": group, "values": numbers(x[b, j, -t:])})
+        if past is not None:
+            for j in range(past.shape[1]):
+                rows.append({"id": f"{b}:past:{j}", "group": group, "role": "past_covariate", "values": numbers(past[b, j, -t:])})
+        if known is not None:
+            for j in range(known.shape[1]):
+                rows.append({"id": f"{b}:known:{j}", "group": group, "role": "future_covariate",
+                             "values": numbers(known[b, j, full_t-t:full_t]), "future_values": numbers(known[b, j, full_t:])})
+    return rows, n, v
+
+
+def forecast_arrays(client, context, horizon, *, past_covariates=None, future_covariates=None,
+                    quantiles=None, postprocess=True, model_revision=None):
+    levels = quantiles if quantiles is not None else [.01] + [i / 20 for i in range(1, 20)] + [.99]
+    rows, n, v = series_from_arrays(context, horizon, past_covariates, future_covariates, numpy_values=True)
+    result = client._forecast_array_rows(rows, horizon, quantiles=levels, postprocess=postprocess, model_revision=model_revision)
+    values = np.empty((n, v, horizon, len(levels)), dtype=np.float32)
+    for b in range(n):
+        for j in range(v):
+            values[b, j] = np.asarray(result[f"{b}:target:{j}"].quantile_values, dtype=np.float32).T
+    return values

flashpdm/client.py

@@ -0,0 +1,230 @@
+"""Sync and async HTTP clients. Forecast requests are never retried implicitly."""
+import json
+import math
+import os
+from urllib.parse import urlsplit
+
+import httpx
+
+from .types import APIError, Forecast, ForecastResponse
+
+MAX_RESPONSE_BYTES = 32 * 1024 * 1024
+
+
+def _body(series, horizon, model, *, quantiles=None, postprocess=None, model_revision=None, array_values=False):
+    if model != "pdm-nano":
+        raise ValueError("Only pdm-nano is supported")
+    if isinstance(horizon, bool) or not isinstance(horizon, int) or not 1 <= horizon <= 16384:
+        raise ValueError("horizon must be an integer in [1, 16384]")
+    if isinstance(series, dict):
+        series = [{"id": k, "values": v} for k, v in series.items()]
+    if not isinstance(series, (list, tuple)) or not 1 <= len(series) <= 512:
+        raise ValueError("series must contain 1 to 512 named series; account limits are enforced by the gateway")
+    def values(raw):
+        if array_values:
+            import numpy as np
+            if not isinstance(raw, np.ndarray) or raw.dtype != np.float32 or raw.ndim != 1 or np.isinf(raw).any():
+                raise ValueError("Array observations must be float32 vectors without infinities")
+            return np.ascontiguousarray(raw)
+        clean = []
+        for value in raw:
+            if value is None:
+                clean.append(None)
+                continue
+            if isinstance(value, (bool, str, bytes)):
+                raise ValueError("Observations must be numbers or None")
+            try:
+                number = float(value)
+            except (TypeError, ValueError, OverflowError) as exc:
+                raise ValueError("Observations must be numbers or None") from exc
+            if math.isinf(number):
+                raise ValueError("Infinite observations are invalid")
+            clean.append(None if math.isnan(number) else number)
+        return clean
+    result, seen = [], set()
+    for row in series:
+        if not isinstance(row, dict) or set(row) - {"id", "values", "group", "role", "future_values"} or not {"id", "values"} <= set(row):
+            raise ValueError("Each series must contain id and values")
+        name = row["id"]
+        if not isinstance(name, str) or not 1 <= len(name) <= 100 or name in seen:
+            raise ValueError("Series IDs must be unique strings of 1 to 100 characters")
+        clean = values(row["values"])
+        if not 2 <= len(clean) <= 16336:
+            raise ValueError("Each series requires 2 to 16336 observations")
+        item = {"id": name, "values": clean}
+        for field in ("group", "role"):
+            if field in row:
+                item[field] = row[field]
+        if "future_values" in row:
+            item["future_values"] = values(row["future_values"])
+        seen.add(name)
+        result.append(item)
+    body = {"model": model, "series": result, "horizon": horizon}
+    if quantiles is not None:
+        if not 1 <= len(quantiles) <= 21 or any(isinstance(q, bool) or not isinstance(q, (int, float)) or not .01 <= q <= .99 for q in quantiles) or any(b <= a for a, b in zip(quantiles, quantiles[1:])):
+            raise ValueError("quantiles must be increasing probabilities in [0.01, 0.99]")
+        body["quantiles"] = list(quantiles)
+    if postprocess is not None:
+        if not isinstance(postprocess, bool):
+            raise ValueError("postprocess must be boolean")
+        body["postprocess"] = postprocess
+    if model_revision is not None:
+        if not isinstance(model_revision, str) or len(model_revision) != 64 or any(c not in "0123456789abcdef" for c in model_revision):
+            raise ValueError("model_revision must be a SHA-256 digest")
+        body["model_revision"] = model_revision
+    return body
+
+
+def _decode(response, content, payload):
+    request_id = response.headers.get("x-request-id")
+    try:
+        data = json.loads(content)
+    except (ValueError, UnicodeError) as exc:
+        raise APIError("Invalid API response", status_code=response.status_code,
+                       code="invalid_response", request_id=request_id) from exc
+    if response.status_code != 200:
+        error = data.get("error", {}) if isinstance(data, dict) else {}
+        if not isinstance(error, dict):
+            error = {}
+        raise APIError(error.get("message", "Forecast request failed"), status_code=response.status_code,
+                       code=error.get("code"), request_id=error.get("requestId", request_id),
+                       retry_after=error.get("retryAfter", response.headers.get("retry-after")))
+    try:
+        if set(data) - {"model", "forecasts", "quantiles", "model_revision"} or data["model"] != payload["model"]:
+            raise ValueError("Unexpected model response")
+        by_id = {}
+        expected = {r["id"] for r in payload["series"] if r.get("role", "target") == "target"}
+        if payload.get("model_revision") and data.get("model_revision") != payload["model_revision"]:
+            raise ValueError("Unexpected model revision")
+        if data.get("quantiles") != payload.get("quantiles"):
+            raise ValueError("Unexpected quantile grid")
+        horizon = payload["horizon"]
+        for row in data["forecasts"]:
+            if set(row) - {"id", "values", "lower", "upper", "quantile_values"} or row["id"] not in expected or row["id"] in by_id:
+                raise ValueError("Unexpected forecast series")
+            for field in ("values", "lower", "upper"):
+                if field in row:
+                    values = row[field]
+                    if not isinstance(values, list) or len(values) != horizon or any(
+                        isinstance(v, bool) or not isinstance(v, (int, float)) or not math.isfinite(v) for v in values):
+                        raise ValueError("Invalid forecast values")
+            if ("lower" in row) != ("upper" in row):
+                raise ValueError("Incomplete forecast bounds")
+            if "lower" in row and any(lo > mid or mid > hi for lo, mid, hi in zip(row["lower"], row["values"], row["upper"])):
+                raise ValueError("Forecast bounds cross")
+            if payload.get("quantiles"):
+                bands = row.get("quantile_values")
+                if not isinstance(bands, list) or len(bands) != len(payload["quantiles"]) or any(
+                    not isinstance(band, list) or len(band) != horizon or any(isinstance(v, bool) or not isinstance(v, (int, float)) or not math.isfinite(v) for v in band) for band in bands):
+                    raise ValueError("Invalid quantile forecasts")
+                if any(any(v < before[j] for j, v in enumerate(after)) for before, after in zip(bands, bands[1:])):
+                    raise ValueError("Quantile forecasts cross")
+            elif "quantile_values" in row:
+                raise ValueError("Unexpected quantile forecasts")
+            by_id[row["id"]] = Forecast(**row)
+        if set(by_id) != expected:
+            raise ValueError("Missing forecast series")
+        return ForecastResponse(data["model"], [by_id[r["id"]] for r in payload["series"] if r.get("role", "target") == "target"], request_id, data.get("quantiles"), data.get("model_revision"))
+    except (KeyError, TypeError, ValueError, OverflowError) as exc:
+        raise APIError("Invalid forecast response", status_code=200, code="invalid_response", request_id=request_id) from exc
+
+
+class _Base:
+    def __init__(self, api_key=None, *, base_url="https://www.flashmind.com", timeout=130., transport=None):
+        url = urlsplit(base_url)
+        local = url.hostname in {"localhost", "127.0.0.1", "::1"}
+        if url.username or url.password or url.query or url.fragment or not url.netloc or (
+            url.scheme != "https" and not (local and url.scheme == "http")):
+            raise ValueError("base_url must be HTTPS (loopback HTTP is allowed for development)")
+        self.api_key = api_key if api_key is not None else os.environ.get("FLASHMIND_API_KEY")
+        if self.api_key is not None and (not isinstance(self.api_key, str) or not self.api_key.strip()):
+            raise ValueError("api_key cannot be empty")
+        self.endpoint = base_url.rstrip("/") + ("/v1/forecast" if self.api_key else "/api/public/forecast")
+        self.headers = {"Accept": "application/json", "User-Agent": "flashpdm-python/0.1.0"}
+        if self.api_key:
+            self.headers["Authorization"] = f"Bearer {self.api_key}"
+        self.timeout, self.transport = timeout, transport
+
+    def _headers(self, idempotency_key):
+        if idempotency_key and not self.api_key:
+            raise ValueError("Idempotency keys require an API key")
+        if idempotency_key is not None and (not isinstance(idempotency_key, str) or not idempotency_key or "\n" in idempotency_key or "\r" in idempotency_key):
+            raise ValueError("Invalid idempotency key")
+        return {**self.headers, **({"Idempotency-Key": idempotency_key} if idempotency_key else {})}
+
+
+class Client(_Base):
+    def __init__(self, *args, **kwargs):
+        super().__init__(*args, **kwargs)
+        self._http = httpx.Client(timeout=self.timeout, transport=self.transport, follow_redirects=False)
+
+    def forecast(self, series, horizon, *, model="pdm-nano", idempotency_key=None, quantiles=None, postprocess=None, model_revision=None):
+        payload = _body(series, horizon, model, quantiles=quantiles, postprocess=postprocess, model_revision=model_revision)
+        return self._request(payload, idempotency_key=idempotency_key)
+
+    def _forecast_array_rows(self, series, horizon, **kwargs):
+        import orjson
+        payload = _body(series, horizon, "pdm-nano", array_values=True, **kwargs)
+        # Native float32 serialization preserves the exact observations and
+        # emits NaN as JSON null without per-value Python formatting.
+        encoded = orjson.dumps(payload, option=orjson.OPT_SERIALIZE_NUMPY)
+        return self._request(payload, encoded=encoded)
+
+    def _request(self, payload, *, idempotency_key=None, encoded=None):
+        headers = self._headers(idempotency_key)
+        if encoded is not None:
+            headers["Content-Type"] = "application/json"
+        body = {"json": payload} if encoded is None else {"content": encoded}
+        try:
+            with self._http.stream("POST", self.endpoint, headers=headers, **body) as response:
+                chunks, size = [], 0
+                for chunk in response.iter_bytes():
+                    size += len(chunk)
+                    if size > MAX_RESPONSE_BYTES:
+                        raise APIError("API response too large", code="invalid_response")
+                    chunks.append(chunk)
+                return _decode(response, b"".join(chunks), payload)
+        except httpx.RequestError as exc:
+            raise APIError("Forecast transport failed; outcome may be unknown. Requests are not automatically retried.", code="transport_error") from exc
+
+    def close(self):
+        self._http.close()
+
+    def forecast_quantiles(self, context, horizon, **kwargs):
+        from .arrays import forecast_arrays
+        return forecast_arrays(self, context, horizon, **kwargs)
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, *_):
+        self.close()
+
+
+class AsyncClient(_Base):
+    def __init__(self, *args, **kwargs):
+        super().__init__(*args, **kwargs)
+        self._http = httpx.AsyncClient(timeout=self.timeout, transport=self.transport, follow_redirects=False)
+
+    async def forecast(self, series, horizon, *, model="pdm-nano", idempotency_key=None, quantiles=None, postprocess=None, model_revision=None):
+        payload = _body(series, horizon, model, quantiles=quantiles, postprocess=postprocess, model_revision=model_revision)
+        try:
+            async with self._http.stream("POST", self.endpoint, headers=self._headers(idempotency_key), json=payload) as response:
+                chunks, size = [], 0
+                async for chunk in response.aiter_bytes():
+                    size += len(chunk)
+                    if size > MAX_RESPONSE_BYTES:
+                        raise APIError("API response too large", code="invalid_response")
+                    chunks.append(chunk)
+                return _decode(response, b"".join(chunks), payload)
+        except httpx.RequestError as exc:
+            raise APIError("Forecast transport failed; outcome may be unknown. Requests are not automatically retried.", code="transport_error") from exc
+
+    async def aclose(self):
+        await self._http.aclose()
+
+    async def __aenter__(self):
+        return self
+
+    async def __aexit__(self, *_):
+        await self.aclose()

flashpdm/gift.py

@@ -0,0 +1,240 @@
+"""GIFT-Eval predictor backed only by the public forecasting HTTP API."""
+from concurrent.futures import FIRST_COMPLETED, ThreadPoolExecutor, wait
+from contextlib import nullcontext
+from pathlib import Path
+import json
+import math
+import hashlib
+import os
+import tempfile
+from threading import Lock
+
+import numpy as np
+
+LEVELS = [.1, .2, .3, .4, .5, .6, .7, .8, .9]
+_DATASET_LOCK = Lock()
+
+
+def load_dataset(name, term):
+    from datasets.utils.tqdm import tqdm as dataset_progress
+    from gift_eval.data import Dataset
+    # Hugging Face uses tqdm.thread_map while loading Arrow shards. Its
+    # temporary lock can be deleted by another concurrent load. Only dataset
+    # construction is serialized; forecasts and metric scoring stay parallel.
+    with _DATASET_LOCK:
+        dataset_progress.set_lock(dataset_progress.get_lock())
+        return Dataset(name=name, term=term, to_univariate=False)
+
+
+def fullstack_projection(bands, context):
+    """Canonical non-negative/count projection using the full observed history.
+
+    bands: (V,H,Q); context: (V,T). No future labels are inspected.
+    """
+    result = np.asarray(bands, dtype=np.float32).copy()
+    for v, history in enumerate(context):
+        observed = np.asarray(history, dtype=np.float64)
+        observed = observed[np.isfinite(observed)]
+        if observed.size and np.all(observed >= 0):
+            result[v] = np.maximum(result[v], 0)
+        if observed.size >= 8 and np.all(observed >= 0) and np.all(observed == np.rint(observed)):
+            result[v] = np.maximum(np.rint(result[v]), 0)
+    return result
+
+
+class PdmPredictor:
+    """GluonTS predictor: target variates stay joint, past covariates stay hidden."""
+    def __init__(self, client, prediction_length, *, model_revision, use_past_covariates=True,
+                 max_series=256, max_cells=131072, max_windows=32, concurrency=4, executor=None, cache_dir=None):
+        self.client = client
+        self.prediction_length = int(prediction_length)
+        self.model_revision = model_revision
+        self.use_past_covariates = use_past_covariates
+        self.max_series, self.max_cells, self.concurrency = max_series, max_cells, concurrency
+        self.max_windows = max_windows
+        self.executor = executor
+        self.cache_dir = Path(cache_dir) if cache_dir is not None else None
+        if self.cache_dir:
+            self.cache_dir.mkdir(parents=True, exist_ok=True)
+
+    def predict(self, inputs):
+        from gluonts.model.forecast import QuantileForecast
+        entries = list(inputs)
+        targets, past = [], []
+        for entry in entries:
+            target = np.asarray(entry["target"], dtype=np.float32)
+            target = target[None] if target.ndim == 1 else target
+            targets.append(target)
+            cov = entry.get("past_feat_dynamic_real") if self.use_past_covariates else None
+            if cov is not None:
+                cov = np.asarray(cov, dtype=np.float32)
+                cov = cov[None] if cov.ndim == 1 else cov
+                cov = cov[:, :target.shape[-1]]
+            past.append(cov)
+        order = sorted(range(len(entries)), key=lambda i: min(targets[i].shape[-1], 16336))
+        packs, pack = [], []
+        for index in order:
+            candidate = pack + [index]
+            width = max(min(targets[i].shape[-1], 16336) for i in candidate)
+            rows = sum(targets[i].shape[0] + (0 if past[i] is None else past[i].shape[0]) for i in candidate)
+            output_cells = sum(targets[i].shape[0] for i in candidate) * self.prediction_length * 12
+            if pack and (len(candidate) > self.max_windows or rows > self.max_series or rows * width > self.max_cells or output_cells > 1_500_000):
+                packs.append(pack)
+                pack = []
+            pack.append(index)
+        if pack:
+            packs.append(pack)
+        outputs = [None] * len(entries)
+        def run(indices):
+            width = max(min(targets[i].shape[-1], 16336) for i in indices)
+            def pad(x):
+                x = x[:, -width:]
+                return np.pad(x, ((0, 0), (width - x.shape[-1], 0)), constant_values=np.nan)
+            context = np.stack([pad(targets[i]) for i in indices])
+            covs = None if past[indices[0]] is None else np.stack([pad(past[i]) for i in indices])
+            path = None
+            if self.cache_dir:
+                digest = hashlib.sha256(f"native-v1:{self.model_revision}:{self.prediction_length}:{LEVELS}".encode())
+                for array in (context, covs):
+                    digest.update(str(None if array is None else array.shape).encode())
+                    if array is not None:
+                        digest.update(array.tobytes())
+                path = self.cache_dir / (digest.hexdigest() + ".npy")
+                if path.exists():
+                    bands = np.load(path, allow_pickle=False)
+                    if bands.shape != (*context.shape[:2], self.prediction_length, len(LEVELS)) or not np.isfinite(bands).all():
+                        raise ValueError(f"Invalid cached forecast: {path}")
+                    return indices, bands
+            # Request raw native quantiles; perform the recorded serving projection
+            # from FULL observed history, including observations before the model crop.
+            bands = self.client.forecast_quantiles(context, self.prediction_length,
+                past_covariates=covs, quantiles=LEVELS, postprocess=False, model_revision=self.model_revision)
+            if path is not None:
+                # Atomic per-request checkpoints retain expensive forecasts if
+                # a later request fails; no partial file can become a cache hit.
+                with tempfile.NamedTemporaryFile(dir=self.cache_dir, suffix=".npy", delete=False) as file:
+                    temporary = file.name
+                    np.save(file, bands, allow_pickle=False)
+                os.replace(temporary, path)
+            return indices, bands
+        # Share a bounded API pool across configurations. When only one large
+        # dataset remains, its windows can use the whole pool instead of being
+        # stranded behind a fixed two-request per-configuration limit.
+        manager = nullcontext(self.executor) if self.executor is not None else ThreadPoolExecutor(max_workers=self.concurrency)
+        with manager as pool:
+            pending, remaining = set(), iter(packs)
+            def submit():
+                indices = next(remaining, None)
+                if indices is not None:
+                    pending.add(pool.submit(run, indices))
+            for _ in range(self.concurrency):
+                submit()
+            try:
+                while pending:
+                    done, _ = wait(pending, return_when=FIRST_COMPLETED)
+                    for future in done:
+                        pending.remove(future)
+                        indices, bands = future.result()
+                        for j, index in enumerate(indices):
+                            outputs[index] = fullstack_projection(bands[j], targets[index])
+                        submit()
+            finally:
+                for future in pending:
+                    future.cancel()
+        for entry, target, bands in zip(entries, targets, outputs):
+            # The point forecast is the median, matching the full-stack scorer.
+            arrays = np.concatenate([bands, bands[..., 4:5]], axis=-1).transpose(2, 1, 0)
+            if np.asarray(entry["target"]).ndim == 1:
+                arrays = arrays[..., 0]
+            yield QuantileForecast(arrays, start_date=entry["start"] + target.shape[-1],
+                                   forecast_keys=[str(q) for q in LEVELS] + ["mean"], item_id=entry.get("item_id"))
+
+
+def metrics():
+    from gluonts.ev.metrics import MAE, MAPE, MASE, MSE, MSIS, ND, NRMSE, RMSE, SMAPE, MeanWeightedSumQuantileLoss
+    return [MSE(forecast_type="mean"), MSE(forecast_type=.5), MAE(), MASE(), MAPE(), SMAPE(), MSIS(),
+            RMSE(), NRMSE(), ND(), MeanWeightedSumQuantileLoss(quantile_levels=LEVELS)]
+
+
+def evaluate_config(client, name, term, *, model_revision, window_limit=None, concurrency=4, executor=None, cache_dir=None):
+    from gluonts.model import evaluate_model
+    from gluonts.time_feature import get_seasonality
+    ds = load_dataset(name, term)
+    predictor = PdmPredictor(client, ds.prediction_length, model_revision=model_revision,
+                             use_past_covariates=bool(ds.past_feat_dynamic_real_dim), concurrency=concurrency, executor=executor, cache_dir=cache_dir)
+    data = ds.test_data
+    if window_limit is not None:
+        from itertools import islice
+        from types import SimpleNamespace
+        data = SimpleNamespace(input=list(islice(data.input, window_limit)), label=list(islice(data.label, window_limit)))
+    result = evaluate_model(predictor, test_data=data, metrics=metrics(), batch_size=512, axis=None,
+                            mask_invalid_label=True, allow_nan_forecast=False, seasonality=get_seasonality(ds.freq))
+    return {column: float(result[column].iloc[0]) for column in result.columns}
+
+
+class ScoreMismatchError(AssertionError):
+    def __init__(self, report):
+        self.report = report
+        first = report["mismatches"][0]
+        super().__init__(f"{first['config']} {first['metric']}: API/official={first['measured']}, recorded={first['reference']}")
+
+
+def verify_results(results, reference, *, rtol=.005):
+    """Check every measured config against the recorded full-stack run."""
+    expected = {r["config"]: r for r in reference["configs"]}
+    checks, mismatches = [], []
+    for key, values in results.items():
+        baseline = expected[key]
+        for metric, column in [("MASE", "MASE[0.5]"), ("WQL", "mean_weighted_sum_quantile_loss")]:
+            got = values[column]
+            wanted = baseline[metric]
+            if not math.isfinite(got) or not math.isclose(got, wanted, rel_tol=rtol, abs_tol=1e-7):
+                mismatches.append({"config": key, "metric": metric, "measured": got, "reference": wanted,
+                                   "relative_difference": got / wanted - 1 if wanted else None})
+        checks.append(key)
+    population_complete = len(checks) == 97 and set(checks) == set(expected)
+    report = {"checked_configs": len(checks), "population_complete": population_complete,
+              "complete": population_complete and not mismatches, "rtol": rtol, "mismatches": mismatches}
+    if mismatches:
+        raise ScoreMismatchError(report)
+    return report
+
+
+def load_reference(path=None, *, profile="historical"):
+    """Load an explicit scoring target, retaining the original historical run.
+
+    The L40S target is the measured production run proposed for submission.
+    It shares the pinned dataset and baseline with the historical run, and
+    never rewrites the earlier scores or changes comparison tolerances.
+    """
+    if profile not in {"historical", "l40s"} or (path is not None and profile != "historical"):
+        raise ValueError("Choose historical, l40s, or an explicit historical reference path")
+    target = Path(path) if path else Path(__file__).with_name("gift_reference.json")
+    reference = json.loads(target.read_text())
+    if profile == "l40s":
+        measured = json.loads(Path(__file__).with_name("gift_reference_l40s.json").read_text())
+        if measured["model_revision"] != reference["model_revision"]:
+            raise ValueError("L40S and historical reference weights differ")
+        rows = {row["config"]: row for row in measured["configs"]}
+        expected = {row["config"] for row in reference["configs"]}
+        if len(rows) != len(measured["configs"]) or set(rows) != expected or len(rows) != 97:
+            raise ValueError("L40S reference must contain every configuration exactly once")
+        reference["configs"] = [{**row, **rows[row["config"]]} for row in reference["configs"]]
+        reference.update(summary=measured["summary"], source=measured["provenance"],
+                         reference_profile=measured["profile"],
+                         runtime=measured["runtime"], source_results_sha256=measured["source_results_sha256"])
+    return reference
+
+
+def verify_dataset(path, reference):
+    """Verify the exact official Arrow snapshot used for the recorded scores."""
+    root = Path(path)
+    for relative, wanted in reference["dataset_files_sha256"].items():
+        digest = hashlib.sha256()
+        with (root / relative).open("rb") as stream:
+            for block in iter(lambda: stream.read(8 * 1024 * 1024), b""):
+                digest.update(block)
+        if digest.hexdigest() != wanted:
+            raise ValueError(f"GIFT dataset integrity mismatch: {relative}")
+    return {"repository": reference["dataset_repo"], "revision": reference["dataset_revision"],
+            "verified_files": len(reference["dataset_files_sha256"])}