Align SDK 0.1.5 with TRACE 0.5.x runtime + handler

This is the alignment audit follow-up: the SDK now matches the
canonical TRACE wire schema and the RunPod handler envelope
field-for-field on every shape that production callers consume
(groundedness scoring, redaction, compression, memory, rollup).

Key fixes that callers see immediately:

* RunPod handler error envelope ({error_code, error, hint, status_code,
  docs_url}) is now decoded into the structured _Envelope used by
  LatenceTraceAPIError. Prior versions only matched {code, message}
  and silently degraded RunPod failures to "HTTP {status}".
* GroundednessRequest accepts `language` as the canonical field
  (with `locale` as a deprecated alias). The server reads `language`
  to pick the per-class calibration bundle; older SDK calls that
  set `locale` were silently dropped on the server.
* RunPod transports now default response_format=canonical so the
  typed GroundednessResponse populates nested scores / runtime_decision
  blocks instead of receiving the flat compact dict (which left most
  typed fields at None).
* score_groundedness exposes profile, response_format,
  include_triangular_diagnostics, evidence_limit, heatmap_format,
  auto_decide as first-class kwargs alongside the existing extra
  fall-through.
* rollup() normalizes the RunPod {success, action, rollup: {...}}
  envelope into the same metrics dict REST returns, and gains an
  as_model=True flag returning the new typed RollupResponse.

Typed model parity bumps:

* GroundednessScores gains nli_aggregate, primary_score/name,
  reverse_context*, semantic_entropy_*, literal_*, structured_*,
  context_*_ratio, support_units_usage_*, and the AST/phantom
  channels emitted by the code lane.
* GroundednessResponse adds top-level band/score/groundedness_v2,
  corpus_route, heatmap, warnings, scoring_mode, profile,
  effective_profile, session_id, *_diagnostics, and the
  next_session_state / next_memory_state lanes.
* RuntimeDecision adds band, policy_version/policy_sha256,
  head_registry_sha256/head_version, reason_codes, evidence,
  unsupported_spans, allow/block_disabled, allow/block_threshold,
  rollback_safe -- covering the full RuntimeDecisionRecord, including
  the new calibration_band_coercion reason code.
* MemoryUpdateResponse.hot_context becomes required (server
  contract); CompressionResponse.provider stays Optional[str].
* RollupResponse mirrors the FastAPI shape so as_model=True works
  for both REST and RunPod transports.

Helper updates:

* GroundednessResponse.fill_native_risk_band promotes risk_band
  from scores.risk_band -> top-level band -> runtime_decision.band
  (in that priority order), matching the new backend coercion.
* integrations._band_utils.resolve_band/resolve_score prefer the
  calibration risk_band / trace_score over the head-driven
  runtime_decision.band / decision.score, so adapter consumers
  render the same band the event log shows.

Deferred to a separate release: typed RunPod action mappings for
the nine /v1/trace/sessions* paths. Those require typed session
models and live outside the groundedness/rollup hot path.

Bumps version 0.1.4 -> 0.1.5 (pyproject.toml + DEFAULT_USER_AGENT).
All 41 unit tests green (27 existing + 14 new alignment regressions).

Author: ddickmann

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "latence"
-version = "0.1.4"
+version = "0.1.5"
 description = "Thin Python SDK for Latence TRACE."
 readme = "README.md"
 requires-python = ">=3.10"

src/latence/__init__.py

@@ -32,12 +32,19 @@
     ComplianceRedactionResponse,
     ComplianceUsage,
     CompressionResponse,
+    CorpusRoute,
     GroundednessRequest,
     GroundednessResponse,
+    GroundednessScores,
     MemoryUpdateResponse,
     NLIVerdict,
     RiskBand,
+    RollupDriftTrend,
+    RollupResponse,
+    RollupTopDeadFile,
     RuntimeDecision,
+    RuntimeEvidenceUnit,
+    RuntimeUnsupportedSpan,
     SupportUnit,
     TokenScore,
 )
@@ -49,7 +56,7 @@
     TraceSessionSnapshot,
 )
 
-__version__ = "0.1.4"
+__version__ = "0.1.5"
 
 __all__ = [
     "AsyncLatence",
@@ -64,9 +71,11 @@
     "ComplianceRedactionResponse",
     "ComplianceUsage",
     "CompressionResponse",
+    "CorpusRoute",
     "FileSessionStorage",
     "GroundednessRequest",
     "GroundednessResponse",
+    "GroundednessScores",
     "InMemorySessionStorage",
     "Latence",
     "LatenceTraceAPIError",
@@ -79,7 +88,12 @@
     "MemoryUpdateResponse",
     "NLIVerdict",
     "RiskBand",
+    "RollupDriftTrend",
+    "RollupResponse",
+    "RollupTopDeadFile",
     "RuntimeDecision",
+    "RuntimeEvidenceUnit",
+    "RuntimeUnsupportedSpan",
     "SessionStorage",
     "SupportUnit",
     "TokenScore",

src/latence/_transport.py

@@ -25,7 +25,7 @@
     _Envelope,
 )
 
-DEFAULT_USER_AGENT = "latence/0.1.4"
+DEFAULT_USER_AGENT = "latence/0.1.5"
 DEFAULT_TIMEOUT_SECONDS = 30.0
 DEFAULT_MAX_RETRIES = 4
 RETRYABLE_STATUS = frozenset({429, 500, 502, 503, 504})
@@ -106,7 +106,24 @@ def parse_retry_after(value: str | None) -> float | None:
 
 def decode_error(status: int, body: Any, request_id: str | None) -> LatenceTraceAPIError:
     envelope = _envelope_from_body(body)
-    message = envelope.message if envelope and envelope.message else f"HTTP {status}"
+    if envelope and envelope.message:
+        message = envelope.message
+    elif status == 422 and isinstance(body, Mapping) and isinstance(body.get("detail"), list):
+        # FastAPI validator errors — the detail is a list of error dicts.
+        # Surface a useful message instead of the generic ``HTTP 422``.
+        details = body["detail"]
+        head = details[0] if details else None
+        if isinstance(head, Mapping):
+            loc = head.get("loc")
+            msg = head.get("msg") or "validation error"
+            location = ".".join(str(item) for item in loc) if isinstance(loc, list) else None
+            message = (
+                f"validation error at {location}: {msg}" if location else f"validation error: {msg}"
+            )
+        else:
+            message = f"validation error: {details!r}"
+    else:
+        message = f"HTTP {status}"
     if status in (401, 402, 403):
         return LatenceTraceAuthError(
             message,
@@ -138,27 +155,59 @@ def decode_error(status: int, body: Any, request_id: str | None) -> LatenceTrace
     return LatenceTraceAPIError(message, status=status, envelope=envelope, request_id=request_id)
 
 
+_ERROR_ENVELOPE_RESERVED = frozenset(
+    {"code", "message", "hint", "docs_url", "error_code", "error", "status_code"}
+)
+
+
 def _envelope_from_body(body: Any) -> _Envelope | None:
+    """Coerce a server error body into a structured :class:`_Envelope`.
+
+    Recognises three wire shapes:
+
+    1. FastAPI ``{"detail": {"code": ..., "message": ..., "hint": ...}}``
+       — the canonical REST error envelope.
+    2. RunPod handler ``{"success": false, "error_code": ..., "error":
+       ..., "hint": ..., "status_code": ..., "docs_url": ...}`` —
+       emitted by ``runpod/handler.py::_service_error_payload`` when a
+       job fails. The handler does not use ``code``/``message``;
+       prior SDK versions would silently fall through to the
+       ``HTTP {status}`` placeholder.
+    3. FastAPI ``{"detail": "<plain string>"}`` — degraded path; we
+       keep ``code=None`` and stuff the string into ``message`` so
+       callers still get a useful description.
+    """
+
     if not isinstance(body, Mapping):
         return None
     detail = body.get("detail")
     if isinstance(detail, Mapping):
         body = detail
+    elif isinstance(detail, str) and detail:
+        return _Envelope(code="error", message=detail, hint=None, docs_url=None, extra={})
     if not isinstance(body, Mapping):
         return None
-    code = body.get("code")
-    if not isinstance(code, str):
+
+    # Accept either ``code`` (REST) or ``error_code`` (RunPod handler).
+    code_value = body.get("code")
+    if not isinstance(code_value, str):
+        code_value = body.get("error_code")
+    # Accept either ``message`` (REST) or ``error`` (RunPod handler).
+    message_value = body.get("message")
+    if not isinstance(message_value, str) or not message_value:
+        message_value = body.get("error")
+
+    # Bail when neither code nor message is present — there is no
+    # structured envelope to surface.
+    if not isinstance(code_value, str) and not isinstance(message_value, str):
         return None
+
     return _Envelope(
-        code=code,
-        message=str(body.get("message") or ""),
+        code=str(code_value) if isinstance(code_value, str) else "error",
+        message=str(message_value) if isinstance(message_value, str) else "",
         hint=body.get("hint") if isinstance(body.get("hint"), str) else None,
         docs_url=body.get("docs_url") if isinstance(body.get("docs_url"), str) else None,
-        extra={
-            k: v
-            for k, v in body.items()
-            if k not in {"code", "message", "hint", "docs_url"}
-        },
+        extra={k: v for k, v in body.items() if k not in _ERROR_ENVELOPE_RESERVED},
     )
 
 

src/latence/async_client.py

@@ -26,6 +26,7 @@
     runpod_request_body,
     unwrap_runpod_response,
 )
+from latence.client import _build_groundedness_payload, _normalize_rollup_body
 from latence.errors import (
     LatenceTraceAPIError,
     LatenceTraceRateLimited,
@@ -41,9 +42,9 @@
     ComplianceRedactionRequest,
     ComplianceRedactionResponse,
     CompressionResponse,
-    GroundednessRequest,
     GroundednessResponse,
     MemoryUpdateResponse,
+    RollupResponse,
     SupportUnit,
 )
 from latence.sessions import (
@@ -344,10 +345,18 @@ async def score_groundedness(
         coverage_threshold: float | None = None,
         raw_context_chunk_tokens: int | None = None,
         response_chunk_tokens: int | None = None,
+        language: str | None = None,
         locale: str | None = None,
         context_trust_enabled: bool = True,
         runtime_head_features: Mapping[str, float] | None = None,
         trajectory_features: Mapping[str, float] | None = None,
+        profile: str | None = None,
+        scoring_mode: str | None = None,
+        response_format: str | None = None,
+        include_triangular_diagnostics: bool | None = None,
+        evidence_limit: int | None = None,
+        heatmap_format: str | None = None,
+        auto_decide: bool | None = None,
         extra: Mapping[str, Any] | None = None,
     ) -> GroundednessResponse:
         payload = self._build_payload(
@@ -361,10 +370,18 @@ async def score_groundedness(
             coverage_threshold=coverage_threshold,
             raw_context_chunk_tokens=raw_context_chunk_tokens,
             response_chunk_tokens=response_chunk_tokens,
+            language=language,
             locale=locale,
             context_trust_enabled=context_trust_enabled,
             runtime_head_features=runtime_head_features,
             trajectory_features=trajectory_features,
+            profile=profile,
+            scoring_mode=scoring_mode,
+            response_format=response_format,
+            include_triangular_diagnostics=include_triangular_diagnostics,
+            evidence_limit=evidence_limit,
+            heatmap_format=heatmap_format,
+            auto_decide=auto_decide,
             extra=extra,
         )
         return await self._request(
@@ -428,14 +445,20 @@ async def redact_compliance(
     async def rollup(
         self,
         turns: Sequence[Mapping[str, Any]],
+        *,
+        as_model: bool = False,
         **options: Any,
-    ) -> Mapping[str, Any]:
-        return await self._request(
+    ) -> RollupResponse | Mapping[str, Any]:
+        body = await self._request(
             "POST",
             "/groundedness/rollup",
             json={"turns": list(turns), **options},
             expected_model=None,
         )
+        normalized = _normalize_rollup_body(body)
+        if as_model:
+            return RollupResponse.model_validate({**normalized, "raw": body})
+        return normalized
 
     def session(
         self,
@@ -470,48 +493,46 @@ def _build_payload(
         coverage_threshold: float | None,
         raw_context_chunk_tokens: int | None,
         response_chunk_tokens: int | None,
+        language: str | None,
         locale: str | None,
         context_trust_enabled: bool,
         runtime_head_features: Mapping[str, float] | None,
         trajectory_features: Mapping[str, float] | None,
+        profile: str | None,
+        scoring_mode: str | None,
+        response_format: str | None,
+        include_triangular_diagnostics: bool | None,
+        evidence_limit: int | None,
+        heatmap_format: str | None,
+        auto_decide: bool | None,
         extra: Mapping[str, Any] | None,
     ) -> dict:
-        normalised_units: list[dict] | None = None
-        if support_units:
-            normalised_units = [
-                u.model_dump(exclude_none=True) if isinstance(u, SupportUnit) else dict(u)
-                for u in support_units
-            ]
-        try:
-            req = GroundednessRequest(
-                query_text=query,
-                response_text=response_text,
-                chunk_ids=list(chunk_ids) if chunk_ids else None,
-                raw_context=_coerce_raw_context(raw_context),
-                support_units=(
-                    [SupportUnit(**u) for u in normalised_units]
-                    if normalised_units
-                    else None
-                ),
-                attribution_mode=attribution_mode,
-                primary_metric=primary_metric,
-                coverage_threshold=coverage_threshold,
-                raw_context_chunk_tokens=raw_context_chunk_tokens,
-                response_chunk_tokens=response_chunk_tokens,
-                locale=locale,
-                context_trust_enabled=context_trust_enabled,
-                runtime_head_features=runtime_head_features,
-                trajectory_features=trajectory_features,
-            )
-        except ValidationError as exc:
-            raise LatenceTraceValidationError(
-                f"client-side request validation failed: {exc.errors()[:3]}",
-                status=422,
-            ) from exc
-        body = req.model_dump(mode="json", exclude_none=True)
-        if extra:
-            body.update(dict(extra))
-        return body
+        return _build_groundedness_payload(
+            runpod=self._runpod,
+            response_text=response_text,
+            query=query,
+            chunk_ids=chunk_ids,
+            raw_context=raw_context,
+            support_units=support_units,
+            attribution_mode=attribution_mode,
+            primary_metric=primary_metric,
+            coverage_threshold=coverage_threshold,
+            raw_context_chunk_tokens=raw_context_chunk_tokens,
+            response_chunk_tokens=response_chunk_tokens,
+            language=language,
+            locale=locale,
+            context_trust_enabled=context_trust_enabled,
+            runtime_head_features=runtime_head_features,
+            trajectory_features=trajectory_features,
+            profile=profile,
+            scoring_mode=scoring_mode,
+            response_format=response_format,
+            include_triangular_diagnostics=include_triangular_diagnostics,
+            evidence_limit=evidence_limit,
+            heatmap_format=heatmap_format,
+            auto_decide=auto_decide,
+            extra=extra,
+        )
 
     async def _request(
         self,