| """Payload assembly — every answer this Space returns goes through here. |
| |
| The contract (ADR-0001 §5, accepted 2026-10-20), on top of the family invariants: |
| |
| - Every payload is a dict with ``status`` in {"ok", "refused", "error", "denied"} plus a |
| human-readable ``reason`` on every non-ok status. Refusals are answers, never exceptions. |
| - Every payload except a denial carries a ``run_id`` (the gate mints none for a caller it |
| turned away). |
| - Every ``ok`` payload carries ``kind: "annotation"`` and **no** ``hierarchy`` or |
| ``n_for_inference``. This is the deliberate break from the data specialists: a row count here |
| is not a sample size, and nothing downstream may render it as one. |
| - Every row carries a complete ``provenance`` block (:mod:`src.provenance`); :func:`ok` refuses to |
| build a payload around a row that does not. |
| - ``coverage_notes`` and ``attribution`` come from config for every source the payload used, and |
| the deterministic ``narrative`` says "according to <source> (queried <date>)". |
| """ |
|
|
| from __future__ import annotations |
|
|
| import datetime |
| import json |
| import secrets |
| from collections.abc import Iterable |
| from typing import Any |
|
|
| from src import config |
| from src.provenance import missing_fields |
|
|
| STATUSES = ("ok", "refused", "error", "denied") |
| SOURCE_ERROR_REASONS = ("source_unavailable", "rate_limited", "upstream_schema_drift") |
| KIND = "annotation" |
| DISCLAIMER = ( |
| "External annotation, not analysis: these rows are what the named public sources say, " |
| "as of the query date on each row. Nothing here was computed from a dataset, and no " |
| "statistic was run." |
| ) |
|
|
|
|
| def mint_run_id() -> str: |
| """A sortable, collision-resistant run id (sibling-agent format).""" |
| stamp = datetime.datetime.now(datetime.UTC).strftime("%Y%m%d_%H%M%S") |
| return f"{stamp}_{secrets.randbelow(10**6):06d}" |
|
|
|
|
| def source_error(source: str, reason: str, detail: str) -> dict[str, str]: |
| if reason not in SOURCE_ERROR_REASONS: |
| raise ValueError(f"source error reason must be one of {SOURCE_ERROR_REASONS}") |
| return {"source": source, "reason": reason, "detail": detail} |
|
|
|
|
| def _attribution(source_ids: Iterable[str]) -> list[dict[str, str]]: |
| out = [] |
| for sid in sorted(set(source_ids)): |
| src = config.source(sid) |
| out.append( |
| { |
| "source": sid, |
| "name": src["name"], |
| "citation": src["citation"], |
| "licence": src["licence"], |
| "licence_url": src["licence_url"], |
| } |
| ) |
| return out |
|
|
|
|
| def _coverage_notes(source_ids: Iterable[str]) -> list[dict[str, str]]: |
| return [ |
| {"source": sid, "note": note} |
| for sid in sorted(set(source_ids)) |
| for note in config.source(sid)["coverage_notes"] |
| ] |
|
|
|
|
| def ok( |
| endpoint: str, |
| *, |
| query: dict[str, Any], |
| rows: list[dict[str, Any]], |
| sources_used: Iterable[str], |
| narrative: str, |
| unresolved: Iterable[dict[str, str]] = (), |
| source_errors: Iterable[dict[str, str]] = (), |
| run_id: str | None = None, |
| **extra: Any, |
| ) -> dict[str, Any]: |
| """An ok payload. Raises ValueError (a programming error) on an unstamped row.""" |
| for i, row in enumerate(rows): |
| gaps = missing_fields(row) |
| if gaps: |
| raise ValueError(f"row {i} is missing provenance fields {gaps}") |
| if not narrative.strip(): |
| raise ValueError("an ok payload needs its deterministic narrative") |
| used = list(sources_used) |
| forbidden = {"hierarchy", "n_for_inference"} & set(extra) |
| if forbidden: |
| raise ValueError(f"annotation payloads never carry {sorted(forbidden)}") |
| payload: dict[str, Any] = { |
| "status": "ok", |
| "run_id": run_id or mint_run_id(), |
| "kind": KIND, |
| "endpoint": endpoint, |
| "query": query, |
| "rows": rows, |
| "unresolved": list(unresolved), |
| "source_errors": list(source_errors), |
| "coverage_notes": _coverage_notes(used), |
| "attribution": _attribution(used), |
| "narrative": narrative, |
| "disclaimer": DISCLAIMER, |
| } |
| payload.update(extra) |
| return payload |
|
|
|
|
| def refused(endpoint: str, reason: str, message: str, *, run_id: str | None = None) -> dict: |
| return { |
| "status": "refused", |
| "run_id": run_id or mint_run_id(), |
| "endpoint": endpoint, |
| "reason": reason, |
| "message": message, |
| } |
|
|
|
|
| def error( |
| endpoint: str, |
| reason: str, |
| message: str, |
| *, |
| source_errors: Iterable[dict[str, str]] = (), |
| run_id: str | None = None, |
| ) -> dict: |
| return { |
| "status": "error", |
| "run_id": run_id or mint_run_id(), |
| "endpoint": endpoint, |
| "reason": reason, |
| "message": message, |
| "source_errors": list(source_errors), |
| } |
|
|
|
|
| def denied(message: str) -> dict: |
| return {"status": "denied", "reason": "access_denied", "message": message} |
|
|
|
|
| def to_json(payload: dict[str, Any]) -> str: |
| if payload.get("status") not in STATUSES: |
| raise ValueError(f"unknown status {payload.get('status')!r}") |
| return json.dumps(payload, ensure_ascii=False) |
|
|
