diff --git a/CHANGELOG.md b/CHANGELOG.md index 3d14fb470..73ddaeae2 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -67,6 +67,15 @@ these packages. All five distributions share one version and one entry. `sdm_client.percentile_thresholds()` draws one such line from the scores alone, by percentile, widened by how scattered the scores are. Install the drawing with the `report` extra. +- `sdm_client.reporting.forecast_report()` draws why a `kumo-forecast` + answer is the forecast it is, from the explanation the answer carries: how + far back in the window each forecast step rests, how the model's latent + state moved over the history and how smoothly, and, asked for separately + because each costs several times the forecast, how much each channel + measured alongside the series contributed, how steadily the model reads + each of them, and what it read reading by reading. The last is asked for + with the `integrated_gradients` inference option and the rest with + `feature_axis`. ### Changed diff --git a/packages/structured-data-models-client/pyproject.toml b/packages/structured-data-models-client/pyproject.toml index cdf02c57f..e168b0bf9 100644 --- a/packages/structured-data-models-client/pyproject.toml +++ b/packages/structured-data-models-client/pyproject.toml @@ -93,7 +93,11 @@ in-process = ["structured-data-models>=0.2.1,<0.3; python_version >= '3.11'"] # not given one. `all` does not carry it for the same reason it does not carry # `databricks-serving`: it is a thing to do with an answer rather than a # backend to read. -report = ["matplotlib>=3.8,<4"] +# Drawing a forecast explanation reads the attribution's own tensors, so this +# brings torch as well as matplotlib. structured-data-models brings torch too, +# and a forecast explanation needs that package anyway; this is so that asking +# for `[report]` alone is enough to draw what you were given. +report = ["matplotlib>=3.8,<4", "torch>=2.7"] all = [ "structured-data-models-client[relational,sqlite,duckdb,postgres,snowflake,databricks,lakebase,s3]", ] diff --git a/packages/structured-data-models-client/src/sdm_client/client.py b/packages/structured-data-models-client/src/sdm_client/client.py index 47c1efa81..3a1255b87 100644 --- a/packages/structured-data-models-client/src/sdm_client/client.py +++ b/packages/structured-data-models-client/src/sdm_client/client.py @@ -25,6 +25,8 @@ from types import TracebackType from typing import Any +from predictive_query import RELATIONAL, TABULAR + from sdm_client.base import ( ModelAdapter, ModelCapabilities, @@ -558,7 +560,9 @@ def _answer( _analysed_or_warned( lambda: ColumnExplanations(_LabelledRows.of(request, calls[0])) ) - if analysed and 'explanation' in fields + if analysed + and 'explanation' in fields + and _learns_from_labels(adapter.spec) else None ) # Every call's rows are kept. A request past the endpoint's per-call @@ -1294,6 +1298,17 @@ def _pinned_dtypes(pinned: Mapping[str, Any]) -> dict[str, str] | None: } +def _learns_from_labels(spec: ModelSpec) -> bool: + r"""Whether ``spec``'s model is shown labelled rows to learn from. + + A column analysis reads those rows, so it is computed only for a model + that has them. A forecast's context is a history rather than labelled + examples. Read as though it were one, each reading of the series was + taken for a class. + """ + return spec.profile in (TABULAR, RELATIONAL) + + def _analysed_or_warned( analyse: Callable[[], ColumnExplanations], ) -> ColumnExplanations | None: diff --git a/packages/structured-data-models-client/src/sdm_client/explain/__init__.py b/packages/structured-data-models-client/src/sdm_client/explain/__init__.py new file mode 100644 index 000000000..6ba12ca26 --- /dev/null +++ b/packages/structured-data-models-client/src/sdm_client/explain/__init__.py @@ -0,0 +1,22 @@ +# SPDX-FileCopyrightText: Copyright (c) 2026, NVIDIA CORPORATION & AFFILIATES. +# All rights reserved. +# SPDX-License-Identifier: Apache-2.0 + +r"""Why a forecast is the forecast it is. + +Asked for as an output field, like any other, and produced only where the +model runs in this process: the attribution reads the model's gradients and +its latent trajectory, and neither of those crosses a wire. + +It is expensive. The latent trajectory walks a window per step of the +context, so an explanation costs tens of seconds on a CPU where a forecast +costs a fraction of one, and feature-axis attribution costs minutes. That is +why it is asked for rather than always computed. + +Not public API itself. :func:`sdm_client.reporting.forecast_report` draws +what this produces. +""" + +from sdm_client.explain._explain import explanation_of + +__all__ = ['explanation_of'] diff --git a/packages/structured-data-models-client/src/sdm_client/explain/_attribution/__init__.py b/packages/structured-data-models-client/src/sdm_client/explain/_attribution/__init__.py new file mode 100644 index 000000000..c31256c89 --- /dev/null +++ b/packages/structured-data-models-client/src/sdm_client/explain/_attribution/__init__.py @@ -0,0 +1,14 @@ +# SPDX-FileCopyrightText: Copyright (c) 2026, NVIDIA CORPORATION & AFFILIATES. +# All rights reserved. +# SPDX-License-Identifier: Apache-2.0 + +r"""The forecast attribution and its report, as they were written. + +Kept together and kept as written: an attribution is a statement about what a +model did, and rewriting the arithmetic that makes it would make it a +statement about something else. + +Only the imports are rewired, to reach each other here. These modules are +excluded from type checking for the same reason the generated parser is +excluded from linting: they are not this repository's to edit. +""" diff --git a/packages/structured-data-models-client/src/sdm_client/explain/_attribution/channel_flow.py b/packages/structured-data-models-client/src/sdm_client/explain/_attribution/channel_flow.py new file mode 100644 index 000000000..6406082ae --- /dev/null +++ b/packages/structured-data-models-client/src/sdm_client/explain/_attribution/channel_flow.py @@ -0,0 +1,533 @@ +# SPDX-FileCopyrightText: Copyright (c) 2026, NVIDIA CORPORATION & AFFILIATES. +# All rights reserved. +# SPDX-License-Identifier: Apache-2.0 + +# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. +# SPDX-License-Identifier: Apache-2.0 + +from __future__ import annotations + +"""Per-channel Jacobian-flow decomposition for feature-axis interpretability. + +This module extends the temporal-axis framework in :mod:`interpretability` to +multivariate inputs. It decomposes each latent trajectory step into per-channel +contributions with a directional central-secant approximation of the +channel-block Jacobian. + +The resulting per-channel flow feeds :func:`lag_channel_horizon_attribution`, +which produces a joint `[K, C, H]` lag-by-channel-by-horizon attribution +tensor. :func:`channel_horizon_marginal` reduces that tensor to the `[C, H]` +feature-axis attribution used by the SDK report. +""" + +from collections.abc import Callable +from dataclasses import dataclass +from typing import TYPE_CHECKING, Literal + +import numpy as np +import torch + +if TYPE_CHECKING: + from collections.abc import Sequence + +from sdm_client.explain._attribution.interpretability import ( + Array, + ForecastModel, + _embed_batch, + _rolling_window_sources, +) + +# --------------------------------------------------------------------------- +# Configuration +# --------------------------------------------------------------------------- + + +@dataclass(frozen=True) +class ChannelFlowConfig: + """Configuration for per-channel Jacobian-flow decomposition. + + Args: + jacobian_secant_scale: Multiplicative scale applied to the per-channel + input increment for the central-difference probe. + time_indices: Optional trajectory transition indices to evaluate. By + default every consecutive transition is processed. + batch_size: Number of probe windows evaluated per forward pass. + transition_batch: Number of transitions stacked into one embed call + before the probe windows are chunked by `batch_size`. + """ + + jacobian_secant_scale: float = 0.5 + time_indices: Sequence[int] | None = None + batch_size: int = 32 + transition_batch: int = 1 + + +@dataclass(frozen=True) +class ChannelFlowReport: + """Per-channel Jacobian-flow decomposition outputs.""" + + method: str + per_channel_flow: Array + flow_total: Array + residual_ratio_per_step: Array | None = None + residual_ratio_mean: float | None = None + residual_ratio_p95: float | None = None + n_time_steps: int = 0 + n_channels: int = 0 + + +# --------------------------------------------------------------------------- +# Shared helpers +# --------------------------------------------------------------------------- + + +def _resolve_step_indices( + *, + time_indices: Sequence[int] | None, + n_windows: int, +) -> np.ndarray: + """Return the array of trajectory transition indices to evaluate. + + A "transition" at index ``tau`` is the pair ``(tau, tau+1)``; valid range + is ``[0, n_windows - 2]``. + """ + if n_windows < 2: + raise ValueError( + f'Need at least 2 rolling windows for flow, got {n_windows}' + ) + if time_indices is None: + return np.arange(n_windows - 1, dtype=np.int64) + arr = np.asarray(time_indices, dtype=np.int64).reshape(-1) + if arr.size == 0: + raise ValueError( + '`time_indices` must contain at least one transition index.' + ) + invalid = (arr < 0) | (arr >= n_windows - 1) + if np.any(invalid): + raise ValueError( + f'`time_indices` contains values outside [0, {n_windows - 2}]: {arr[invalid].tolist()}' + ) + return np.unique(arr) + + +class _ChannelFlowEmbedDP(torch.nn.Module): + """Routes forward() to model.embed() so DataParallel shards the + probe-embedding batches across GPUs in channel-flow Jacobians. + DataParallel only intercepts forward(), not arbitrary named methods. + """ + + def __init__(self, model: ForecastModel) -> None: + super().__init__() + self._m = model + + def forward( + self, x_enc: torch.Tensor, input_mask: torch.Tensor + ) -> torch.Tensor: + out = self._m.embed(x_enc=x_enc, input_mask=input_mask) + return out.embeddings if hasattr(out, 'embeddings') else out + + +def _embed_windows_batched( + model: ForecastModel, + windows: Array, + masks: Array, + *, + device: torch.device, + batch_size: int, +) -> Array: + """Batched embedding of a stack of ``[N, C, L]`` windows. + + NaN/inf in the model's embedding output are replaced with zero, mirroring + the sanitization that ``interpretability.extract_latent_trajectory`` + applies to the v1 path. Without this, non-finite activations from + out-of-distribution forecast-extension windows can propagate + into ``per_channel_flow`` and break the v1 reduction (Prop 1) on real + weights even though the in-context portion is clean. + """ + n = int(windows.shape[0]) + if n == 0: + return np.zeros((0, 0), dtype=np.float32) + out_chunks: list[Array] = [] + _is_dp = isinstance(model, torch.nn.DataParallel) + for i in range(0, n, batch_size): + x = torch.from_numpy( + np.ascontiguousarray(windows[i : i + batch_size]) + ).to(device=device, dtype=torch.float32) + m = torch.from_numpy( + np.ascontiguousarray(masks[i : i + batch_size]) + ).to(device=device, dtype=torch.long) + if _is_dp: + out_chunks.append( + model(x, m).detach().cpu().numpy().astype(np.float32) + ) + else: + out_chunks.append(_embed_batch(model, x, m)) + z = np.concatenate(out_chunks, axis=0) + if np.any(~np.isfinite(z)): + z = np.nan_to_num(z, nan=0.0, posinf=0.0, neginf=0.0).astype( + np.float32, copy=False + ) + return z + + +ValueFn = Callable[..., Array] + + +# --------------------------------------------------------------------------- +# Jacobian-flow +# --------------------------------------------------------------------------- + + +@torch.no_grad() +def compute_per_channel_flow_jacobian( + model: ForecastModel, + series_ct: Array, # [C, T] + *, + seq_len: int, + input_mask_t: Array | None = None, + device: torch.device, + cfg: ChannelFlowConfig | None = None, + value_fn: ValueFn | None = None, +) -> ChannelFlowReport: + """First-order per-channel decomposition of latent flow. + + For each transition ``tau -> tau+1`` we approximate + + Delta Z_tau^(c) ~= 0.5 * [ embed(X_tau + s * bump_c) - embed(X_tau - s * bump_c) ] + / s + + where ``bump_c`` is the input-tensor with row ``c`` set to the per-channel + increment ``Delta x_tau^(c) = X_{tau+1}[c] - X_tau[c]`` and zeros elsewhere, + and ``s = cfg.jacobian_secant_scale``. The per-channel flow magnitude is + ``phi_tau(c) = || Delta Z_tau^(c) ||_2``. + + The residual ``r_tau = Delta Z_tau - sum_c Delta Z_tau^(c)`` is used to + populate the trust ratio diagnostic. + + Cost: For each of ``T - 1`` transitions we evaluate ``2C + 1`` embeddings + (``C`` "+s" probes, ``C`` "-s" probes, plus ``Z_{tau+1}`` -- ``Z_tau`` is + re-used from the previous iteration). We batch over channels so this is + one batched forward of size ``2C + 1`` per transition. + """ + cfg = cfg or ChannelFlowConfig() + # When multiple GPUs are available and no custom value_fn is set, + # wrap the model so DataParallel splits the (2+2*C)-probe embedding + # batch across devices, cutting wall-clock roughly in half per + # additional GPU without any change to the transition loop logic. + _n_gpus = torch.cuda.device_count() if torch.cuda.is_available() else 0 + if _n_gpus > 1 and value_fn is None: + import logging as _log + + _log.getLogger(__name__).info( + 'channel flow Jacobian: using %d GPUs via DataParallel', _n_gpus + ) + model = torch.nn.DataParallel(_ChannelFlowEmbedDP(model)) + vf = value_fn if value_fn is not None else _embed_windows_batched + + xw_view, m_view, T = _rolling_window_sources( + series_ct, seq_len=seq_len, input_mask_t=input_mask_t + ) + if T < 2: + raise ValueError( + f'Need at least 2 time steps for flow decomposition, got T={T}' + ) + transitions = _resolve_step_indices( + time_indices=cfg.time_indices, n_windows=T + ) + + C = int(np.asarray(series_ct).shape[0]) + L = int(seq_len) + s = float(cfg.jacobian_secant_scale) + if s <= 0: + raise ValueError(f'jacobian_secant_scale must be > 0, got {s}') + + phi = np.full((T - 1, C), np.nan, dtype=np.float32) + flow_total = np.full((T - 1,), np.nan, dtype=np.float32) + residual = np.full((T - 1,), np.nan, dtype=np.float32) + + # Number of "probe windows" per transition: Z_tau, Z_{tau+1}, +/- bumps. + probes_per_trans = 2 + 2 * C + trans_batch = max(1, int(cfg.transition_batch)) + + for chunk_start in range(0, len(transitions), trans_batch): + chunk = transitions[chunk_start : chunk_start + trans_batch] + m_chunk = len(chunk) + + # Pre-fetch all windows referenced by this chunk in one slice each + # (avoids materialising the rolling-window view C+1 times per + # transition like the per-tau path used to do). + starts = chunk.astype(np.int64) + win_a = np.asarray(xw_view[starts], dtype=np.float32) # [m, C, L] + win_b = np.asarray(xw_view[starts + 1], dtype=np.float32) # [m, C, L] + mask_a = np.asarray(m_view[starts], dtype=np.int64) # [m, L] + mask_b = np.asarray(m_view[starts + 1], dtype=np.int64) # [m, L] + delta_cl = (win_b - win_a).astype(np.float32, copy=False) # [m, C, L] + + # Build the [m * probes_per_trans, C, L] probe stack in one shot. + # Layout per transition is [a, b, +probe_0..+probe_{C-1}, -probe_0..]. + stack = np.empty((m_chunk, probes_per_trans, C, L), dtype=np.float32) + stack[:, 0] = win_a + stack[:, 1] = win_b + + # Bumps share the original window's content except on the bumped + # channel row, which is shifted by +/- s * delta_x. We construct + # them by tiling x_a across C "probes" and then overwriting the + # diagonal (c, c) row with the per-channel shifted value. + plus = np.broadcast_to(win_a[:, None, :, :], (m_chunk, C, C, L)).copy() + minus = plus.copy() + # diag indexing: for each transition m and probe c, row c is + # x_a[m, c] +/- s * delta_cl[m, c]. + diag_idx = np.arange(C) + plus[:, diag_idx, diag_idx, :] = ( + win_a[:, diag_idx, :] + s * delta_cl[:, diag_idx, :] + ) + minus[:, diag_idx, diag_idx, :] = ( + win_a[:, diag_idx, :] - s * delta_cl[:, diag_idx, :] + ) + stack[:, 2 : 2 + C] = plus + stack[:, 2 + C :] = minus + + # Mask discipline: position 1 (Z_{tau+1}) uses window B's mask; + # everything else uses window A's mask. This matches the per-window + # mask discipline used by ``extract_latent_trajectory`` and is what + # makes the v1 reduction (Prop 1) hold exactly when C=1. + masks_full = np.broadcast_to( + mask_a[:, None, :], (m_chunk, probes_per_trans, L) + ).copy() + masks_full[:, 1] = mask_b + + flat_stack = stack.reshape(m_chunk * probes_per_trans, C, L) + flat_masks = masks_full.reshape(m_chunk * probes_per_trans, L) + + z_flat = vf( + model, + flat_stack, + flat_masks, + device=device, + batch_size=int(cfg.batch_size), + ) # [m * probes_per_trans, Dv] + D = int(z_flat.shape[1]) + z = z_flat.reshape(m_chunk, probes_per_trans, D) + + z_tau = z[:, 0, :] # [m, D] + z_tau_plus = z[:, 1, :] # [m, D] + delta_z = z_tau_plus - z_tau # [m, D] + + # Per-channel directional derivative, central-secant form: + # (z_+ - z_-) / (2s). Reshape pulls out [m, C, D]. + delta_z_per_chan = (z[:, 2 : 2 + C, :] - z[:, 2 + C :, :]) / ( + 2.0 * s + ) # [m, C, D] + + # Per-tau scalar norms. We deliberately call ``np.linalg.norm`` once + # per row (instead of an axis-aware norm across the m-batch) to + # match the float32 summation order of the original per-tau loop + # bit-for-bit -- otherwise BLAS picks a slightly different reduction + # tree for [m, D] vs [D] inputs and the scalar flow_total / residual + # drift by ~1 ULP. The scalar work is negligible compared to the + # (already-vectorised) embed pass that produced ``z``. + for k, tau in enumerate(chunk): + dz_k = delta_z[k] # [D] + dzpc_k = delta_z_per_chan[k] # [C, D] + phi[int(tau)] = np.linalg.norm(dzpc_k, ord=2, axis=1).astype( + np.float32 + ) + flow_total[int(tau)] = float(np.linalg.norm(dz_k, ord=2)) + denom_k = float(np.linalg.norm(dz_k, ord=2)) + 1e-12 + r_k = dz_k - dzpc_k.sum(axis=0) + residual[int(tau)] = float(np.linalg.norm(r_k, ord=2)) / denom_k + + finite = np.isfinite(residual) + res_mean = float(np.nanmean(residual[finite])) if np.any(finite) else None + res_p95 = ( + float(np.nanpercentile(residual[finite], 95)) + if np.any(finite) + else None + ) + + return ChannelFlowReport( + method='jacobian', + per_channel_flow=phi, + flow_total=flow_total, + residual_ratio_per_step=residual, + residual_ratio_mean=res_mean, + residual_ratio_p95=res_p95, + n_time_steps=int(T - 1), + n_channels=C, + ) + + +def compute_per_channel_flow( + model: ForecastModel, + series_ct: Array, + *, + seq_len: int, + input_mask_t: Array | None = None, + device: torch.device, + cfg: ChannelFlowConfig | None = None, + value_fn: ValueFn | None = None, +) -> ChannelFlowReport: + """Compute the configured per-channel Jacobian-flow report.""" + return compute_per_channel_flow_jacobian( + model, + series_ct, + seq_len=seq_len, + input_mask_t=input_mask_t, + device=device, + cfg=cfg, + value_fn=value_fn, + ) + + +# --------------------------------------------------------------------------- +# Lag x Channel x Horizon attribution +# --------------------------------------------------------------------------- + + +def lag_channel_horizon_attribution( + per_channel_flow: Array, # [T-1, C] + *, + t_index: int, + n_lags: int, + horizon: int, + softmax_tau: float = 1.0, + horizon_kernel: Literal['exp', 'none'] = 'exp', + kernel_min_scale: float = 4.0, + kernel_max_scale: float | None = None, + normalize: Literal['joint', 'per_channel', 'none'] = 'joint', +) -> tuple[Array, Array]: + """Joint lag x channel x horizon attribution. + + This is the natural generalisation of :func:`lag_horizon_attribution` to + a per-channel flow input. The lag-horizon kernel ``w_h(a) = exp(-a / s_h)`` + is reused unchanged from v1; the only difference is that the cumulative + kernel-weighted sum is taken per channel, producing a ``[K, C, H]`` + score tensor instead of v1's ``[K, H]``. + + The ``normalize`` flag controls how the softmax over the score tensor is + taken: + + * ``"joint"`` (default): softmax over the *joint* ``(lag, channel)`` axis + for each horizon. Marginalising over channels recovers v1's + lag-horizon attribution as a sanity check; marginalising over lags + gives a per-channel-per-horizon attribution. + * ``"per_channel"``: softmax over the lag axis, separately for each + ``(c, h)`` pair. Useful when the absolute scale of each channel's + contribution is known to vary widely. + * ``"none"``: return raw scores without softmax normalization. + + Returns: + scores: ``[K, C, H]`` + attributions: ``[K, C, H]`` + """ + flow_tc = np.asarray(per_channel_flow, dtype=np.float32) + if flow_tc.ndim != 2: + raise ValueError( + f'Expected per_channel_flow shape [T-1, C], got {flow_tc.shape}' + ) + flow_tc = np.where(np.isfinite(flow_tc), flow_tc, 0.0).astype(np.float32) + + Tm1, C = flow_tc.shape + K = int(n_lags) + H = int(horizon) + if K <= 0 or H <= 0: + raise ValueError('n_lags and horizon must be positive') + if not (1 <= int(t_index) <= Tm1): + raise ValueError(f't_index must be in [1, {Tm1}], got {t_index}') + if int(t_index) < K: + raise ValueError(f'n_lags must be <= t_index={int(t_index)}, got {K}') + + # Most-recent-first slice of history flow per channel. + hist_tail = flow_tc[max(0, int(t_index) - K) : int(t_index), :] # [<=K, C] + hist_rev = hist_tail[::-1, :] # most recent first + L = hist_rev.shape[0] + + # Horizon scales (identical to v1). + min_s = float(kernel_min_scale) + max_s = ( + float(kernel_max_scale) if kernel_max_scale is not None else float(K) + ) + if min_s <= 0 or max_s <= 0: + raise ValueError('kernel scales must be positive') + max_s = max(max_s, min_s) + if H == 1: + scales_h = np.array([min_s], dtype=np.float32) + else: + u_h = np.arange(H, dtype=np.float32) / float(H - 1) + scales_h = (min_s + u_h * (max_s - min_s)).astype(np.float32) + + scores = np.zeros((K, C, H), dtype=np.float32) + if horizon_kernel == 'none': + csum = np.cumsum(hist_rev, axis=0, dtype=np.float32) # [L, C] + scores[:L, :, :] = csum[:, :, None] + elif horizon_kernel == 'exp': + ages_l = np.arange(L, dtype=np.float32)[:, None] # [L, 1] + target_bytes = 64 * 1024 * 1024 + bytes_per_h = max(1, L * C * 4) + chunk = max(1, min(H, target_bytes // bytes_per_h)) + for h0 in range(0, H, chunk): + h1 = min(H, h0 + chunk) + s = np.maximum(scales_h[h0:h1][None, :], np.float32(1e-6)) + w_lh = np.exp(-ages_l / s).astype(np.float32) # [L, chunk] + # hist_rev: [L, C]; w_lh: [L, chunk] -> contribution per (l, c, h) + hw_lhc = hist_rev[:, :, None] * w_lh[:, None, :] # [L, C, chunk] + csum = np.cumsum(hw_lhc, axis=0, dtype=np.float32) # [L, C, chunk] + scores[:L, :, h0:h1] = csum + else: + raise ValueError(f'Unsupported horizon_kernel={horizon_kernel!r}') + + tau = max(float(softmax_tau), 1e-6) + if normalize == 'none': + return scores, scores.copy() + if normalize == 'per_channel': + attrib = np.empty_like(scores) + for c in range(C): + for h in range(H): + col = scores[:, c, h] + if not np.any(col): + attrib[:, c, h] = 1.0 / float(K) + else: + e = np.exp((col - col.max()) / tau) + s = e.sum() + attrib[:, c, h] = e / s if s > 0 else 1.0 / float(K) + return scores, attrib + if normalize != 'joint': + raise ValueError(f'Unsupported normalize={normalize!r}') + + # Joint softmax over (lag, channel) per horizon. + attrib = np.empty_like(scores) + flat = scores.reshape(K * C, H) + for h in range(H): + col = flat[:, h] + if not np.any(col): + attrib[:, :, h] = 1.0 / float(K * C) + continue + e = np.exp((col - col.max()) / tau) + s = e.sum() + if s <= 0: + attrib[:, :, h] = 1.0 / float(K * C) + else: + attrib[:, :, h] = (e / s).reshape(K, C) + return scores, attrib + + +def channel_horizon_marginal(attribution_kch: Array) -> Array: + """Sum a ``[K, C, H]`` attribution tensor over the lag axis.""" + return ( + np.asarray(attribution_kch, dtype=np.float32) + .sum(axis=0) + .astype(np.float32) + ) + + +def lag_horizon_marginal(attribution_kch: Array) -> Array: + """Sum a ``[K, C, H]`` attribution tensor over the channel axis. + + Matches the v1 lag-horizon attribution shape ``[K, H]`` so it can be + plugged directly into :func:`evaluate_lag_faithfulness`. + """ + return ( + np.asarray(attribution_kch, dtype=np.float32) + .sum(axis=1) + .astype(np.float32) + ) diff --git a/packages/structured-data-models-client/src/sdm_client/explain/_attribution/channel_stability.py b/packages/structured-data-models-client/src/sdm_client/explain/_attribution/channel_stability.py new file mode 100644 index 000000000..5f76d48d6 --- /dev/null +++ b/packages/structured-data-models-client/src/sdm_client/explain/_attribution/channel_stability.py @@ -0,0 +1,378 @@ +# SPDX-FileCopyrightText: Copyright (c) 2026, NVIDIA CORPORATION & AFFILIATES. +# All rights reserved. +# SPDX-License-Identifier: Apache-2.0 + +# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. +# SPDX-License-Identifier: Apache-2.0 + +from __future__ import annotations + +"""Per-channel embedding stability (v2 feature-axis stability). + +This module contains the channel-axis analogue of v1's embedding stability +primitive in :mod:`interpretability`: + +* :func:`compute_embedding_stability` (v1) reports a single scalar Lipschitz + ratio per (model, series), aggregating over many input perturbation trials. + Its v2 counterpart :func:`compute_per_channel_embedding_stability` reports + the same ratio *per input channel*, by perturbing only one row of the input + window at a time. Answers: "which input channels does the embedding map + treat in a Lipschitz-safe way?" + +Mathematical definitions +======================== + +**Per-channel embedding stability (Lipschitz-style).** +For an input context ``X_t in R^{C x L}`` and a channel ``c in {0, ..., C-1}``, +define the per-channel-perturbed input + + X_t^(c, eps) = X_t + epsilon e_c x_t^T , epsilon ~ N(0, (alpha sigma_c)^2 I_L), + +i.e. additive Gaussian noise with scale ``alpha * sigma_c`` (where +``sigma_c = std(X_t[c, observed])`` and ``alpha = noise_scale``) restricted to +row ``c`` of the input. Only row ``c`` differs from ``X_t``, so the Frobenius +norm reduces to a row-vector L2 norm: + + || X_t^(c, eps) - X_t ||_F = || epsilon ||_2 = || x_t'[c, :] - x_t[c, :] ||_2 . + +The per-channel Lipschitz-style ratio is + + R_t^(c) = || embed(X_t^(c, eps)) - embed(X_t) ||_2 / ( || X_t^(c, eps) - X_t ||_F + eta ), + +where ``eta = 1e-12`` is a numerical floor on the denominator. We aggregate +over ``n_trials`` perturbation trials per channel and per time index, then +report mean / max / p50 / p95 per channel. + +**Sanity invariance.** If the embedding is channel-independent -- +``embed(X) = sum_c phi_c(x_c)`` for some per-channel maps ``phi_c`` -- then +perturbing only row ``c`` changes ``embed`` by ``phi_c(x_c + n) - phi_c(x_c)`` +alone. The ratio ``R_t^(c)`` therefore probes the local Lipschitz constant of +``phi_c`` in isolation. In the limit of vanishing noise scale, +``R_t^(c) -> ||J_{phi_c}||_op``. For the linear channel-independent mock model +the ratio is *exactly* ``||W^c||_op`` of that channel's projection -- this is +the invariance checked by +``test_channel_independent_model_recovers_jacobian_norm`` in the test suite. + +Cost summary +============ + +* :func:`compute_per_channel_embedding_stability`: + ``n_trials * C`` embed calls per time index, ``+1`` baseline embed call. + All batched into one forward pass per time index via ``_embed_windows_batched``. +""" + +from dataclasses import dataclass + +import numpy as np +import torch + +from sdm_client.explain._attribution.channel_flow import _embed_windows_batched +from sdm_client.explain._attribution.interpretability import ( + Array, + ForecastModel, + _rolling_window_sources, + extract_latent_trajectory, +) + +# --------------------------------------------------------------------------- +# Reports +# --------------------------------------------------------------------------- + + +@dataclass(frozen=True) +class PerChannelEmbeddingStabilityReport: + """Per-channel result of the empirical embedding stability test. + + Shapes (with ``C`` input channels): + + * ``lip_ratio_mean``, ``lip_ratio_max``, ``lip_ratio_p50``, ``lip_ratio_p95``: + ``[C]`` -- aggregates over the ratios collected for that channel. + * ``n_trials_per_channel``: ``[C]`` -- number of perturbation trials that + contributed a finite ratio for that channel (may differ across channels + if some perturbations were skipped, e.g. a fully-zero noise draw on a + constant channel). + * ``n_unique_windows``: ``int`` -- count of distinct time indices that + contributed to at least one channel's ratio set. + * ``step_delta_norm_mean``: ``float`` -- mean ``||Z_{t+1} - Z_t||`` on the + unperturbed trajectory (a v1-style reference scale; identical to the + scalar returned by :func:`compute_embedding_stability`). + """ + + lip_ratio_mean: Array # [C] + lip_ratio_max: Array # [C] + lip_ratio_p50: Array # [C] + lip_ratio_p95: Array # [C] + n_trials_per_channel: Array # [C], int + n_unique_windows: int + step_delta_norm_mean: float + n_channels: int + + +# --------------------------------------------------------------------------- +# Shared helpers +# --------------------------------------------------------------------------- + + +def _select_time_indices( + *, + seq_len: int, + T: int, + n_trials: int, + rng: np.random.Generator, + time_indices: Array | None = None, +) -> np.ndarray: + """Mirror the sampling discipline used in v1 :func:`compute_embedding_stability`. + + Prefers indices ``[seq_len - 1, T)`` (full-window region) and repeats with + a shuffle if the candidate pool is smaller than ``n_trials``. Different + perturbation seeds across the repeats keep the trials statistically + distinct even when the underlying windows are reused. + """ + if time_indices is not None: + return np.asarray(time_indices, dtype=np.int64).reshape(-1) + candidates = np.arange(seq_len - 1, T, dtype=np.int64) + if len(candidates) == 0: + candidates = np.arange(T, dtype=np.int64) + if len(candidates) >= n_trials: + return rng.choice(candidates, size=n_trials, replace=False) + n_repeats = int(np.ceil(n_trials / len(candidates))) + out = np.tile(candidates, n_repeats)[:n_trials] + rng.shuffle(out) + return out + + +def _per_channel_std(window_cl: Array, win_mask: Array) -> Array: + """Per-channel std of ``window_cl[:, observed]``. + + Channels with std ``< 1e-8`` (numerically constant on the observed slice) + fall back to ``1.0`` to match the v1 convention -- they get the *raw* + noise scale and we measure ``embed`` sensitivity to that absolute scale + rather than to a normalised-by-zero scale. + """ + obs = np.asarray(win_mask, dtype=bool) + if not np.any(obs): + return np.ones((window_cl.shape[0],), dtype=np.float32) + std = np.std(window_cl[:, obs], axis=1).astype(np.float32, copy=False) + std = np.where(std < 1e-8, np.float32(1.0), std) + return std + + +# --------------------------------------------------------------------------- +# Per-channel embedding stability +# --------------------------------------------------------------------------- + + +@torch.no_grad() +def compute_per_channel_embedding_stability( + model: ForecastModel, + series_ct: Array, # [C, T] + *, + seq_len: int, + input_mask_t: Array | None = None, + device: torch.device, + n_trials: int = 30, + noise_scale: float = 0.01, + time_indices: Array | None = None, + batch_size: int = 16, + trajectory_batch_size: int = 32, + seed: int = 42, +) -> PerChannelEmbeddingStabilityReport: + """Channel-wise Lipschitz-style stability test. + + For each channel ``c``, perturbs only row ``c`` of the input window and + measures the ratio ``|| embed(X') - embed(X) ||_2 / || X' - X ||_F`` + averaged over ``n_trials`` perturbation trials. The result is the v2 + feature-axis analogue of :func:`compute_embedding_stability` (which + perturbs all channels jointly and returns a single scalar). + + Args: + model: forecast model exposing the ``embed`` interface. + series_ct: ``[C, T]`` series; only the trailing time indices matter. + seq_len: context length ``L`` of the model. + input_mask_t: optional ``[T]`` observed-mask for the series. + device: torch device for the embed calls. + n_trials: number of perturbation trials *per channel and per time + index*. Total perturbation embeds = ``n_trials * |time_indices| * C``. + noise_scale: noise amplitude as a fraction of per-channel std. + time_indices: optional explicit ``[T_idx]`` time-index list. If None, + samples ``n_trials`` indices from the full-window region. + batch_size: chunk size for batched embed of perturbation windows. + trajectory_batch_size: chunk size for the reference-trajectory embed + (separate budget because the reference is computed once over the + full series). + seed: RNG seed for the per-channel noise. + + Returns: + :class:`PerChannelEmbeddingStabilityReport` with shape-``[C]`` summaries. + """ + xw_view, m_view, T = _rolling_window_sources( + series_ct, seq_len=seq_len, input_mask_t=input_mask_t + ) + if T < 2: + raise ValueError( + f'Need at least 2 time steps for per-channel stability test, got T={T}' + ) + C = int(np.asarray(series_ct).shape[0]) + L = int(seq_len) + + rng = np.random.default_rng(int(seed)) + sampled_indices = _select_time_indices( + seq_len=L, + T=T, + n_trials=int(n_trials), + rng=rng, + time_indices=time_indices, + ) + sampled_indices = np.unique(np.clip(sampled_indices, 0, T - 1)) + if sampled_indices.size == 0: + raise ValueError( + 'No valid time indices to sample for per-channel stability.' + ) + + # Collected ratios are gathered into per-channel lists across all + # (time_index, trial) draws so the aggregation is purely vectorised at the + # end. Each accepted draw contributes one float per channel. + per_channel_ratios: list[list[float]] = [[] for _ in range(C)] + n_unique = 0 + + # Number of trials per time index: keep at least 1; rotate noise seeds so + # the trials are not identical across time indices. + trials_per_index = max(1, int(np.ceil(n_trials / sampled_indices.size))) + + for t_idx, t in enumerate(sampled_indices): + win = np.asarray(xw_view[int(t)], dtype=np.float32) # [C, L] + mask = np.asarray(m_view[int(t)], dtype=np.int64) # [L] + obs_mask = mask.astype(bool) + if not np.any(obs_mask): + continue + + std_per_chan = _per_channel_std(win, mask) # [C] + win_mask_f = mask.astype(np.float32, copy=False) # [L] + + # Build a [1 + C * trials_per_index, C, L] probe stack: + # slot 0 = baseline; slots 1..C, C+1..2C, ... = trial-major, + # channel-minor perturbations (channel c of trial r at slot 1 + r*C + c). + n_perturbs = C * trials_per_index + stack = np.empty((1 + n_perturbs, C, L), dtype=np.float32) + stack[0] = win + + # Draw noise once per (trial, channel) at scale alpha * std_c restricted + # to observed positions. Padded positions contribute 0 to both + # numerator (embed sees the same masked input) and denominator (we + # measure Frobenius norm of x' - x, which is zero in masked positions). + noise_unit = rng.standard_normal((trials_per_index, C, L)).astype( + np.float32 + ) + # Apply the observation mask (zero perturbation where mask=0). + noise_unit = noise_unit * win_mask_f[None, None, :] + # Per-channel scale. + noise_unit *= (float(noise_scale) * std_per_chan)[ + None, :, None + ] # [r, C, L] + + # Frobenius norm equals the row-c L2 norm of the per-channel noise. + # Drop trials where every channel ended up with a numerically zero + # noise vector (e.g. constant + tiny noise_scale on a fully-padded + # window) -- they would inject inf into the ratio aggregation. + dx_norm = np.linalg.norm( + noise_unit.reshape(trials_per_index * C, L), ord=2, axis=1 + ).astype(np.float32) + dx_norm = dx_norm.reshape(trials_per_index, C) + + # Materialise perturbed windows: copy ``win`` then overwrite row c with + # ``win[c] + noise[r, c, :]``. + perturbed = np.broadcast_to( + win[None, None, :, :], (trials_per_index, C, C, L) + ).copy() + chan_idx = np.arange(C) + perturbed[:, chan_idx, chan_idx, :] = ( + win[chan_idx, :][None, :, :] + noise_unit + ) # [r, C, L] + + # Flatten trial/channel dims into the leading "slot" axis. + stack[1:] = perturbed.reshape(n_perturbs, C, L) + masks_stack = np.broadcast_to(mask[None, :], (1 + n_perturbs, L)).copy() + + z = _embed_windows_batched( + model, + stack, + masks_stack, + device=device, + batch_size=int(batch_size), + ) # [1 + n_perturbs, D] + z_base = z[0] # [D] + z_pert = z[1:].reshape(trials_per_index, C, -1) # [r, C, D] + + dz_norm = np.linalg.norm( + z_pert - z_base[None, None, :], ord=2, axis=2 + ).astype(np.float32) # [r, C] + + # Aggregate per-channel ratios. Skip (trial, channel) cells where the + # noise vector was numerically zero. + valid_mask = dx_norm > 1e-12 + eps = np.float32(1e-12) + ratios = dz_norm / (dx_norm + eps) + for c in range(C): + valid_c = valid_mask[:, c] + if not np.any(valid_c): + continue + for r_val in ratios[valid_c, c]: + per_channel_ratios[c].append(float(r_val)) + n_unique += 1 + + # Reference scale (matches v1 step_delta_norm_mean) - computed once over + # the full series. Failure-tolerant: if the trajectory is degenerate, fall + # back to NaN. + try: + Z_full = extract_latent_trajectory( + model, + series_ct, + seq_len=L, + input_mask_t=input_mask_t, + device=device, + batch_size=int(trajectory_batch_size), + ) + if Z_full.shape[0] >= 2: + step_deltas = np.linalg.norm( + Z_full[1:] - Z_full[:-1], ord=2, axis=1 + ) + step_delta_mean = float(np.nanmean(step_deltas)) + else: + step_delta_mean = float('nan') + except Exception: + step_delta_mean = float('nan') + + lip_mean = np.full((C,), np.nan, dtype=np.float32) + lip_max = np.full((C,), np.nan, dtype=np.float32) + lip_p50 = np.full((C,), np.nan, dtype=np.float32) + lip_p95 = np.full((C,), np.nan, dtype=np.float32) + n_per_chan = np.zeros((C,), dtype=np.int64) + for c in range(C): + if not per_channel_ratios[c]: + continue + arr = np.asarray(per_channel_ratios[c], dtype=np.float64) + finite = arr[np.isfinite(arr)] + if finite.size == 0: + continue + lip_mean[c] = float(np.mean(finite)) + lip_max[c] = float(np.max(finite)) + lip_p50[c] = float(np.percentile(finite, 50)) + lip_p95[c] = float(np.percentile(finite, 95)) + n_per_chan[c] = int(finite.size) + + return PerChannelEmbeddingStabilityReport( + lip_ratio_mean=lip_mean, + lip_ratio_max=lip_max, + lip_ratio_p50=lip_p50, + lip_ratio_p95=lip_p95, + n_trials_per_channel=n_per_chan, + n_unique_windows=int(n_unique), + step_delta_norm_mean=step_delta_mean, + n_channels=int(C), + ) + + +__all__ = [ + 'PerChannelEmbeddingStabilityReport', + 'compute_per_channel_embedding_stability', +] diff --git a/packages/structured-data-models-client/src/sdm_client/explain/_attribution/integrated_gradients.py b/packages/structured-data-models-client/src/sdm_client/explain/_attribution/integrated_gradients.py new file mode 100644 index 000000000..9b2689921 --- /dev/null +++ b/packages/structured-data-models-client/src/sdm_client/explain/_attribution/integrated_gradients.py @@ -0,0 +1,340 @@ +# SPDX-FileCopyrightText: Copyright (c) 2026, NVIDIA CORPORATION & AFFILIATES. +# All rights reserved. +# SPDX-License-Identifier: Apache-2.0 + +# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. +# SPDX-License-Identifier: Apache-2.0 + +from __future__ import annotations + +"""Integrated Gradients / Expected Gradients over the embedding layer. + +What this measures +================== +This is a *general*, model-agnostic interpretability primitive. Given any model +that encodes a time-series context window into an embedding, + + e = Enc(x) , x in R^{...} (the input window), e in R^{D} (the encoding), + +it measures the effect of the input on the encoding by **accumulating the +gradients of the embedding layer along a straight-line path from a baseline to +the input** (Integrated Gradients; Sundararajan et al., 2017): + + A_i = (x_i - x0_i) * \\int_0^1 d g(Enc(x0 + a*(x - x0))) / d x_i da , + +where ``g`` reduces the embedding vector to a scalar (default: its L2 norm) and +``x0`` is the baseline (default: zeros, i.e. the "absence of input"). The path +``x0 -> x`` progressively *imputes* the input values into the encoder, and the +accumulated gradient quantifies how strongly those values drive the encoding. + +By the completeness axiom, + + sum_i A_i = g(Enc(x)) - g(Enc(x0)) , + +which is reported as a convergence diagnostic. + +Baseline choice (important for instance-normalized encoders) +============================================================ +Instance normalization ``(x - mean) / std`` is invariant to shifting and scaling +the input. A straight-line path from a *zero or constant* baseline to ``x`` can +therefore become the same normalized series at every step, making the embedding +flat along the path and degrading IG completeness at the degenerate endpoint. +The default white-noise baseline is matched to the input's global mean/std, which +breaks that invariance. Averaging several such baselines (``n_baselines > 1``) +produces the Expected-Gradients estimator and reduces variance. + +Design +====== +* **Model-agnostic.** The core depends only on a differentiable + ``embed_fn: Tensor[n, *feat] -> Tensor[n, D]`` that maps a *batch* of inputs + to a batch of embeddings. Nothing here knows about channels, patches, + missingness, or any specific architecture. +* **Real gradients.** Unlike the gradient-free probes elsewhere in + this package, this uses autograd: interpolation points are pushed through the + encoder in one or more batches and ``torch.autograd.grad`` yields the + gradients with respect to the input path only (each step's embedding depends + only on its own row). +* **Global, not per-axis.** The headline output is a single scalar effect over + the whole embedding layer plus a saliency map in the input's own shape. No + channel/feature-axis decomposition is imposed by this primitive. + +Cost: one forward/gradient pass per interpolation chunk. +""" + +import warnings +from collections.abc import Callable +from dataclasses import dataclass +from typing import Literal + +import numpy as np +import torch + +Array = np.ndarray +EmbedFn = Callable[[torch.Tensor], torch.Tensor] +Reduce = Literal['l2', 'sum', 'mean'] +BaselineMode = Literal['noise', 'zero', 'mean'] + + +@dataclass(frozen=True) +class EmbeddingAttribution: + """Result of Integrated Gradients over the embedding layer. + + * ``attribution``: per-input-element Integrated Gradients, in the input's + own shape (a model-agnostic saliency map over the context window). + * ``overall_effect``: ``sum_i attribution_i`` -- the net signed effect of + the input on the (reduced) embedding. Equal to ``embedding_delta`` up to + the Riemann approximation error. + * ``abs_effect``: ``sum_i |attribution_i|`` -- total saliency mass, a + magnitude summary that does not cancel across positions. + * ``embedding_delta``: ``g(Enc(x)) - g(Enc(x0))`` measured directly. + * ``embedding_delta_abs_mean``: mean absolute endpoint change across + Expected-Gradients baselines. This is the stable scale used below. + * ``convergence_delta``: ``|overall_effect - embedding_delta| / + (embedding_delta_abs_mean + eps)``; the Integrated-Gradients completeness + residual (-> 0 as ``n_steps`` grows). Using ``|mean(delta)|`` in the + denominator, as the old implementation did, explodes whenever endpoint + changes from different noise baselines cancel. + """ + + attribution: Array + overall_effect: float + abs_effect: float + embedding_delta: float + embedding_delta_abs_mean: float + convergence_delta: float + n_steps: int + n_baselines: int + baseline: str + reduce: str + embedding_dim: int + + +def _reduce_embedding(emb: torch.Tensor, reduce: Reduce) -> torch.Tensor: + """Reduce an ``[n, D]`` (or ``[n, ...]``) embedding batch to a scalar per row.""" + flat = emb.reshape(emb.shape[0], -1) + if reduce == 'l2': + return torch.linalg.vector_norm(flat, dim=1) + if reduce == 'sum': + return flat.sum(dim=1) + if reduce == 'mean': + return flat.mean(dim=1) + raise ValueError( + f"Unknown reduce {reduce!r}; expected 'l2' | 'sum' | 'mean'." + ) + + +def _ig_single( + embed_fn: EmbedFn, + x_t: torch.Tensor, + x0: torch.Tensor, + *, + n_steps: int, + reduce: Reduce, + internal_batch_size: int | None = None, +) -> tuple[Array, float, int]: + """One Integrated-Gradients pass for a fixed baseline ``x0``. + + Returns ``(attribution, embedding_delta, embedding_dim)``. + """ + delta = x_t - x0 # [*feat] + dev = x_t.device + + chunk = int(internal_batch_size or n_steps) + if chunk < 1: + raise ValueError( + f'internal_batch_size must be >= 1 when provided, got {internal_batch_size}' + ) + chunk = min(chunk, int(n_steps)) + + grad_sum = torch.zeros_like(x_t) + expand_prefix = (1,) * x_t.ndim + for start in range(0, int(n_steps), chunk): + stop = min(int(n_steps), start + chunk) + count = stop - start + + # Midpoint Riemann nodes for this chunk. + alphas = ( + torch.arange(start, stop, device=dev, dtype=torch.float32) + 0.5 + ) / int(n_steps) + x_interp = x0.unsqueeze(0) + alphas.reshape( + (count,) + expand_prefix + ) * delta.unsqueeze(0) + x_interp = x_interp.clone().requires_grad_(True) + + with torch.enable_grad(): + emb = embed_fn(x_interp) # [count, D] + if emb.shape[0] != count: + raise RuntimeError( + f'embed_fn must preserve the leading batch dim: got {emb.shape[0]} rows for {count} inputs.' + ) + g = _reduce_embedding(emb, reduce) # [count] + # Request only input-path gradients. Using .backward() here would + # also materialize parameter gradients for large encoders and keep + # them resident across integration batches. + grad = torch.autograd.grad( + g.sum(), x_interp, retain_graph=False, create_graph=False + )[0] + + grad_sum += grad.detach().sum(dim=0) + del emb, g, grad, x_interp + + avg_grad = grad_sum / float(n_steps) # [*feat] + attribution = (delta * avg_grad).detach().cpu().numpy().astype(np.float32) + + with torch.no_grad(): + ends = torch.stack([x0, x_t], dim=0) + emb_ends = embed_fn(ends) + g_ends = _reduce_embedding(emb_ends, reduce) + emb_dim = int(emb_ends.reshape(emb_ends.shape[0], -1).shape[1]) + embedding_delta = float((g_ends[1] - g_ends[0]).item()) + return attribution, embedding_delta, emb_dim + + +def integrated_gradients_embedding( + embed_fn: EmbedFn, + x: Array | torch.Tensor, + *, + baseline: BaselineMode | Array | torch.Tensor | float = 'noise', + n_steps: int = 64, + n_baselines: int = 1, + internal_batch_size: int | None = None, + reduce: Reduce = 'l2', + seed: int = 0, + device: torch.device | str | None = None, +) -> EmbeddingAttribution: + """Accumulate embedding-layer gradients along the baseline->input path. + + Args: + embed_fn: differentiable map from a *batch* of inputs ``[n, *feat]`` to a + batch of embeddings ``[n, D]`` (or any ``[n, ...]`` reduced to a + scalar per row). This callable is the only model-specific input. + x: a single input window, shape ``[*feat]`` (no batch dim). + baseline: path start. Either a mode string or an explicit reference: + + * ``"noise"`` (default) -- white noise matched to ``x``'s global + mean/std. Recommended for instance-normalized models; with + ``n_baselines > 1`` this becomes the Expected-Gradients estimator. + * ``"zero"`` / ``"mean"`` / a constant float -- a *constant* baseline. + **Degenerate for instance-normalized backbones** (emits a warning). + * an array shaped like ``x`` -- an explicit baseline. + n_steps: number of Riemann (midpoint) steps for the path integral. + n_baselines: number of independent ``"noise"`` baselines to average over + (Expected Gradients). Ignored (forced to 1) for explicit/constant + baselines. + internal_batch_size: maximum number of interpolation points to embed at + once. ``None`` keeps the original one-batch behavior; smaller values + trade a little runtime for much lower activation memory. + reduce: how the embedding vector is reduced to the scalar objective + ``g`` -- ``'l2'`` (default), ``'sum'`` or ``'mean'``. + seed: RNG seed for the noise baseline(s). + device: device for the computation; defaults to ``x``'s device (or CPU). + + Returns: + :class:`EmbeddingAttribution`. + """ + if n_steps < 1: + raise ValueError(f'n_steps must be >= 1, got {n_steps}') + if n_baselines < 1: + raise ValueError(f'n_baselines must be >= 1, got {n_baselines}') + + if isinstance(x, torch.Tensor): + dev = torch.device(device) if device is not None else x.device + x_t = x.detach().to(device=dev, dtype=torch.float32) + else: + dev = ( + torch.device(device) if device is not None else torch.device('cpu') + ) + x_t = torch.as_tensor(np.asarray(x, dtype=np.float32), device=dev) + + # Build the list of baseline tensors. + baselines: list[torch.Tensor] = [] + if isinstance(baseline, str) and baseline == 'noise': + mu = float(x_t.mean().item()) + sigma = float(x_t.std().item()) + sigma = sigma if sigma > 1e-8 else 1.0 + rng = np.random.default_rng(seed) + for _ in range(n_baselines): + noise = rng.standard_normal(tuple(x_t.shape)).astype(np.float32) + baselines.append(torch.as_tensor(mu + sigma * noise, device=dev)) + baseline_name = 'noise' + else: + if n_baselines != 1: + warnings.warn( + "n_baselines is ignored for non-'noise' baselines; using 1.", + stacklevel=2, + ) + if isinstance(baseline, str) and baseline in ('zero', 'mean'): + const = 0.0 if baseline == 'zero' else float(x_t.mean().item()) + baselines.append(torch.full_like(x_t, const)) + baseline_name = baseline + warnings.warn( + f"A constant '{baseline}' baseline is degenerate for instance-normalized models " + "(scale/shift invariance) and typically yields ~0 attribution; prefer baseline='noise'.", + stacklevel=2, + ) + elif isinstance(baseline, (int, float)): + baselines.append(torch.full_like(x_t, float(baseline))) + baseline_name = f'const({float(baseline):g})' + warnings.warn( + "A constant baseline is degenerate for instance-normalized models; prefer baseline='noise'.", + stacklevel=2, + ) + else: + x0 = ( + baseline.detach().to(device=dev, dtype=torch.float32) + if isinstance(baseline, torch.Tensor) + else torch.as_tensor( + np.asarray(baseline, dtype=np.float32), device=dev + ) + ) + if x0.shape != x_t.shape: + raise ValueError( + f'baseline shape {tuple(x0.shape)} must match x shape {tuple(x_t.shape)}' + ) + baselines.append(x0) + baseline_name = 'array' + + attrs: list[Array] = [] + deltas: list[float] = [] + emb_dim = 0 + for x0 in baselines: + attr, edelta, emb_dim = _ig_single( + embed_fn, + x_t, + x0, + n_steps=n_steps, + reduce=reduce, + internal_batch_size=internal_batch_size, + ) + attrs.append(attr) + deltas.append(edelta) + + attribution = np.mean(np.stack(attrs, axis=0), axis=0).astype(np.float32) + embedding_delta = float(np.mean(deltas)) + embedding_delta_abs_mean = float(np.mean(np.abs(deltas))) + overall = float(attribution.sum()) + abs_effect = float(np.abs(attribution).sum()) + eps = 1e-12 + convergence = float( + abs(overall - embedding_delta) / (embedding_delta_abs_mean + eps) + ) + + return EmbeddingAttribution( + attribution=attribution, + overall_effect=overall, + abs_effect=abs_effect, + embedding_delta=embedding_delta, + embedding_delta_abs_mean=embedding_delta_abs_mean, + convergence_delta=convergence, + n_steps=int(n_steps), + n_baselines=len(baselines), + baseline=baseline_name, + reduce=str(reduce), + embedding_dim=int(emb_dim), + ) + + +__all__ = [ + 'EmbeddingAttribution', + 'integrated_gradients_embedding', +] diff --git a/packages/structured-data-models-client/src/sdm_client/explain/_attribution/interpretability.py b/packages/structured-data-models-client/src/sdm_client/explain/_attribution/interpretability.py new file mode 100644 index 000000000..2071af33a --- /dev/null +++ b/packages/structured-data-models-client/src/sdm_client/explain/_attribution/interpretability.py @@ -0,0 +1,1709 @@ +# SPDX-FileCopyrightText: Copyright (c) 2026, NVIDIA CORPORATION & AFFILIATES. +# All rights reserved. +# SPDX-License-Identifier: Apache-2.0 + +# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. +# SPDX-License-Identifier: Apache-2.0 + +from __future__ import annotations + +""" +Model-agnostic interpretability utilities for time series forecasting. + +Pipeline structure (latent interface -> semantic flow -> lag x horizon matrix -> +local surrogates), implemented as a stable, model-agnostic approximation: + - Build a latent trajectory by embedding a rolling window at each time index. + - Define a scalar "flow magnitude" per step from consecutive latent states + (delta norm + optional scale term). + - Aggregate these magnitudes into a lag x horizon influence matrix and + normalize per horizon via softmax. + - Fit horizon-specific *weighted sparse linear* surrogates using + time-series-preserving perturbations. + +The result is horizon-resolved, temporally continuous, model-agnostic +explanations without retraining the forecaster. + +Stability / quality notes: +- The pipeline assumes temporal smoothness of the embedding: small input + changes should yield proportionally small latent changes. If not, flow + magnitudes may reflect representation noise. +- Use SemanticFlowConfig.smooth_latent_alpha for optional temporal smoothing + of Z. +- The latent trajectory is built over [history; forecast]. The forecast + segment is out-of-distribution (model-generated). Flow there can be noisier; + use flow_ratio_forecast_vs_history and flow_variance_ratio_forecast_vs_history + on ForecastExplanation to gauge whether attributions that depend on the + extended segment are likely to be volatile (ratio > 1 suggests more noise). +""" + +import warnings +from dataclasses import dataclass +from typing import TYPE_CHECKING, Any, Literal, Protocol + +import numpy as np +import torch + +if TYPE_CHECKING: + from sdm_client.explain._attribution.channel_flow import ChannelFlowConfig + +Array = np.ndarray + + +class ForecastModel(Protocol): + """Minimal protocol for models exposing forecast and embedding interfaces.""" + + def __call__(self, *, x_enc: torch.Tensor, input_mask: torch.Tensor) -> Any: + """Forward pass returning an object with a `.forecast` tensor [B, C, H].""" + + def embed(self, *, x_enc: torch.Tensor, input_mask: torch.Tensor) -> Any: + """Embedding pass returning an object with `.embeddings` tensor [B, D].""" + + +@dataclass(frozen=True) +class SemanticFlowConfig: + """ + Configuration for semantic-flow computation. + + Args: + flow_kind: + - 'delta_l2': m_t = ||z_{t+1} - z_t||_2 (latent displacement; no output sensitivity). + - 'output_aware': m_t = |(∂y/∂Z_t)(Z_{t+1}-Z_t)| (first-order forecast effect). + Requires dy_dZ in compute_semantic_flow_magnitudes. + scale_weight: + Optional extra term based on latent norm changes (delta_l2 only): + scale_weight * clip(|log(||z_{t+1}|| / ||z_t||)|, 0, 10) + The log-ratio term is capped at 10 to limit the influence of extreme norm jumps. + smooth_latent_alpha: + If in (0, 1), smooth the latent trajectory with EMA before computing flow: + Z_smooth[t] = alpha * Z_smooth[t-1] + (1 - alpha) * Z[t]. + Can improve robustness when embeddings are noisy (Lipschitz-like regularization). + output_aware_aggregation: + When flow_kind is 'output_aware', how to aggregate over horizons if dy_dZ has shape (T, H, D): + 'l2' => m_t = sqrt(sum_h (grad_t_h @ delta_t)^2), 'sum' => m_t = sum_h |grad_t_h @ delta_t|. + eps: + Numerical stability. + """ + + flow_kind: Literal['delta_l2', 'output_aware'] = 'delta_l2' + scale_weight: float = 0.0 + smooth_latent_alpha: float = 0.0 + output_aware_aggregation: Literal['l2', 'sum'] = 'l2' + eps: float = 1e-12 + + +@dataclass(frozen=True) +class TrajectoryStabilityReport: + """ + Summary of temporal smoothness for a latent trajectory. + + The trajectory is centered by a reference latent state and optionally scaled by the + per-dimension standard deviation of the reference segment. Lower zero-crossing, + direction-flip, and relative-jitter values indicate smoother latent evolution. + """ + + zero_crossing_rate_mean: float + zero_crossing_rate_p95: float + direction_flip_rate_mean: float + direction_flip_rate_p95: float + relative_jitter_mean: float + relative_jitter_p95: float + occupancy_positive_mean: float + occupancy_negative_mean: float + n_time_steps: int + n_dimensions: int + + +@dataclass(frozen=True) +class PerturbationConfig: + """ + Structure-preserving perturbations for local surrogates. + + block-bootstrap: resamples contiguous blocks to preserve local autocorrelation. + fourier-phase-preserving noise: keeps Fourier phase but perturbs amplitude mildly to preserve seasonality. + """ + + n_samples: int = 128 + block_len: int = 32 + fourier_amp_sigma: float = 0.05 + mix_original: float = 0.25 # 0 = fully perturbed, 1 = fully original + seed: int = 13 + + +@dataclass(frozen=True) +class SurrogateConfig: + """ + Horizon-specific local surrogate settings. + + We fit a weighted L1-regularized linear model (ISTA) independently for each horizon h. + """ + + n_lags: int = 64 + l1_alpha: float = 5e-3 + distance_lambda: float = 1.0 + max_iter: int = 300 + tol: float = 1e-5 + + +@dataclass(frozen=True) +class ForecastExplanation: + """ + Explanation outputs. + + Shapes: + - baseline_forecast: [C, H] + - lag_horizon_scores: [K, H] (unnormalized, larger means more influence) + - lag_horizon_attributions: [K, H] (softmax-normalized over lags for each horizon) + - surrogate_coef: [C, H, P] (may be None if surrogates disabled; P = C * surrogate_n_lags) + - surrogate_intercept: [C, H] (may be None if surrogates disabled) + + Segment quality (forecast vs history): + - flow_ratio_forecast_vs_history: mean flow in forecast segment / mean flow in history. + >1 means the extended (OOD) segment is more volatile; attributions that weight by + flow in that region may be noisier. + - flow_variance_ratio_forecast_vs_history: variance of flow in forecast / variance in history. + - Set to None if segment split is invalid (e.g. too short). + + Additional diagnostics: + - curvature_ratio_forecast_vs_history: compares second-difference energy of Z in forecast vs history. + - latent_diag_mahalanobis_ratio_forecast_vs_history: compares a diagonal-Mahalanobis latent distance + in forecast vs history (OOD shift indicator). + + Feature-axis (v2) outputs (populated only when ``explain_forecast`` is + called with ``channel_axis=True``): + - per_channel_flow: [T-1, C] -- per-channel decomposition of latent + flow (phi_tau(c)). + - lag_channel_horizon_scores: [K, C, H] -- joint score tensor before + normalization. + - lag_channel_horizon_attributions: [K, C, H] -- softmax-normalized + joint lag x channel x horizon attribution. + - channel_horizon_attributions: [C, H] -- channel-marginal of the + joint attribution; suitable for feature-axis evaluations. + - channel_flow_method: which Jacobian estimator produced the above. + - channel_flow_residual_ratio_mean / _p95: trust-region diagnostic for + the Jacobian variant. ``|| Delta Z - sum_c Delta Z^(c) || / ||Delta Z||`` + averaged over transitions; lower is better. + """ + + baseline_forecast: Array + lag_horizon_scores: Array + lag_horizon_attributions: Array + flow_magnitudes: Array + latent_trajectory: Array + surrogate_coef: Array | None = None + surrogate_intercept: Array | None = None + surrogate_feature_layout: str | None = None + flow_ratio_forecast_vs_history: float | None = None + flow_variance_ratio_forecast_vs_history: float | None = None + curvature_ratio_forecast_vs_history: float | None = None + latent_diag_mahalanobis_ratio_forecast_vs_history: float | None = None + # v2 feature-axis outputs (None when channel_axis=False) + per_channel_flow: Array | None = None + lag_channel_horizon_scores: Array | None = None + lag_channel_horizon_attributions: Array | None = None + channel_horizon_attributions: Array | None = None + channel_flow_method: str | None = None + channel_flow_residual_ratio_mean: float | None = None + channel_flow_residual_ratio_p95: float | None = None + + +def _flow_segment_ratios( + flow_magnitudes: Array, # [T-1] + context_len: int, + forecast_horizon: int, + eps: float = 1e-12, +) -> tuple[float | None, float | None]: + """ + Compare flow in history vs forecast (OOD) segment to gauge attribution quality. + + The latent trajectory is built over [history; forecast]. Flow in the forecast segment + (windows that include model-generated future) can be noisier; higher ratio means + attributions that depend on that segment are more likely to be volatile. + + Returns: + (flow_ratio, variance_ratio): mean(flow_forecast)/mean(flow_history) and + var(flow_forecast)/var(flow_history). None if segment split is invalid. + """ + m = np.asarray(flow_magnitudes, dtype=np.float32) + m = np.where(np.isfinite(m), m, np.nan) + L = int(context_len) + H = int(forecast_horizon) + if L <= 0 or H <= 0 or m.shape[0] < L + H - 1: + return None, None + # History: transitions 0..L-2 (windows purely in history) + m_hist = m[0 : L - 1] + # Forecast: transitions L-1..L+H-2 (windows extending into forecast) + m_fcst = m[L - 1 : L + H - 1] + if m_hist.size == 0 or m_fcst.size == 0: + return None, None + mean_hist = float(np.nanmean(m_hist)) + eps + mean_fcst = float(np.nanmean(m_fcst)) + eps + flow_ratio = mean_fcst / mean_hist + var_hist = float(np.nanvar(m_hist)) + eps + var_fcst = float(np.nanvar(m_fcst)) + eps + var_ratio = var_fcst / var_hist + return flow_ratio, var_ratio + + +def _curvature_segment_ratio( + Z: Array, # [T, D] + context_len: int, + forecast_horizon: int, + eps: float = 1e-12, +) -> float | None: + """ + Curvature/jitter diagnostic: ratio of second-difference energy in forecast vs history. + + Define curvature per step: + c_t = ||Z_{t+2} - 2 Z_{t+1} + Z_t||_2, t=0..T-3. + + Returns: + mean(c in forecast segment) / mean(c in history segment), or None if invalid split. + """ + Z = np.asarray(Z, dtype=np.float32) + if Z.ndim != 2 or Z.shape[0] < 3: + return None + T = Z.shape[0] + L = int(context_len) + H = int(forecast_horizon) + if L <= 1 or H <= 0 or T < L + H: + return None + # second differences live on indices 0..T-3; segment boundary at latent index L-1. + dd = Z[2:] - 2.0 * Z[1:-1] + Z[:-2] # [T-2, D] + c = np.linalg.norm(dd, ord=2, axis=1) + c = np.where(np.isfinite(c), c, np.nan) + + # history curvature uses steps fully before boundary: t=0..(L-3) + c_hist = c[0 : max(0, L - 2)] + # forecast curvature uses steps starting at boundary: t=(L-2)..(L+H-3) (clipped) + c_fcst = c[max(0, L - 2) : min(c.shape[0], L + H - 2)] + if c_hist.size == 0 or c_fcst.size == 0: + return None + return (float(np.nanmean(c_fcst)) + eps) / (float(np.nanmean(c_hist)) + eps) + + +def _latent_diag_mahalanobis_ratio( + Z: Array, # [T, D] + context_len: int, + forecast_horizon: int, + eps: float = 1e-12, +) -> float | None: + """ + OOD shift diagnostic: compare diagonal-Mahalanobis distance of latents in forecast vs history. + + Fit (mu, var) on history latents Z[0:L], then compute: + d2(z) = sum_i ( (z_i - mu_i)^2 / (var_i + eps) ) + Return mean(d2 in forecast latents) / mean(d2 in history latents). + """ + Z = np.asarray(Z, dtype=np.float32) + if Z.ndim != 2: + return None + T = Z.shape[0] + L = int(context_len) + H = int(forecast_horizon) + if L <= 1 or H <= 0 or T < L + H: + return None + + Z_hist = Z[:L] + Z_fcst = Z[L : L + H] + if Z_hist.shape[0] < 2 or Z_fcst.shape[0] < 1: + return None + + mu = np.nanmean(np.where(np.isfinite(Z_hist), Z_hist, np.nan), axis=0) + var = np.nanvar(np.where(np.isfinite(Z_hist), Z_hist, np.nan), axis=0) + var = np.where(np.isfinite(var) & (var > 1e-8), var, 1.0).astype(np.float32) + + def d2(A: Array) -> Array: + A = np.where(np.isfinite(A), A, np.nan) + return np.nansum( + ((A - mu[None, :]) ** 2) / (var[None, :] + eps), axis=1 + ) + + d2_hist = d2(Z_hist) + d2_fcst = d2(Z_fcst) + if not np.isfinite(d2_hist).any() or not np.isfinite(d2_fcst).any(): + return None + return (float(np.nanmean(d2_fcst)) + eps) / ( + float(np.nanmean(d2_hist)) + eps + ) + + +def _softmax(x: Array, axis: int = 0, eps: float = 1e-12) -> Array: + x = x - np.max(x, axis=axis, keepdims=True) + ex = np.exp(x) + den = np.sum(ex, axis=axis, keepdims=True) + return ex / np.maximum(den, eps) + + +def _as_numpy(x: Any) -> Array: + if isinstance(x, np.ndarray): + return x + if isinstance(x, torch.Tensor): + return x.detach().cpu().numpy() + return np.asarray(x) + + +@torch.no_grad() +def _forecast_autoregressive( + model: ForecastModel, + x_enc: torch.Tensor, + input_mask: torch.Tensor, + *, + model_horizon: int, + target_horizon: int, +) -> Array: + """ + Autoregressive forecasting (batched) to extend beyond model's native horizon. + + Returns: numpy array [B, C, target_horizon] + """ + if target_horizon <= 0: + raise ValueError('target_horizon must be positive') + if model_horizon <= 0: + raise ValueError('model_horizon must be positive') + + B, C, seq_len = x_enc.shape + device = x_enc.device + + def _finite_forecast(value: Array, *, stage: str) -> Array: + value = np.asarray(value, dtype=np.float32) + if not np.isfinite(value).all(): + n_bad = int((~np.isfinite(value)).sum()) + raise FloatingPointError( + f'Model forecast produced {n_bad} non-finite value(s) during {stage}' + ) + return value + + if target_horizon <= model_horizon: + with torch.amp.autocast('cuda', enabled=device.type == 'cuda'): + out = model(x_enc=x_enc, input_mask=input_mask) + forecast = _as_numpy(out.forecast[:, :, :target_horizon]).astype( + np.float32, copy=False + ) + return _finite_forecast(forecast, stage='direct forecasting') + + num_iters = int(np.ceil(target_horizon / model_horizon)) + cur_x = x_enc.clone() + cur_mask = input_mask.clone() + preds_chunks: list[Array] = [] + remaining = target_horizon + + for _ in range(num_iters): + with torch.amp.autocast('cuda', enabled=device.type == 'cuda'): + out = model(x_enc=cur_x, input_mask=cur_mask) + chunk = out.forecast.detach() + if not bool(torch.isfinite(chunk).all()): + n_bad = int((~torch.isfinite(chunk)).sum().item()) + raise FloatingPointError( + f'Model forecast produced {n_bad} non-finite value(s) during autoregressive forecasting' + ) + steps = min(model_horizon, remaining) + chunk_trimmed = chunk[:, :, :steps] + preds_chunks.append( + chunk_trimmed.to(device='cpu', dtype=torch.float32).numpy() + ) + remaining -= steps + if remaining <= 0: + break + + extended = torch.cat([cur_x, chunk_trimmed], dim=2) + cur_x = extended[:, :, -seq_len:] + cur_mask = torch.ones(B, seq_len, dtype=cur_mask.dtype, device=device) + + return np.concatenate(preds_chunks, axis=2).astype(np.float32, copy=False) + + +def _channel_replacement_rows(arr_cl: Array, *, replacement: str) -> Array: + arr = np.asarray(arr_cl, dtype=np.float32) + C, L = arr.shape + if replacement == 'zero': + return np.zeros((C, L), dtype=np.float32) + if replacement == 'local_mean': + return np.repeat( + arr.mean(axis=1, keepdims=True).astype(np.float32), L, axis=1 + ) + raise ValueError(f'Unsupported replacement={replacement!r}') + + +def compute_target_channel_input_jacobian_importance( + model: ForecastModel, + *, + x_context_ct: Array, + input_mask_l: Array, + device: torch.device, + target_channel: int, + model_horizon: int, + forecast_horizon: int, + replacement: Literal['local_mean', 'zero'] = 'local_mean', + forecast_batch_size: int = 8, + finite_difference_scale: float = 0.1, + prefer_autograd: bool = True, +) -> Array: + """Target-specific directional replacement effect by channel and horizon.""" + arr = np.asarray(x_context_ct, dtype=np.float32) + if arr.ndim != 2: + raise ValueError(f'Expected x_context_ct [C,L], got {arr.shape}') + C, L = arr.shape + H = int(forecast_horizon) + target = int(target_channel) + if not (0 <= target < C): + raise ValueError(f'target_channel out of range for C={C}: {target}') + mask = np.asarray(input_mask_l, dtype=np.int64) + if mask.shape != (L,): + raise ValueError( + f'Expected input_mask_l shape {(L,)}, got {mask.shape}' + ) + + baseline = _channel_replacement_rows(arr, replacement=str(replacement)) + delta = arr - baseline + active_direction = np.any(np.abs(delta) > 1e-12, axis=1) + + if prefer_autograd: + delta_t = torch.from_numpy(delta[None]).to( + device=device, dtype=torch.float32 + ) + x_t = ( + torch.from_numpy(arr[None]) + .to(device=device, dtype=torch.float32) + .requires_grad_(True) + ) + m_t = torch.from_numpy(mask[None]).to(device=device, dtype=torch.long) + with torch.enable_grad(): + out = model(x_enc=x_t, input_mask=m_t) + forecast = out.forecast[:, target, :H] + if forecast.shape[-1] < H: + raise ValueError( + f'Model returned horizon={forecast.shape[-1]}, expected at least {H}' + ) + if forecast.requires_grad: + importance = np.zeros((C, H), dtype=np.float32) + input_is_connected = True + for h in range(H): + grad = torch.autograd.grad( + forecast[:, h].sum(), + x_t, + retain_graph=h < H - 1, + create_graph=False, + allow_unused=True, + )[0] + if grad is None: + input_is_connected = False + break + score_c = (grad * delta_t).sum(dim=-1).abs()[0] + active_t = torch.as_tensor( + active_direction, + dtype=torch.bool, + device=score_c.device, + ) + score_c = torch.where( + active_t, score_c, torch.zeros_like(score_c) + ) + importance[:, h] = ( + score_c.detach().cpu().numpy().astype(np.float32) + ) + if input_is_connected: + importance[target, :] = 0.0 + if not np.isfinite(importance).all(): + n_bad = int((~np.isfinite(importance)).sum()) + raise FloatingPointError( + f'Jacobian attribution produced {n_bad} non-finite value(s)' + ) + return importance.astype(np.float32, copy=False) + + eps = float(finite_difference_scale) + if not (0.0 < eps <= 1.0): + raise ValueError( + f'finite_difference_scale must be in (0, 1], got {finite_difference_scale}' + ) + importance = np.zeros((C, H), dtype=np.float32) + chans = [c for c in range(C) if c != target] + channel_batch = max(1, int(forecast_batch_size) // 2) + for start in range(0, len(chans), channel_batch): + chunk = chans[start : start + channel_batch] + stack = np.broadcast_to(arr[None], (2 * len(chunk), C, L)).copy() + for i, c in enumerate(chunk): + stack[i, c, :] = arr[c, :] - eps * delta[c, :] + stack[len(chunk) + i, c, :] = arr[c, :] + eps * delta[c, :] + masks = np.broadcast_to(mask[None], (2 * len(chunk), L)).copy() + xb = torch.from_numpy(stack).to(device=device, dtype=torch.float32) + mb = torch.from_numpy(masks).to(device=device, dtype=torch.long) + yb = _forecast_autoregressive( + model, + xb, + mb, + model_horizon=int(model_horizon), + target_horizon=H, + )[:, target, :] + yb = np.asarray(yb, dtype=np.float32) + effects = np.abs(yb[len(chunk) :] - yb[: len(chunk)]) / (2.0 * eps) + for i, c in enumerate(chunk): + importance[c, :] = effects[i] + if not np.isfinite(importance).all(): + n_bad = int((~np.isfinite(importance)).sum()) + raise FloatingPointError( + f'Finite-difference attribution produced {n_bad} non-finite value(s)' + ) + return importance.astype(np.float32, copy=False) + + +@torch.no_grad() +def _embed_batch( + model: ForecastModel, x_enc: torch.Tensor, input_mask: torch.Tensor +) -> Array: + out = model.embed(x_enc=x_enc, input_mask=input_mask) + if not hasattr(out, 'embeddings') or out.embeddings is None: + raise RuntimeError('model.embed(...) did not return `.embeddings`') + return _as_numpy(out.embeddings).astype(np.float32) + + +def _sliding_window_view( + a: Array, window_shape: int, *, axis: int = 0 +) -> Array: + try: + from numpy.lib.stride_tricks import sliding_window_view # type: ignore[attr-defined] + except Exception: + from numpy.lib.stride_tricks import as_strided + + def sliding_window_view( + a: Array, window_shape: int, *, axis: int = 0 + ) -> Array: + if axis != 0: + raise ValueError( + 'fallback sliding_window_view only supports axis=0' + ) + a = np.asarray(a) + n = a.shape[0] + w = int(window_shape) + if w <= 0 or w > n: + raise ValueError('invalid window_shape') + shape = (n - w + 1, w) + a.shape[1:] + strides = (a.strides[0],) + a.strides + return as_strided(a, shape=shape, strides=strides) + + return sliding_window_view(a, window_shape=window_shape, axis=axis) + + +def _rolling_window_sources( + series_ct: Array, # [C, T] + *, + seq_len: int, + input_mask_t: Array + | None = None, # [T] optional observed mask (1=real,0=pad/missing) +) -> tuple[Array, Array, int]: + """ + Prepare rolling-window views used to materialize batches on demand. + """ + if series_ct.ndim != 2: + raise ValueError(f'Expected series [C,T], got shape {series_ct.shape}') + _, T = series_ct.shape + L = int(seq_len) + if L <= 0: + raise ValueError('seq_len must be positive') + + mask_t = None + if input_mask_t is not None: + mask_t = np.asarray(input_mask_t, dtype=np.int64).reshape(-1) + if mask_t.shape != (T,): + raise ValueError( + f'Expected input_mask_t shape {(T,)}, got {mask_t.shape}' + ) + if T == 0: + C = int(series_ct.shape[0]) + return ( + np.zeros((0, C, L), dtype=np.float32), + np.zeros((0, L), dtype=np.int64), + 0, + ) + + x = np.asarray(series_ct, dtype=np.float32) + pad = L - 1 + if pad > 0: + x_pad = np.pad( + x, + ((0, 0), (pad, 0)), + mode='constant', + constant_values=np.float32(0.0), + ) + else: + x_pad = x + x_view = _sliding_window_view(x_pad, window_shape=L, axis=1) + xw_view = np.transpose(x_view, (1, 0, 2)) + + if mask_t is None: + mask_src = np.ones((T,), dtype=np.int64) + else: + mask_src = mask_t.astype(np.int64, copy=False) + if pad > 0: + mask_pad = np.pad( + mask_src, (pad, 0), mode='constant', constant_values=np.int64(0) + ) + else: + mask_pad = mask_src + m_view = _sliding_window_view(mask_pad, window_shape=L, axis=0) + return xw_view, m_view, T + + +def _rolling_window_batch( + xw_view: Array, + m_view: Array, + *, + start: int, + stop: int, +) -> tuple[Array, Array]: + """ + Build only the requested rolling windows [start:stop]. + + Returns sliced views when possible so callers can defer materialization until + they actually need contiguous/writable arrays (for example at torch conversion). + """ + start_i = max(0, int(start)) + stop_i = max(start_i, int(stop)) + batch = stop_i - start_i + C = int(xw_view.shape[1]) if xw_view.ndim >= 2 else 0 + L = int(xw_view.shape[2]) if xw_view.ndim >= 3 else 0 + if batch == 0: + return np.zeros((0, C, L), dtype=np.float32), np.zeros( + (0, L), dtype=np.int64 + ) + return ( + np.asarray(xw_view[start_i:stop_i], dtype=np.float32), + np.asarray(m_view[start_i:stop_i], dtype=np.int64), + ) + + +def _rolling_windows( + series_ct: Array, # [C, T] + *, + seq_len: int, + input_mask_t: Array + | None = None, # [T] optional observed mask (1=real,0=pad/missing) +) -> tuple[Array, Array]: + """ + Build rolling model-input windows for every time index. + + Returns: + x_windows: [T, C, seq_len] + masks: [T, seq_len] + """ + L = int(seq_len) + xw_view, m_view, T = _rolling_window_sources( + series_ct, seq_len=L, input_mask_t=input_mask_t + ) + if T == 0: + C = int(np.asarray(series_ct).shape[0]) + return np.zeros((0, C, L), dtype=np.float32), np.zeros( + (0, L), dtype=np.int64 + ) + x_batch, m_batch = _rolling_window_batch(xw_view, m_view, start=0, stop=T) + return np.ascontiguousarray(x_batch), np.ascontiguousarray(m_batch) + + +def extract_latent_trajectory( + model: ForecastModel, + series_ct: Array, # [C, T] + *, + seq_len: int, + input_mask_t: Array + | None = None, # [T] optional observed mask for the series + device: torch.device, + batch_size: int = 32, +) -> Array: + """ + Latent Representation Interface (model-agnostic): + - Builds a latent state Z_t for each time t by embedding the last `seq_len` values up to t. + + Returns: Z [T, D] + """ + xw_view, m_view, T = _rolling_window_sources( + series_ct, seq_len=seq_len, input_mask_t=input_mask_t + ) + if T == 0: + return np.zeros((0, 0), dtype=np.float32) + Z_chunks: list[Array] = [] + for i in range(0, T, batch_size): + x_batch, m_batch = _rolling_window_batch( + xw_view, m_view, start=i, stop=i + batch_size + ) + xb = torch.from_numpy(np.ascontiguousarray(x_batch)).to( + device=device, dtype=torch.float32 + ) + mb = torch.from_numpy(np.ascontiguousarray(m_batch)).to( + device=device, dtype=torch.long + ) + Z_chunks.append(_embed_batch(model, xb, mb)) + Z = np.concatenate(Z_chunks, axis=0) + if np.any(~np.isfinite(Z)): + warnings.warn( + 'Latent trajectory Z contains non-finite values (NaN/inf); replacing with 0 before downstream computation.', + UserWarning, + stacklevel=2, + ) + Z = np.nan_to_num(Z, nan=0.0, posinf=0.0, neginf=0.0).astype(np.float32) + return Z + + +def _signed_states(values_td: Array, *, deadband: float) -> np.ndarray: + states = np.zeros(values_td.shape, dtype=np.int8) + states[values_td > deadband] = 1 + states[values_td < -deadband] = -1 + return states + + +def _state_change_rate(states_td: np.ndarray) -> np.ndarray: + if states_td.ndim != 2: + raise ValueError(f'Expected states [T,D], got shape {states_td.shape}') + if states_td.shape[0] < 2: + return np.full((states_td.shape[1],), np.nan, dtype=np.float32) + prev = states_td[:-1] + cur = states_td[1:] + valid = (prev != 0) & (cur != 0) + changed = (prev != cur) & valid + denom = np.sum(valid, axis=0).astype(np.float32) + numer = np.sum(changed, axis=0).astype(np.float32) + out = np.full((states_td.shape[1],), np.nan, dtype=np.float32) + nonzero = denom > 0 + out[nonzero] = numer[nonzero] / denom[nonzero] + return out + + +def _safe_mean_and_p95(values_d: Array) -> tuple[float, float]: + vals = np.asarray(values_d, dtype=np.float32).reshape(-1) + finite = vals[np.isfinite(vals)] + if finite.size == 0: + return float('nan'), float('nan') + return float(np.mean(finite)), float(np.percentile(finite, 95)) + + +def summarize_trajectory_stability( + Z_td: Array, + *, + reference_mask_t: Array | None = None, + reference_mode: Literal['mean', 'median'] = 'mean', + normalize: bool = True, + zero_band: float = 0.05, + eps: float = 1e-8, +) -> TrajectoryStabilityReport: + """ + Quantify how often a latent trajectory oscillates around its reference state. + + We center each latent dimension by a reference vector, optionally divide by its + reference-segment standard deviation, then compute: + - zero-crossing rate: how often the trajectory changes sign around the reference + - direction-flip rate: how often consecutive step directions reverse + - relative jitter: mean absolute step size divided by mean absolute level + - occupancy: fraction of time spent above/below the centered reference + """ + Z = np.asarray(Z_td, dtype=np.float32) + if Z.ndim != 2: + raise ValueError( + f'Expected latent trajectory [T,D], got shape {Z.shape}' + ) + if Z.shape[0] < 2: + raise ValueError( + 'Need at least two latent states to summarize trajectory stability' + ) + if np.any(~np.isfinite(Z)): + warnings.warn( + 'Latent trajectory Z contains non-finite values (NaN/inf); replacing with 0 for trajectory stability.', + UserWarning, + stacklevel=2, + ) + Z = np.where(np.isfinite(Z), Z, 0.0).astype(np.float32) + + T, D = Z.shape + if reference_mask_t is None: + ref_mask = np.ones((T,), dtype=bool) + else: + ref_mask = np.asarray(reference_mask_t, dtype=bool).reshape(-1) + if ref_mask.shape != (T,): + raise ValueError( + f'Expected reference_mask_t shape {(T,)}, got {ref_mask.shape}' + ) + if not np.any(ref_mask): + ref_mask = np.ones((T,), dtype=bool) + Z_ref = Z[ref_mask] + + if reference_mode == 'mean': + center = np.mean(Z_ref, axis=0, dtype=np.float32) + else: + center = np.median(Z_ref, axis=0).astype(np.float32) + + Z_centered = Z - center[None, :] + if normalize: + scale = np.std(Z_ref, axis=0).astype(np.float32) + scale[scale < eps] = 1.0 + Z_centered = Z_centered / scale[None, :] + + states = _signed_states(Z_centered, deadband=float(zero_band)) + zero_crossing_rate_d = _state_change_rate(states) + + deltas = Z_centered[1:] - Z_centered[:-1] + delta_states = _signed_states(deltas, deadband=float(zero_band)) + direction_flip_rate_d = _state_change_rate(delta_states) + + level_mag = np.mean(np.abs(Z_centered), axis=0) + step_mag = np.mean(np.abs(deltas), axis=0) + relative_jitter_d = step_mag / (level_mag + float(eps)) + + return TrajectoryStabilityReport( + zero_crossing_rate_mean=_safe_mean_and_p95(zero_crossing_rate_d)[0], + zero_crossing_rate_p95=_safe_mean_and_p95(zero_crossing_rate_d)[1], + direction_flip_rate_mean=_safe_mean_and_p95(direction_flip_rate_d)[0], + direction_flip_rate_p95=_safe_mean_and_p95(direction_flip_rate_d)[1], + relative_jitter_mean=_safe_mean_and_p95(relative_jitter_d)[0], + relative_jitter_p95=_safe_mean_and_p95(relative_jitter_d)[1], + occupancy_positive_mean=float(np.mean(Z_centered > float(zero_band))), + occupancy_negative_mean=float(np.mean(Z_centered < -float(zero_band))), + n_time_steps=int(T), + n_dimensions=int(D), + ) + + +@torch.no_grad() +def compute_trajectory_stability( + model: ForecastModel, + series_ct: Array, # [C, T] + *, + seq_len: int, + input_mask_t: Array | None = None, + device: torch.device, + batch_size: int = 32, + reference_mode: Literal['mean', 'median'] = 'mean', + normalize: bool = True, + zero_band: float = 0.05, + eps: float = 1e-8, +) -> TrajectoryStabilityReport: + """ + Build the latent trajectory for a series and summarize its temporal smoothness. + """ + Z = extract_latent_trajectory( + model, + series_ct, + seq_len=seq_len, + input_mask_t=input_mask_t, + device=device, + batch_size=batch_size, + ) + return summarize_trajectory_stability( + Z, + reference_mask_t=input_mask_t, + reference_mode=reference_mode, + normalize=normalize, + zero_band=zero_band, + eps=eps, + ) + + +def _smooth_latent_trajectory(Z: Array, alpha: float) -> Array: + """ + EMA along time (returns new array): + Z_smooth[t] = alpha * Z_smooth[t-1] + (1-alpha) * Z[t] + with the first row unchanged. + + Uses a vectorized closed form for speed on large [T, D] arrays and falls + back to the sequential recurrence if alpha is so extreme that the power + scaling becomes numerically unstable. + """ + if Z.shape[0] < 2 or alpha <= 0 or alpha >= 1: + return Z + + out = np.asarray(Z, dtype=np.float32).copy() + T = out.shape[0] + alpha_f = float(alpha) + + # Closed form: + # y[t] = alpha^t * (x[0] + (1-alpha) * sum_{k=1}^t x[k] / alpha^k) + # This avoids the Python O(T) recurrence loop while preserving the exact EMA. + idx = np.arange(1, T, dtype=np.float64) + with np.errstate(over='ignore', under='ignore', invalid='ignore'): + pow_alpha = np.power(alpha_f, idx) + inv_pow_alpha = np.power(alpha_f, -idx) + + if np.all(np.isfinite(pow_alpha)) and np.all(np.isfinite(inv_pow_alpha)): + scaled = out[1:].astype(np.float64, copy=False) * inv_pow_alpha[:, None] + csum = np.cumsum(scaled, axis=0, dtype=np.float64) + out[1:] = ( + pow_alpha[:, None] + * ( + out[0].astype(np.float64, copy=False)[None, :] + + (1.0 - alpha_f) * csum + ) + ).astype(np.float32) + return out + + for t in range(1, T): + out[t] = alpha_f * out[t - 1] + (1.0 - alpha_f) * out[t] + return out + + +def compute_semantic_flow_magnitudes( + Z: Array, + cfg: SemanticFlowConfig, + dy_dZ: Array | None = None, +) -> Array: + """ + Semantic Flow Computation Unit: + - Computes a per-step scalar flow magnitude from consecutive latent states. + + If SemanticFlowConfig.smooth_latent_alpha is in (0, 1), applies EMA smoothing to Z + before computing flow (Lipschitz-like regularization when embeddings are noisy). + + For flow_kind 'output_aware': requires dy_dZ. Then + m_t = |(∂y/∂Z_t)(Z_{t+1}-Z_t)| (first-order effect of latent step on forecast). + dy_dZ must have shape (T, D) or (T, H, D). T must match Z.shape[0]. If (T, H, D), + magnitudes are aggregated over horizons using output_aware_aggregation. Assumptions: + forecast (or surrogate) is differentiable w.r.t. Z_t and depends on more than Z_{L-1} + for non-degenerate lag resolution. + + Returns: m [T-1] + """ + if Z.ndim != 2: + raise ValueError(f'Expected Z [T,D], got shape {Z.shape}') + if Z.shape[0] < 2: + raise ValueError('Need at least two latent states to compute flow.') + + T, D = Z.shape + + # Optional temporal smoothing of latent trajectory + if 0 < cfg.smooth_latent_alpha < 1: + Z = _smooth_latent_trajectory(Z, cfg.smooth_latent_alpha) + + # Sanitize NaN in latent trajectory (e.g. from embed on out-of-distribution windows) + if np.any(~np.isfinite(Z)): + warnings.warn( + 'Latent trajectory Z contains non-finite values (NaN/inf); replacing with 0 for flow computation. ' + 'This can happen when the model embeds windows that include forecast values.', + UserWarning, + stacklevel=2, + ) + Z = np.where(np.isfinite(Z), Z, 0.0).astype(np.float32) + + d = Z[1:] - Z[:-1] # [T-1, D] + + if cfg.flow_kind == 'output_aware': + if dy_dZ is None: + raise ValueError( + "flow_kind='output_aware' requires dy_dZ (gradient of forecast w.r.t. Z_t)." + ) + dy_dZ = np.asarray(dy_dZ, dtype=np.float32) + if dy_dZ.shape[0] != T: + raise ValueError( + f'dy_dZ.shape[0] must equal Z.shape[0] ({T}), got {dy_dZ.shape[0]}' + ) + if dy_dZ.ndim == 2: + # [T, D] => scalar effect per step: m_t = |dy_dZ[t] @ delta_t| + if dy_dZ.shape[1] != D: + raise ValueError( + f'dy_dZ shape [T,D] expects D={D}, got {dy_dZ.shape[1]}' + ) + # m_t = |dy_dZ[t] @ d[t]| for t = 0..T-2; we need dy_dZ at indices 0..T-2 (first T-1 rows) + grad_t = dy_dZ[:-1] # [T-1, D] + dot = np.sum(grad_t * d, axis=1) # [T-1] + m = np.abs(dot).astype(np.float32) + elif dy_dZ.ndim == 3: + # [T, H, D] => aggregate over horizons + H = dy_dZ.shape[1] + if dy_dZ.shape[2] != D: + raise ValueError( + f'dy_dZ shape [T,H,D] expects D={D}, got {dy_dZ.shape[2]}' + ) + grad_t = dy_dZ[:-1] # [T-1, H, D] + # dot[t,h] = grad_t[t,h] @ d[t] + dot = np.einsum('thd,td->th', grad_t, d) # [T-1, H] + if cfg.output_aware_aggregation == 'l2': + m = np.sqrt(np.sum(dot**2, axis=1)).astype(np.float32) + else: + m = np.sum(np.abs(dot), axis=1).astype(np.float32) + else: + raise ValueError( + f'dy_dZ must be 2D [T,D] or 3D [T,H,D], got shape {dy_dZ.shape}' + ) + if np.any(~np.isfinite(m)): + m = np.where(np.isfinite(m), m, 0.0).astype(np.float32) + return m + + if cfg.flow_kind != 'delta_l2': + raise ValueError(f'Unsupported flow_kind={cfg.flow_kind}') + + delta = np.linalg.norm(d, ord=2, axis=1).astype(np.float32) + if np.any(~np.isfinite(delta)): + delta = np.where(np.isfinite(delta), delta, 0.0).astype(np.float32) + + if cfg.scale_weight > 0: + n0 = np.linalg.norm(Z[:-1], ord=2, axis=1) + n1 = np.linalg.norm(Z[1:], ord=2, axis=1) + ratio = (n1 + cfg.eps) / (n0 + cfg.eps) + ratio = np.clip(ratio, 1e-6, 1e6) + log_scale = np.abs(np.log(ratio)).astype(np.float32) + log_scale = np.clip(log_scale, 0.0, 10.0) + return delta + float(cfg.scale_weight) * log_scale + + return delta + + +def lag_horizon_attribution( + flow_magnitudes: Array, # [T-1] + *, + t_index: int, + n_lags: int, + horizon: int, + softmax_tau: float = 1.0, + horizon_kernel: Literal['exp', 'none'] = 'exp', + kernel_min_scale: float = 4.0, + kernel_max_scale: float | None = None, +) -> tuple[Array, Array]: + """ + Lag-Horizon Attribution Engine. + + We compute a lag x horizon score matrix from *history* flow magnitudes (transitions up to t_index), + then normalize horizon-wise with softmax over lags. + + Why history-only? + - The latent trajectory is built over [history; forecast]. The forecast part is model-generated (OOD). + Including forecast-segment flow in the lag-score adds a horizon-dependent *constant* across lags, + which makes the horizon-wise softmax identical across horizons (a degeneracy). + - For horizon-resolved explanations, we instead weight the history flow with a horizon-dependent kernel + so that far horizons can distribute weight over longer temporal scales. + + Returns: + scores: [K, H] (cumulative-flow score; larger => more influence) + attributions: [K, H] (softmax-normalized over lags for each horizon) + + Note: The attribution matrix is in general *full*, not upper triangular. Each lag j can + influence every horizon h, because we sum flow along the path from t-j to t+h; there is no + structural constraint that lag j only affects horizon h when h >= j. + """ + m = np.asarray(flow_magnitudes, dtype=np.float32).copy() + if np.any(~np.isfinite(m)): + warnings.warn( + 'flow_magnitudes contain non-finite values; replacing with 0 for attribution.', + UserWarning, + stacklevel=2, + ) + m = np.where(np.isfinite(m), m, 0.0).astype(np.float32) + + Tm = m.shape[0] # transitions count (Z length - 1) + K = int(n_lags) + H = int(horizon) + if K <= 0 or H <= 0: + raise ValueError('n_lags and horizon must be positive') + if not (0 <= t_index <= Tm): + raise ValueError(f't_index must be in [0,{Tm}], got {t_index}') + + # History transitions are indices 0..t_index-1 inclusive (count = t_index). + # A lag j uses the last j history transitions: p = (t_index-j) .. (t_index-1). + if t_index < 1: + raise ValueError( + 't_index must be >= 1 to attribute history flow to lags.' + ) + if t_index < K: + raise ValueError(f'n_lags must be <= t_index={t_index}, got {K}') + + # Horizon-dependent kernel over transition age a=0..K-1 (0=most recent history transition). + if horizon_kernel not in ('exp', 'none'): + raise ValueError(f'Unsupported horizon_kernel={horizon_kernel}') + min_s = float(kernel_min_scale) + max_s = ( + float(kernel_max_scale) if kernel_max_scale is not None else float(K) + ) + if min_s <= 0 or max_s <= 0: + raise ValueError( + 'kernel_min_scale and kernel_max_scale must be positive' + ) + max_s = max(max_s, min_s) + + scores = np.zeros((K, H), dtype=np.float32) + # Pre-slice history flow (length t_index). We only need last K steps for attribution. + hist = m[:t_index] # [t_index] + hist_tail = hist[max(0, t_index - K) : t_index] # [<=K], oldest..newest + # Reverse so index 0 = most recent, consistent with "age" + hist_rev = hist_tail[::-1].astype( + np.float32, copy=False + ) # [<=K], most recent..older + + # Vectorized horizon kernels. The previous implementation recomputed ages/weights/cumsum per horizon. + # Here we broadcast weights across horizons and compute all cumulative sums in one pass (chunked to + # cap memory when K*H is large). + L = int(hist_rev.shape[0]) + if H == 1: + scales_h = np.array([min_s], dtype=np.float32) + else: + u_h = (np.arange(H, dtype=np.float32) / float(H - 1)).astype( + np.float32 + ) # 0..1 + scales_h = (min_s + u_h * (max_s - min_s)).astype(np.float32) + + if horizon_kernel == 'none': + csum = np.cumsum(hist_rev, dtype=np.float32) # [L] + scores[:L, :] = csum[:, None] + else: + scales_h = np.maximum(scales_h, np.float32(1e-6)) + ages_l = np.arange(L, dtype=np.float32)[:, None] # [L,1] + + # Choose a horizon chunk size to keep the intermediate [L,chunk] weight matrix bounded. + # (float32 => 4 bytes per entry) + target_bytes = 64 * 1024 * 1024 # ~64MiB + bytes_per_h = max(1, L * 4) + chunk = int(max(1, min(H, target_bytes // bytes_per_h))) + + for h0 in range(0, H, chunk): + h1 = min(H, h0 + chunk) + s = scales_h[h0:h1][None, :] # [1,chunk] float32 + w_lh = np.exp(-ages_l / s) # [L,chunk] float32 + hw_lh = hist_rev[:, None] * w_lh + csum_lh = np.cumsum(hw_lh, axis=0, dtype=np.float32) # [L,chunk] + scores[:L, h0:h1] = csum_lh + + # Horizon-wise softmax over lags. + tau = max(float(softmax_tau), 1e-6) + zero_score_cols = np.all(scores == 0.0, axis=0) + if np.any(zero_score_cols): + warnings.warn( + f'{int(np.sum(zero_score_cols))} horizon(s) have all-zero lag scores; ' + 'returning uniform lag attributions for those columns.', + UserWarning, + stacklevel=2, + ) + attributions = _softmax(scores / tau, axis=0) + # If any column is all zero or had NaN, softmax can yield NaN; fallback to uniform + if np.any(~np.isfinite(attributions)): + uniform = np.ones((K, H), dtype=np.float32) / float(K) + attributions = np.where( + np.isfinite(attributions), attributions, uniform + ) + return scores, attributions + + +def _block_bootstrap( + series_ct: Array, *, block_len: int, rng: np.random.Generator +) -> Array: + C, L = series_ct.shape + b = max(1, int(block_len)) + n_blocks = int(np.ceil(L / b)) + out = np.empty((C, n_blocks * b), dtype=np.float32) + for i in range(n_blocks): + s = int(rng.integers(0, max(1, L - b + 1))) + out[:, i * b : (i + 1) * b] = series_ct[:, s : s + b] + return out[:, :L] + + +def _fourier_phase_preserving_noise( + series_ct: Array, *, amp_sigma: float, rng: np.random.Generator +) -> Array: + if amp_sigma <= 0: + return series_ct.astype(np.float32, copy=True) + + C, L = series_ct.shape + out = np.empty_like(series_ct, dtype=np.float32) + for c in range(C): + x = series_ct[c].astype(np.float32) + X = np.fft.rfft(x) + amp = np.abs(X) + phase = np.angle(X) + + # multiplicative log-amplitude noise keeps phase unchanged + noise = rng.normal( + loc=0.0, scale=float(amp_sigma), size=amp.shape + ).astype(np.float32) + amp2 = amp * np.exp(noise) + X2 = amp2 * np.exp(1j * phase) + x2 = np.fft.irfft(X2, n=L).real.astype(np.float32) + + # Match mean/std to original to avoid drift. + mu0, sd0 = float(x.mean()), float(x.std() + 1e-8) + mu1, sd1 = float(x2.mean()), float(x2.std() + 1e-8) + x2 = (x2 - mu1) * (sd0 / sd1) + mu0 + out[c] = x2 + return out + + +def generate_structure_preserving_perturbations( + x_context_ct: Array, cfg: PerturbationConfig +) -> Array: + """ + Generate perturbations that preserve temporal continuity and seasonality. + + Returns: samples [N, C, L] + """ + x0 = np.asarray(x_context_ct, dtype=np.float32) + if x0.ndim != 2: + raise ValueError(f'Expected x_context [C,L], got {x0.shape}') + C, L = x0.shape + + rng = np.random.default_rng(int(cfg.seed)) + out = np.empty((int(cfg.n_samples), C, L), dtype=np.float32) + mix = float(cfg.mix_original) + for i in range(int(cfg.n_samples)): + xb = _block_bootstrap(x0, block_len=cfg.block_len, rng=rng) + xf = _fourier_phase_preserving_noise( + xb, amp_sigma=cfg.fourier_amp_sigma, rng=rng + ) + out[i] = mix * x0 + (1.0 - mix) * xf + return out + + +def _weighted_standardize( + X: Array, w: Array, eps: float = 1e-12 +) -> tuple[Array, Array, Array]: + """ + Weighted standardization column-wise. + + Returns Xs, mean, std. + """ + w = w.reshape(-1, 1).astype(np.float32) + wsum = float(np.sum(w)) + eps + mu = np.sum(w * X, axis=0) / wsum + var = np.sum(w * (X - mu) ** 2, axis=0) / wsum + sd = np.sqrt(np.maximum(var, eps)) + return (X - mu) / sd, mu.astype(np.float32), sd.astype(np.float32) + + +def _ista_weighted_lasso( + X: Array, + y: Array, + w: Array, + *, + alpha: float, + max_iter: int, + tol: float, +) -> tuple[Array, float]: + """ + Weighted Lasso via ISTA: + min_b 1/2 ||sqrt(w) (X b - y)||^2 + alpha ||b||_1 + + Returns: + coef: [P] + intercept: scalar (computed in original space) + """ + X = np.asarray(X, dtype=np.float32) + y = np.asarray(y, dtype=np.float32).reshape(-1) + w = np.asarray(w, dtype=np.float32).reshape(-1) + if X.ndim != 2: + raise ValueError('X must be 2D') + n, p = X.shape + if y.shape[0] != n or w.shape[0] != n: + raise ValueError('Mismatched shapes between X, y, w') + + # Weighted standardize X; center y + Xs, mu_x, sd_x = _weighted_standardize(X, w) + wsum = float(np.sum(w)) + 1e-12 + mu_y = float(np.sum(w * y) / wsum) + yc = y - mu_y + + # Precompute for gradient with weights + sw = np.sqrt(np.maximum(w, 0.0)).astype(np.float32) + Xw = Xs * sw[:, None] + yw = yc * sw + + # Lipschitz constant of grad = ||Xw||_2^2 (spectral norm squared). + # Use power iteration on A=(Xw^T Xw) with a convergence check. + # Underestimating L makes ISTA steps too large; we also add backtracking below. + v = np.ones((p,), dtype=np.float32) / np.sqrt(max(1, p)) + power_tol = 1e-4 + max_power_iter = 100 + for _ in range(max_power_iter): + Av = Xw.T @ (Xw @ v) + nAv = float(np.linalg.norm(Av) + 1e-12) + v_next = (Av / nAv).astype(np.float32) + if float(np.linalg.norm(v_next - v)) <= power_tol: + v = v_next + break + v = v_next + Av = Xw.T @ (Xw @ v) + L = float(v @ Av) + if not np.isfinite(L) or L <= 0: + # Safe fallback bound: ||Xw||_F^2 >= ||Xw||_2^2 + L = float(np.sum(Xw.astype(np.float64) ** 2)) + 1e-12 + else: + L = L + 1e-12 + step = 1.0 / L + + def soft_threshold(a: Array, thr: float) -> Array: + return np.sign(a) * np.maximum(np.abs(a) - thr, 0.0) + + b = np.zeros((p,), dtype=np.float32) + last_obj = np.inf + max_backtrack = 25 + for _ in range(int(max_iter)): + r = Xw @ b - yw + grad = Xw.T @ r + obj_cur = 0.5 * float(r @ r) + float(alpha) * float(np.sum(np.abs(b))) + + # ISTA step; backtrack if objective fails to decrease (guards against L underestimation). + step_local = step + b_new = soft_threshold(b - step_local * grad, step_local * float(alpha)) + + # objective (for convergence check) + r2 = Xw @ b_new - yw + obj = 0.5 * float(r2 @ r2) + float(alpha) * float(np.sum(np.abs(b_new))) + bt = 0 + while (not np.isfinite(obj) or obj > obj_cur) and bt < max_backtrack: + step_local *= 0.5 + b_new = soft_threshold( + b - step_local * grad, step_local * float(alpha) + ) + r2 = Xw @ b_new - yw + obj = 0.5 * float(r2 @ r2) + float(alpha) * float( + np.sum(np.abs(b_new)) + ) + bt += 1 + + step = min(step, step_local) + if abs(last_obj - obj) <= float(tol) * max(1.0, last_obj): + b = b_new + break + b = b_new + last_obj = obj + + # Unstandardize: y ≈ mu_y + sum_j ( (x_j - mu_xj)/sd_xj ) * b_j + # => y ≈ (mu_y - sum_j mu_xj/sd_xj * b_j) + sum_j x_j * (b_j/sd_xj) + coef = (b / sd_x).astype(np.float32) + intercept = float(mu_y - np.sum((mu_x / sd_x) * b)) + return coef, intercept + + +def fit_horizon_surrogates( + model: ForecastModel, + *, + x_context_ct: Array, # [C, L] + input_mask_l: Array, # [L] + model_horizon: int, + forecast_horizon: int, + device: torch.device, + pert_cfg: PerturbationConfig, + surr_cfg: SurrogateConfig, + batch_size: int = 16, + n_jobs: int | None = None, +) -> tuple[Array, Array, str]: + """ + Local Surrogate Modeling Module. + + We fit a weighted sparse linear model per horizon h and channel c: + y_hat[c,h] ≈ intercept[c,h] + X_lags · coef[c,h,:] + + Features are lagged values of the context window: + X = flatten([C, K]) for last K lags (oldest->newest within that slice). + + Weights: + w_i = exp(-distance_lambda * ||Z_i - Z_0||^2) + where Z_i is an embedding of the (perturbed) context window. + """ + x0 = np.asarray(x_context_ct, dtype=np.float32) + C, L = x0.shape + K = int(surr_cfg.n_lags) + if K <= 0 or K > L: + raise ValueError(f'Surrogate n_lags must be in [1,{L}], got {K}') + + # Baseline embedding for weighting + x0_t = torch.from_numpy(x0[None, :, :]).to( + device=device, dtype=torch.float32 + ) + m0_t = torch.from_numpy( + np.asarray(input_mask_l[None, :], dtype=np.int64) + ).to(device=device, dtype=torch.long) + z0 = _embed_batch(model, x0_t, m0_t)[0] # [D] + + # Perturbations + samples = generate_structure_preserving_perturbations( + x0, pert_cfg + ) # [N, C, L] + N = samples.shape[0] + + # Build features from last K lags + X = samples[:, :, -K:] # [N,C,K] + X = X.reshape(N, C * K).astype(np.float32) # [N, P] + feature_layout = ( + f'flatten(C={C},lags={K}) with ordering [c0_lag0..lagK-1, c1_lag0..]' + ) + + # Embed perturbed samples for weights, and forecast to build y targets. + Z_list: list[Array] = [] + Y_list: list[Array] = [] + mask = np.asarray(input_mask_l, dtype=np.int64) + for i in range(0, N, batch_size): + xb = torch.from_numpy(samples[i : i + batch_size]).to( + device=device, dtype=torch.float32 + ) + mb = torch.from_numpy(np.tile(mask[None, :], (xb.shape[0], 1))).to( + device=device, dtype=torch.long + ) + Z_list.append(_embed_batch(model, xb, mb)) + Yb = _forecast_autoregressive( + model, + xb, + mb, + model_horizon=model_horizon, + target_horizon=forecast_horizon, + ) # [b,C,H] + Y_list.append(Yb) + + Z = np.concatenate(Z_list, axis=0) # [N,D] + Y = np.concatenate(Y_list, axis=0) # [N,C,H] + + # Local weights around baseline + dz = Z - z0[None, :] + dist2 = np.sum(dz * dz, axis=1).astype(np.float32) + w = ( + np.exp(-float(surr_cfg.distance_lambda) * dist2).astype(np.float32) + + 1e-12 + ) + + # Fit per horizon+channel. Each (c, h) regression is independent and + # CPU-bound (NumPy / BLAS), so we farm them out to a thread pool when + # ``n_jobs > 1``. ISTA's inner loops call into NumPy linalg which + # releases the GIL, so threads scale better than processes here and + # avoid pickling the (potentially large) shared X / w buffers. + H = int(forecast_horizon) + P = X.shape[1] + coef = np.zeros((C, H, P), dtype=np.float32) # [C,H,P] + intercept = np.zeros((C, H), dtype=np.float32) # [C,H] + + alpha = float(surr_cfg.l1_alpha) + max_iter = int(surr_cfg.max_iter) + tol = float(surr_cfg.tol) + + def _solve_one(args: tuple[int, int]) -> tuple[int, int, Array, float]: + c_idx, h_idx = args + b, a0 = _ista_weighted_lasso( + X, + Y[:, c_idx, h_idx], + w, + alpha=alpha, + max_iter=max_iter, + tol=tol, + ) + return c_idx, h_idx, b, a0 + + work_items = [(c, h) for c in range(C) for h in range(H)] + + for item in work_items: + c_idx, h_idx, b, a0 = _solve_one(item) + coef[c_idx, h_idx] = b + intercept[c_idx, h_idx] = a0 + + return coef, intercept, feature_layout + + +def explain_forecast( + model: ForecastModel, + *, + x_context_ct: Array, # [C, L] + input_mask_l: Array, # [L] + model_horizon: int, + forecast_horizon: int, + device: torch.device, + n_lags: int = 128, + flow_cfg: SemanticFlowConfig | None = None, + softmax_tau: float = 1.0, + surrogate: bool = True, + pert_cfg: PerturbationConfig | None = None, + surr_cfg: SurrogateConfig | None = None, + latent_batch_size: int = 32, + surrogate_n_jobs: int | None = None, + # v2 feature-axis switches + channel_axis: bool = False, + chan_cfg: ChannelFlowConfig | None = None, # forward ref; imported lazily + channel_softmax_tau: float | None = None, + channel_output_aware: bool = False, + channel_target: int | None = None, +) -> ForecastExplanation: + """ + End-to-end interpretability pipeline: + 1) Forecast (for extension into the future) + 2) Latent trajectory extraction over [history + forecast] + 3) Semantic flow magnitudes + 4) Lag x Horizon attribution matrix + horizon-wise softmax + 5) Optional horizon-specific local surrogates with structure-preserving perturbations + + When ``channel_axis=True`` (and the input has C > 1 channels) we additionally + run the v2 feature-axis stages: per-channel Jacobian-flow decomposition + and joint lag x channel x horizon attribution. + + Pass ``chan_cfg`` to control the per-channel flow estimator. When + ``chan_cfg`` is None we default to ``ChannelFlowConfig()``, the fast O(C) + estimator suitable for routine use. + """ + flow_cfg = flow_cfg or SemanticFlowConfig() + pert_cfg = pert_cfg or PerturbationConfig() + if surr_cfg is None: + # Preserve existing behavior: cap surrogate lag features to 64 by default. + # Emit a warning so callers who set n_lags>64 aren't surprised. + if int(n_lags) > 64: + warnings.warn( + f'explain_forecast default SurrogateConfig caps n_lags to 64 ' + f'(got n_lags={int(n_lags)}). Pass surr_cfg=SurrogateConfig(n_lags=...) ' + f'to override.', + UserWarning, + stacklevel=2, + ) + surr_cfg = SurrogateConfig(n_lags=min(64, int(n_lags))) + K = int(n_lags) + + x0 = np.asarray(x_context_ct, dtype=np.float32) + if x0.ndim != 2: + raise ValueError(f'Expected x_context [C,L], got {x0.shape}') + C, L = x0.shape + if L < 2: + raise ValueError( + f'x_context must have length >= 2 for lag attribution, got L={L}' + ) + max_lags = L - 1 + if K <= 0 or max_lags < K: + raise ValueError(f'n_lags must be in [1,{max_lags}], got {K}') + + mask = np.asarray(input_mask_l, dtype=np.int64) + if mask.shape != (L,): + raise ValueError(f'Expected input_mask [L], got {mask.shape}') + + # --- 1) baseline forecast --- + x_t = torch.from_numpy(x0[None, :, :]).to( + device=device, dtype=torch.float32 + ) + m_t = torch.from_numpy(mask[None, :]).to(device=device, dtype=torch.long) + base = _forecast_autoregressive( + model, + x_t, + m_t, + model_horizon=int(model_horizon), + target_horizon=int(forecast_horizon), + )[0] # [C,H] + + # --- 2) build extended series and latent trajectory --- + series_ext = np.concatenate([x0, base], axis=1) # [C, L+H] + mask_ext = np.concatenate( + [mask, np.ones((int(forecast_horizon),), dtype=np.int64)], axis=0 + ) # [L+H] + Z = extract_latent_trajectory( + model, + series_ext, + seq_len=L, + input_mask_t=mask_ext, + device=device, + batch_size=latent_batch_size, + ) # [T,D] + + # --- 3) semantic flow magnitudes --- + m = compute_semantic_flow_magnitudes(Z, flow_cfg) # [T-1] + + # --- 3b) segment quality: forecast vs history flow (OOD volatility) --- + flow_ratio, flow_var_ratio = _flow_segment_ratios( + m, context_len=L, forecast_horizon=int(forecast_horizon) + ) + curvature_ratio = _curvature_segment_ratio( + Z, context_len=L, forecast_horizon=int(forecast_horizon) + ) + maha_ratio = _latent_diag_mahalanobis_ratio( + Z, context_len=L, forecast_horizon=int(forecast_horizon) + ) + + # --- 4) lag×horizon attribution --- + # t corresponds to last observed index in the context window. + t_index = L - 1 + scores, attrib = lag_horizon_attribution( + m, + t_index=t_index, + n_lags=K, + horizon=int(forecast_horizon), + softmax_tau=float(softmax_tau), + ) + + # --- 5) horizon-specific surrogates --- + coef = None + intercept = None + feature_layout = None + if surrogate: + coef, intercept, feature_layout = fit_horizon_surrogates( + model, + x_context_ct=x0, + input_mask_l=mask, + model_horizon=int(model_horizon), + forecast_horizon=int(forecast_horizon), + device=device, + pert_cfg=pert_cfg, + surr_cfg=surr_cfg, + n_jobs=surrogate_n_jobs, + ) + + # --- 6) v2 feature-axis stages (optional) --- + per_chan_flow = None + lag_chan_scores = None + lag_chan_attrib = None + chan_horizon_attrib = None + chan_method = None + chan_resid_mean = None + chan_resid_p95 = None + if channel_axis: + from sdm_client.explain._attribution.channel_flow import ( # local import avoids circular dependency at module load + ChannelFlowConfig, + channel_horizon_marginal, + compute_per_channel_flow, + lag_channel_horizon_attribution, + ) + + chan_cfg_eff = chan_cfg if chan_cfg is not None else ChannelFlowConfig() + if channel_output_aware: + if channel_target is None: + raise ValueError( + 'channel_output_aware=True requires channel_target (the forecast ' + 'channel whose prediction the attribution should explain).' + ) + chan_horizon_attrib = ( + compute_target_channel_input_jacobian_importance( + model, + x_context_ct=x0, + input_mask_l=mask, + device=device, + target_channel=int(channel_target), + model_horizon=int(model_horizon), + forecast_horizon=int(forecast_horizon), + ) + ) + chan_method = 'target_input_jacobian' + else: + report = compute_per_channel_flow( + model, + series_ext, + seq_len=L, + input_mask_t=mask_ext, + device=device, + cfg=chan_cfg_eff, + ) + per_chan_flow = report.per_channel_flow + chan_method = report.method + chan_resid_mean = report.residual_ratio_mean + chan_resid_p95 = report.residual_ratio_p95 + chan_tau = ( + float(channel_softmax_tau) + if channel_softmax_tau is not None + else float(softmax_tau) + ) + lag_chan_scores, lag_chan_attrib = lag_channel_horizon_attribution( + per_chan_flow, + t_index=t_index, + n_lags=K, + horizon=int(forecast_horizon), + softmax_tau=chan_tau, + normalize='joint', + ) + chan_horizon_attrib = channel_horizon_marginal(lag_chan_attrib) + + return ForecastExplanation( + baseline_forecast=base, + lag_horizon_scores=scores, + lag_horizon_attributions=attrib, + flow_magnitudes=m, + latent_trajectory=Z, + surrogate_coef=coef, + surrogate_intercept=intercept, + surrogate_feature_layout=feature_layout, + flow_ratio_forecast_vs_history=flow_ratio, + flow_variance_ratio_forecast_vs_history=flow_var_ratio, + curvature_ratio_forecast_vs_history=curvature_ratio, + latent_diag_mahalanobis_ratio_forecast_vs_history=maha_ratio, + per_channel_flow=per_chan_flow, + lag_channel_horizon_scores=lag_chan_scores, + lag_channel_horizon_attributions=lag_chan_attrib, + channel_horizon_attributions=chan_horizon_attrib, + channel_flow_method=chan_method, + channel_flow_residual_ratio_mean=chan_resid_mean, + channel_flow_residual_ratio_p95=chan_resid_p95, + ) diff --git a/packages/structured-data-models-client/src/sdm_client/explain/_attribution/pages.py b/packages/structured-data-models-client/src/sdm_client/explain/_attribution/pages.py new file mode 100644 index 000000000..4da73becb --- /dev/null +++ b/packages/structured-data-models-client/src/sdm_client/explain/_attribution/pages.py @@ -0,0 +1,1904 @@ +# SPDX-FileCopyrightText: Copyright (c) 2026, NVIDIA CORPORATION & AFFILIATES. +# All rights reserved. +# SPDX-License-Identifier: Apache-2.0 + +r"""Drawing a forecast explanation, as it was written to be drawn. + +The pages of the forecast report, the artifacts written beside them, and the +explanation as JSON. +""" + +from __future__ import annotations + +import json +import logging +import types +from contextlib import contextmanager +from datetime import datetime, timezone +from pathlib import Path +from typing import Any + +import numpy as np +import pandas as pd +import torch + +from sdm_client.explain._attribution.channel_stability import ( + PerChannelEmbeddingStabilityReport, +) +from sdm_client.explain._attribution.interpretability import ( + ForecastExplanation, + TrajectoryStabilityReport, +) + +# Module scope in the file these were taken from, and dropped by the move. +# Without them the integrated-gradients page and every warning path here +# raise NameError the moment they run. +logger = logging.getLogger(__name__) + + +def _save_lag_horizon_artifacts( + out_dir: Path, + attributions: np.ndarray, + scores: np.ndarray | None = None, + *, + na_rep: str = 'nan', +) -> Path | None: + """Write lag x horizon attribution CSVs and a heatmap PNG. + + Returns the path to the heatmap PNG if matplotlib is available, else None. + """ + K, H = attributions.shape + + lag_cols = [f'horizon_{h}' for h in range(H)] + df_matrix = pd.DataFrame(attributions, columns=lag_cols) + df_matrix.insert(0, 'lag', [f'lag_{j}' for j in range(K)]) + df_matrix.to_csv( + out_dir / 'lag_horizon_attributions.csv', index=False, na_rep=na_rep + ) + + rows = [] + for j in range(K): + for h in range(H): + row = { + 'lag': j, + 'horizon': h, + 'attribution': float(attributions[j, h]), + } + if scores is not None: + row['score'] = float(scores[j, h]) + rows.append(row) + pd.DataFrame(rows).to_csv( + out_dir / 'lag_horizon_long.csv', index=False, na_rep=na_rep + ) + + try: + import matplotlib as mpl + + mpl.use('Agg') + import matplotlib.pyplot as plt + except ImportError: + return None + + fig, ax = plt.subplots(figsize=(max(8, H * 0.15), max(6, K * 0.05))) + im = ax.imshow( + attributions, aspect='auto', cmap='viridis', interpolation='nearest' + ) + ax.set_xlabel('Forecast horizon') + ax.set_ylabel('Lag (past time step)') + ax.set_xticks(np.linspace(0, H - 1, min(12, H), dtype=int)) + ax.set_xticklabels(np.linspace(0, H - 1, min(12, H), dtype=int)) + ax.set_yticks(np.linspace(0, K - 1, min(12, K), dtype=int)) + ax.set_yticklabels(np.linspace(0, K - 1, min(12, K), dtype=int)) + plt.colorbar(im, ax=ax, label='Attribution') + plt.tight_layout() + heatmap_path = out_dir / 'lag_horizon_heatmap.png' + plt.savefig(heatmap_path, dpi=120) + plt.close(fig) + return heatmap_path + + +def _topk_lag_steps_per_horizon( + scores: np.ndarray, + *, + top_k: int = 5, +) -> tuple[np.ndarray | None, list[list[str]]]: + """Compute marginal per-step lag weights and produce top-k summary rows.""" + if scores.ndim != 2 or scores.shape[0] < 2 or scores.shape[1] < 1: + return None, [] + step_scores = np.vstack([scores[0:1, :], np.diff(scores, axis=0)]) + step_scores = step_scores - np.max(step_scores, axis=0, keepdims=True) + step_probs = np.exp(step_scores) + step_probs = step_probs / np.maximum( + np.sum(step_probs, axis=0, keepdims=True), 1e-12 + ) + + H = step_probs.shape[1] + rows: list[list[str]] = [] + for h in range(H): + order = np.argsort(-step_probs[:, h])[:top_k] + row: list[str] = [f'horizon_{h}'] + for idx in order: + lag_step = int(idx) + 1 + w = float(step_probs[idx, h]) + row.append(str(lag_step)) + row.append(f'{w:.4f}') + while len(row) < 1 + 2 * top_k: + row.extend(['', '']) + rows.append(row) + return step_probs, rows + + +def _semantic_flow_segments( + flow: np.ndarray, + *, + context_len: int, + forecast_horizon: int, +) -> tuple[np.ndarray, np.ndarray, int]: + """Split flow_magnitudes into (history, forecast) using the same convention as + ``interpretability._flow_segment_ratios``. + + Returns ``(history_flow, forecast_flow, boundary_index)`` where ``boundary_index`` + is the transition index that marks the first window touching the forecast segment. + """ + f = np.asarray(flow, dtype=np.float32).reshape(-1) + T_trans = int(f.shape[0]) + L = int(context_len) + H = int(forecast_horizon) + boundary = max(0, L - 1) + hist = f[0:boundary] if T_trans > 0 else f + fcst = f[boundary : min(T_trans, L + H - 1)] if T_trans > 0 else f + return hist, fcst, boundary + + +def _save_semantic_flow_csv( + out_dir: Path, + flow: np.ndarray, + *, + context_len: int, + forecast_horizon: int, + na_rep: str = 'nan', +) -> Path: + """Persist per-transition latent flow magnitudes with a segment label. + + Columns: ``transition_index, segment, flow_magnitude`` where ``segment`` is + ``"history"`` for transitions whose window sits inside the input context and + ``"forecast"`` for transitions whose window extends into the model-generated + future. Transitions outside both segments (only possible when ``T-1 > L+H-1``) + are labeled ``"tail"``. + """ + f = np.asarray(flow, dtype=np.float32).reshape(-1) + T_trans = int(f.shape[0]) + L = int(context_len) + H = int(forecast_horizon) + boundary = max(0, L - 1) + fcst_end = min(T_trans, L + H - 1) + + segments = np.full((T_trans,), 'tail', dtype=object) + segments[0:boundary] = 'history' + segments[boundary:fcst_end] = 'forecast' + + df = pd.DataFrame( + { + 'transition_index': np.arange(T_trans, dtype=np.int64), + 'segment': segments, + 'flow_magnitude': f, + } + ) + out_path = out_dir / 'semantic_flow.csv' + df.to_csv(out_path, index=False, na_rep=na_rep) + return out_path + + +def _semantic_flow_page( + pdf: Any, + plt: Any, + *, + explanation: ForecastExplanation, + context_len: int, + forecast_horizon: int, +) -> None: + """Append a single PDF page summarizing semantic flow magnitudes. + + Layout mirrors the trajectory-stability page: title, gray blurb, a primary + visual (line chart of flow over transitions with the history/forecast split + annotated), two side-by-side tables (per-segment summary + diagnostics), and + a monospace reading guide. + """ + if getattr(explanation, 'flow_magnitudes', None) is None: + return + flow = np.asarray(explanation.flow_magnitudes, dtype=np.float32).reshape(-1) + T_trans = int(flow.shape[0]) + if T_trans == 0: + return + + hist, fcst, boundary = _semantic_flow_segments( + flow, + context_len=context_len, + forecast_horizon=forecast_horizon, + ) + + def _stats(arr: np.ndarray) -> tuple[str, str, str, str, str, str]: + a = np.asarray(arr, dtype=np.float32) + a = a[np.isfinite(a)] + if a.size == 0: + return ('--', '--', '--', '--', '--', '0') + return ( + f'{float(np.mean(a)):.4f}', + f'{float(np.median(a)):.4f}', + f'{float(np.percentile(a, 95)):.4f}', + f'{float(np.max(a)):.4f}', + f'{float(np.var(a)):.4f}', + f'{int(a.size)}', + ) + + hist_s = _stats(hist) + fcst_s = _stats(fcst) + + def _fmt(x: Any) -> str: + if x is None: + return 'n/a' + try: + xv = float(x) + except (TypeError, ValueError): + return 'n/a' + return f'{xv:.4f}' if np.isfinite(xv) else 'n/a' + + fig = plt.figure(figsize=(11, 8.5)) + fig.text( + 0.5, + 0.95, + 'Semantic flow magnitudes', + ha='center', + fontsize=14, + fontweight='bold', + ) + fig.text( + 0.06, + 0.90, + r'Per-step latent flow is $m_t = \Vert \mathbf{z}_{t+1} - \mathbf{z}_t \Vert_2$' + ' over the trajectory built on\n' + '[history; forecast]. This is the temporal signal that drives the lag x horizon\n' + 'heatmap; bigger spikes contribute more to attribution. Compare the history\n' + 'segment against the forecast segment to gauge representation-level stability.', + ha='left', + va='top', + fontsize=9, + fontfamily='DejaVu Sans', + math_fontfamily='dejavusans', + color='gray', + ) + + ax = fig.add_axes((0.08, 0.55, 0.84, 0.23)) + x_axis = np.arange(T_trans) + ax.plot( + x_axis, flow, linewidth=1.0, color='#1f77b4', label='flow magnitude' + ) + if 0 < boundary < T_trans: + ax.axvspan(boundary, T_trans - 1, color='#f0f0f0', alpha=0.7, zorder=0) + ax.axvline( + boundary, + color='black', + linestyle='--', + linewidth=0.9, + label='history / forecast split', + ) + if hist.size > 0: + hist_mean = float(np.nanmean(hist)) + ax.hlines( + hist_mean, + 0, + max(0, boundary - 1), + colors='#2ca02c', + linestyles=':', + linewidth=1.2, + label=f'history mean ({hist_mean:.3f})', + ) + if fcst.size > 0: + fcst_mean = float(np.nanmean(fcst)) + fcst_end_idx = max( + boundary, + min(T_trans, int(context_len) + int(forecast_horizon) - 1) - 1, + ) + ax.hlines( + fcst_mean, + boundary, + fcst_end_idx, + colors='#d62728', + linestyles=':', + linewidth=1.2, + label=f'forecast mean ({fcst_mean:.3f})', + ) + ax.set_xlabel(r'Latent transition index ($t \rightarrow t+1$)') + ax.set_ylabel(r'$\Vert \mathbf{z}_{t+1} - \mathbf{z}_t \Vert_2$') + ax.legend(loc='upper right', fontsize=8, framealpha=0.85) + + seg_rows = [ + ['Mean', hist_s[0], fcst_s[0]], + ['Median', hist_s[1], fcst_s[1]], + ['P95', hist_s[2], fcst_s[2]], + ['Max', hist_s[3], fcst_s[3]], + ['Variance', hist_s[4], fcst_s[4]], + ['Transitions', hist_s[5], fcst_s[5]], + ] + ax_t1 = fig.add_axes((0.06, 0.32, 0.42, 0.18)) + ax_t1.axis('off') + table_seg = ax_t1.table( + cellText=seg_rows, + colLabels=['Metric', 'History', 'Forecast'], + colWidths=[0.4, 0.3, 0.3], + loc='upper center', + cellLoc='center', + ) + table_seg.auto_set_font_size(False) + table_seg.set_fontsize(8) + table_seg.scale(1.0, 1.3) + for c in range(3): + cell = table_seg[(0, c)] + cell.set_facecolor('#dddddd') + cell.set_text_props(weight='bold') + + diag_rows = [ + [ + 'Flow ratio (forecast/history)', + _fmt(explanation.flow_ratio_forecast_vs_history), + r'$\approx 1$ healthy, $>1.5$ OOD-volatile', + ], + [ + 'Flow variance ratio', + _fmt(explanation.flow_variance_ratio_forecast_vs_history), + r'$\approx 1$ healthy, $>2$ noisy', + ], + [ + 'Curvature ratio', + _fmt(explanation.curvature_ratio_forecast_vs_history), + r'$\approx 1$ healthy, $>1.5$ jaggy', + ], + [ + 'Latent diag-Mahalanobis ratio', + _fmt(explanation.latent_diag_mahalanobis_ratio_forecast_vs_history), + r'$\approx 1$ healthy, $\gg 1$ OOD shift', + ], + ] + ax_t2 = fig.add_axes((0.52, 0.32, 0.42, 0.18)) + ax_t2.axis('off') + table_diag = ax_t2.table( + cellText=diag_rows, + colLabels=['Diagnostic', 'Value', 'Heuristic'], + colWidths=[0.42, 0.18, 0.40], + loc='upper center', + cellLoc='center', + ) + table_diag.auto_set_font_size(False) + table_diag.set_fontsize(8) + table_diag.scale(1.0, 1.3) + for c in range(3): + cell = table_diag[(0, c)] + cell.set_facecolor('#dddddd') + cell.set_text_props(weight='bold') + + interp_text = ( + 'How to read these metrics\n' + '-------------------------\n' + ' - Per-segment table: mean / median / p95 / max / variance of latent\n' + ' flow magnitudes split into history (transitions fully inside the\n' + ' input window) and forecast (transitions whose window touches the\n' + ' model-generated future).\n' + ' - Flow ratio: average forecast flow divided by average history flow. Values\n' + " near 1 mean the model's latent dynamics in the OOD segment match history.\n" + ' Large values flag attributions in that region as likely noisy.\n' + ' - Flow variance ratio: same comparison on variance.\n' + ' - Curvature ratio: second-difference energy of Z; spikes when the\n' + ' forecast segment becomes much jaggier than history.\n' + ' - Latent diag-Mahalanobis ratio: per-dim distance of forecast latents\n' + ' from the history mean (scaled by history variance). Values well above 1 indicate a\n' + ' representation-level OOD shift.\n' + '\n' + 'These scalars are also under explanation.diagnostics in explanation.json,\n' + 'and the full series is exported as semantic_flow.csv.' + ) + fig.text( + 0.06, + 0.30, + interp_text, + ha='left', + va='top', + fontsize=9, + family='monospace', + color='#333333', + linespacing=1.05, + ) + + pdf.savefig(fig) + plt.close(fig) + + +def _save_channel_axis_artifacts( + out_dir: Path, + channel_horizon_attributions: np.ndarray, + channel_labels: list[str] | None = None, + *, + na_rep: str = 'nan', +) -> Path | None: + """Write the [C, H] channel x horizon attribution CSV and a heatmap PNG. + + Returns the path to the heatmap PNG if matplotlib is available, else None. + """ + A = np.asarray(channel_horizon_attributions, dtype=np.float32) + if A.ndim != 2: + return None + C, H = A.shape + labels = ( + channel_labels + if (channel_labels and len(channel_labels) == C) + else [f'channel_{c}' for c in range(C)] + ) + + df = pd.DataFrame(A, columns=[f'horizon_{h}' for h in range(H)]) + df.insert(0, 'channel', labels) + df.to_csv( + out_dir / 'channel_horizon_attributions.csv', index=False, na_rep=na_rep + ) + + try: + import matplotlib as mpl + + mpl.use('Agg') + import matplotlib.pyplot as plt + except ImportError: + return None + + fig, ax = plt.subplots(figsize=(max(8, H * 0.15), max(4, C * 0.4))) + im = ax.imshow(A, aspect='auto', cmap='viridis', interpolation='nearest') + ax.set_xlabel('Forecast horizon') + ax.set_ylabel('Input channel') + ax.set_yticks(range(C)) + ax.set_yticklabels(labels, fontsize=8) + xt = np.linspace(0, H - 1, min(12, H), dtype=int) + ax.set_xticks(xt) + ax.set_xticklabels(xt) + plt.colorbar(im, ax=ax, label='Attribution') + plt.tight_layout() + heatmap_path = out_dir / 'channel_horizon_heatmap.png' + plt.savefig(heatmap_path, dpi=120) + plt.close(fig) + return heatmap_path + + +def _channel_axis_page( + pdf: Any, + plt: Any, + *, + explanation: ForecastExplanation, + channel_labels: list[str] | None = None, +) -> None: + """Append one PDF page for the feature-axis (channel x horizon) attribution. + + Primary visual: a [C, H] heatmap of how much each input channel contributes to + each forecast step. A side bar summarizes each channel's total attribution + (summed over horizons) as a single feature-importance score. + """ + A = getattr(explanation, 'channel_horizon_attributions', None) + if A is None: + return + A = np.asarray(A, dtype=np.float32) + if A.ndim != 2 or A.shape[0] < 1 or A.shape[1] < 1: + return + C, H = A.shape + labels = ( + channel_labels + if (channel_labels and len(channel_labels) == C) + else [f'channel_{c}' for c in range(C)] + ) + importance = A.sum(axis=1) + method = getattr(explanation, 'channel_flow_method', None) or 'jacobian' + resid = getattr(explanation, 'channel_flow_residual_ratio_mean', None) + target_jacobian = method == 'target_input_jacobian' + intro = ( + 'Which input channel drives each target forecast step. Each cell is the magnitude of\n' + "the target forecast's local directional response when that channel moves from its\n" + 'local-mean replacement to the observed input. Rows are channels and columns are\n' + 'forecast steps; brighter = a stronger target-specific effect.' + if target_jacobian + else "Which input channel (feature) drives each forecast step. The model's response is\n" + 'decomposed along the feature axis into per-channel contributions, then aggregated\n' + 'per horizon. Rows are input channels, columns are forecast steps; brighter = that\n' + 'channel matters more there.' + ) + + fig = plt.figure(figsize=(11, 8.5)) + fig.text( + 0.5, + 0.95, + 'Feature-axis attribution (channel x horizon)', + ha='center', + fontsize=14, + fontweight='bold', + ) + fig.text( + 0.06, + 0.90, + intro, + ha='left', + va='top', + fontsize=9, + color='gray', + ) + + ax = fig.add_axes((0.08, 0.40, 0.56, 0.42)) + im = ax.imshow(A, aspect='auto', cmap='viridis', interpolation='nearest') + ax.set_xlabel('Forecast horizon (0 = first predicted step)') + ax.set_ylabel('Input channel') + ax.set_yticks(range(C)) + ax.set_yticklabels(labels, fontsize=8) + xt = np.linspace(0, H - 1, min(12, H), dtype=int) + ax.set_xticks(xt) + ax.set_xticklabels(xt) + fig.colorbar( + im, + ax=ax, + fraction=0.046, + pad=0.04, + label='Directional effect' if target_jacobian else 'Attribution', + ) + + axb = fig.add_axes((0.72, 0.40, 0.22, 0.42)) + y = np.arange(C) + axb.barh(y, importance, color='#1f77b4') + axb.set_yticks(y) + axb.set_yticklabels([]) + axb.invert_yaxis() # channel 0 at top, aligned with the heatmap rows + axb.set_title('Channel importance\n(sum over horizons)', fontsize=9) + axb.set_xlabel( + 'Total effect' if target_jacobian else 'Total attribution', fontsize=8 + ) + axb.tick_params(axis='both', labelsize=7) + + top_c = int(np.argmax(importance)) + resid_line = ( + f' - Estimator: {method}. Jacobian trust ratio (mean residual): {resid:.3f}\n' + ' (lower = more reliable first-order split; high values flag strong\n' + ' cross-channel interaction the first-order decomposition cannot capture).\n' + if resid is not None + else f' - Estimator: {method}.\n' + ) + heatmap_note = ( + " - Heatmap cell (channel c, horizon h): magnitude of the target forecast's\n" + ' first-order directional replacement effect; columns are not normalized.\n' + if target_jacobian + else ' - Heatmap cell (channel c, horizon h): share of the forecast at step h\n' + ' attributable to input channel c (each horizon column sums to 1 over channels).\n' + ) + bar_note = 'total effect' if target_jacobian else 'total attribution' + note = ( + 'How to read this page\n' + '---------------------\n' + + heatmap_note + + f" - Right bar: each channel's {bar_note} summed across horizons -- a single\n" + ' feature-importance score per input channel.\n' + f' - Most influential channel overall: {labels[top_c]}.\n' + + resid_line + + '\n' + 'Full channel-by-horizon values are exported as channel_horizon_attributions.csv.' + ) + fig.text( + 0.06, + 0.30, + note, + ha='left', + va='top', + fontsize=9, + family='monospace', + color='#333333', + linespacing=1.05, + ) + + pdf.savefig(fig) + plt.close(fig) + + +def _feature_axis_embedding_stability_frame( + report: PerChannelEmbeddingStabilityReport, + channel_labels: list[str] | None = None, +) -> pd.DataFrame: + """Return the complete feature-axis embedding-stability report.""" + n_channels = int(report.n_channels) + labels = ( + channel_labels + if channel_labels is not None and len(channel_labels) == n_channels + else [f'channel_{c}' for c in range(n_channels)] + ) + return pd.DataFrame( + { + 'feature': labels, + 'lip_ratio_mean': np.asarray( + report.lip_ratio_mean, dtype=np.float32 + ), + 'lip_ratio_p50': np.asarray(report.lip_ratio_p50, dtype=np.float32), + 'lip_ratio_p95': np.asarray(report.lip_ratio_p95, dtype=np.float32), + 'lip_ratio_max': np.asarray(report.lip_ratio_max, dtype=np.float32), + 'n_trials_per_channel': np.asarray( + report.n_trials_per_channel, dtype=np.int64 + ), + 'n_unique_windows': int(report.n_unique_windows), + 'step_delta_norm_mean': float(report.step_delta_norm_mean), + } + ) + + +def _save_feature_axis_embedding_stability_csv( + out_dir: Path, + report: PerChannelEmbeddingStabilityReport, + channel_labels: list[str] | None = None, +) -> Path: + """Write the complete feature-axis embedding-stability report.""" + out_path = out_dir / 'feature_axis_embedding_stability.csv' + _feature_axis_embedding_stability_frame(report, channel_labels).to_csv( + out_path, index=False, na_rep='nan' + ) + return out_path + + +def _feature_axis_embedding_stability_page( + pdf: Any, + plt: Any, + *, + report: PerChannelEmbeddingStabilityReport, + channel_labels: list[str] | None = None, +) -> None: + """Append the feature-axis embedding-stability summary.""" + frame = _feature_axis_embedding_stability_frame(report, channel_labels) + shown = frame.sort_values( + 'lip_ratio_p95', ascending=False, na_position='last' + ).head(10) + + def _fmt(value: Any) -> str: + numeric = float(value) + return f'{numeric:.4f}' if np.isfinite(numeric) else 'n/a' + + fig = plt.figure(figsize=(11, 8.5)) + fig.text( + 0.5, + 0.95, + 'Feature-axis embedding stability', + ha='center', + fontsize=14, + fontweight='bold', + ) + fig.text( + 0.06, + 0.90, + 'This shows the delta between two embedding points after a small, controlled change to one feature.\n' + r'Each sensitivity score is $\Vert \Delta \mathbf{z} \Vert_2' + r'\,/\, \Vert \Delta \mathbf{x}_c \Vert_2$.' + '\nLower values mean less latent movement per unit feature change; compare features\n' + 'within the same model and dataset because embedding scales are model-specific.', + ha='left', + va='top', + fontsize=9, + fontfamily='DejaVu Sans', + math_fontfamily='dejavusans', + color='gray', + ) + + table_rows = [ + [ + row.feature, + _fmt(row.lip_ratio_mean), + _fmt(row.lip_ratio_p50), + _fmt(row.lip_ratio_p95), + _fmt(row.lip_ratio_max), + str(int(row.n_trials_per_channel)), + ] + for row in shown.itertuples(index=False) + ] + table_ax = fig.add_axes((0.06, 0.50, 0.88, 0.28)) + table_ax.axis('off') + table = table_ax.table( + cellText=table_rows, + colLabels=['Feature', 'Mean', 'P50', 'P95', 'Max', 'Trials'], + colWidths=[0.30, 0.14, 0.14, 0.14, 0.14, 0.14], + loc='upper center', + cellLoc='center', + ) + table.auto_set_font_size(False) + table.set_fontsize(8) + table.scale(1.0, 1.2) + for c in range(6): + cell = table[(0, c)] + cell.set_facecolor('#dddddd') + cell.set_text_props(weight='bold') + + interp_text = ( + 'How to read these metrics\n' + '-------------------------\n' + ' - Mean / P50 / P95 / Max: summaries of the sensitivity score across\n' + ' small feature changes. Lower values mean the embedding\n' + ' moves less per unit change in that feature.\n' + ' - P95: conservative tail sensitivity. Rows are ranked by P95; the highest\n' + ' values identify features whose small changes can move the embedding most.\n' + ' - Trials: valid sensitivity measurements retained for that feature.\n' + f' - Sample coverage: {int(report.n_unique_windows)} unique windows. Mean\n' + f' baseline latent step: {_fmt(report.step_delta_norm_mean)} (reference only).\n' + ' - Compare values only within the same model and dataset because embedding\n' + ' scales are model-specific. A larger ratio is sensitivity, not by itself a defect.\n' + '\n' + 'All features and raw report fields are exported to\n' + 'feature_axis_embedding_stability.csv and explanation.json.' + ) + fig.text( + 0.06, + 0.43, + interp_text, + ha='left', + va='top', + fontsize=9, + family='monospace', + color='#333333', + ) + + pdf.savefig(fig) + plt.close(fig) + + +@contextmanager +def _normalization_statistics_gradient( + model: torch.nn.Module, *, enabled: bool +): + """Temporarily include supported normalization statistics in autograd.""" + if not enabled: + yield 0 + return + + restores: list[tuple[object, object, bool]] = [] + for module in model.modules(): + if not all( + hasattr(module, name) + for name in ('_get_statistics', '_normalize', 'eps') + ): + continue + + original = module._get_statistics + had_instance_override = '_get_statistics' in vars(module) + + def _get_statistics( + self: Any, x: torch.Tensor, mask: torch.Tensor | None = None + ) -> None: + if mask is None: + mask = torch.ones((x.shape[0], x.shape[-1]), device=x.device) + expanded = ( + mask.to(device=x.device) + .unsqueeze(1) + .expand(-1, x.shape[1], -1) + .bool() + ) + masked_x = torch.where( + expanded, x, torch.full_like(x, float('nan')) + ) + mean = torch.nanmean(masked_x, dim=-1, keepdim=True) + variance = (masked_x - mean).square().nanmean(dim=-1, keepdim=True) + raw_stdev = variance.sqrt() + eps_sq = torch.as_tensor( + float(self.eps) ** 2, + dtype=variance.dtype, + device=variance.device, + ) + safe_stdev = variance.clamp_min(eps_sq).sqrt() + self.mean = mean + self.stdev = ( + raw_stdev.detach() + safe_stdev - safe_stdev.detach() + self.eps + ) + + module._get_statistics = types.MethodType(_get_statistics, module) + restores.append((module, original, had_instance_override)) + + try: + yield len(restores) + finally: + for module, original, had_instance_override in reversed(restores): + if had_instance_override: + module._get_statistics = original + else: + delattr(module, '_get_statistics') + + +def _compute_integrated_gradients_report( + *, + model: torch.nn.Module, + x_context_ct: np.ndarray, + input_mask_l: np.ndarray, + device: torch.device, + channel_labels: list[str], + baseline: Any, + n_steps: int, + n_baselines: int, + internal_batch_size: int | None, + reduce: str, + seed: int, + grad_through_norm: bool, +) -> dict[str, Any]: + """Run embedding integrated gradients for the current SDK context window.""" + from sdm_client.explain._attribution.integrated_gradients import ( + integrated_gradients_embedding, + ) + + x_tensor = torch.as_tensor( + np.asarray(x_context_ct, dtype=np.float32), device=device + ) + input_mask = torch.as_tensor( + np.asarray(input_mask_l, dtype=np.int64), device=device + ) + + def embed_fn(x: torch.Tensor) -> torch.Tensor: + if x.ndim != 3: + raise ValueError( + f'SDK embedding input must be [batch, channels, context], got {tuple(x.shape)}' + ) + mask = ( + input_mask.reshape(1, -1).expand(x.shape[0], -1).to(device=x.device) + ) + with _normalization_statistics_gradient( + model, enabled=grad_through_norm + ): + output = model.embed(x_enc=x, input_mask=mask) + embeddings = ( + output.embeddings if hasattr(output, 'embeddings') else output + ) + return embeddings.reshape(embeddings.shape[0], -1) + + attribution = integrated_gradients_embedding( + embed_fn, + x_tensor, + baseline=baseline, + n_steps=n_steps, + n_baselines=n_baselines, + internal_batch_size=internal_batch_size, + reduce=reduce, + seed=seed, + device=device, + ) + + A = np.asarray(attribution.attribution, dtype=np.float32) + if A.ndim != 2: + raise ValueError( + f'integrated gradients attribution must be [C, L], got shape {A.shape}' + ) + + C, _ = A.shape + labels = ( + channel_labels + if len(channel_labels) == C + else [f'channel_{c}' for c in range(C)] + ) + abs_A = np.abs(A) + channel_abs_effect = abs_A.sum(axis=1).astype(np.float32) + channel_signed_effect = A.sum(axis=1).astype(np.float32) + total_abs = float(channel_abs_effect.sum()) + channel_abs_share = ( + (channel_abs_effect / total_abs).astype(np.float32) + if total_abs > 1e-12 + else np.zeros_like(channel_abs_effect, dtype=np.float32) + ) + time_abs_effect = abs_A.sum(axis=0).astype(np.float32) + top_order = np.argsort(-channel_abs_effect)[: min(10, C)] + + return { + 'attribution': A, + 'channel_labels': labels, + 'channel_abs_effect': channel_abs_effect, + 'channel_signed_effect': channel_signed_effect, + 'channel_abs_share': channel_abs_share, + 'time_abs_effect': time_abs_effect, + 'top_channels': [ + { + 'channel': labels[int(i)], + 'abs_effect': float(channel_abs_effect[int(i)]), + 'signed_effect': float(channel_signed_effect[int(i)]), + 'abs_share': float(channel_abs_share[int(i)]), + } + for i in top_order + ], + 'overall_effect': float(attribution.overall_effect), + 'abs_effect': float(attribution.abs_effect), + 'embedding_delta': float(attribution.embedding_delta), + 'embedding_delta_abs_mean': float(attribution.embedding_delta_abs_mean), + 'convergence_delta': float(attribution.convergence_delta), + 'n_steps': int(attribution.n_steps), + 'n_baselines': int(attribution.n_baselines), + 'baseline': str(attribution.baseline), + 'reduce': str(attribution.reduce), + 'embedding_dim': int(attribution.embedding_dim), + 'grad_through_norm': bool(grad_through_norm), + } + + +def _save_integrated_gradients_artifacts( + out_dir: Path, + integrated_gradients_report: dict[str, Any], + *, + na_rep: str = 'nan', +) -> Path | None: + """Write integrated-gradients CSVs and a signed heatmap PNG.""" + A = np.asarray( + integrated_gradients_report.get('attribution'), dtype=np.float32 + ) + if A.ndim != 2: + return None + C, L = A.shape + labels = integrated_gradients_report.get('channel_labels') + labels = ( + labels + if isinstance(labels, list) and len(labels) == C + else [f'channel_{c}' for c in range(C)] + ) + + df_matrix = pd.DataFrame(A.T, columns=labels) + df_matrix.insert(0, 'lag_from_last', np.arange(L - 1, -1, -1, dtype=int)) + df_matrix.insert(0, 'context_index', np.arange(L, dtype=int)) + df_matrix.to_csv( + out_dir / 'integrated_gradients_attributions.csv', + index=False, + na_rep=na_rep, + ) + + summary = pd.DataFrame( + { + 'channel': labels, + 'signed_effect': np.asarray( + integrated_gradients_report['channel_signed_effect'], + dtype=np.float32, + ), + 'abs_effect': np.asarray( + integrated_gradients_report['channel_abs_effect'], + dtype=np.float32, + ), + 'abs_share': np.asarray( + integrated_gradients_report['channel_abs_share'], + dtype=np.float32, + ), + } + ) + summary.to_csv( + out_dir / 'integrated_gradients_channel_summary.csv', + index=False, + na_rep=na_rep, + ) + + try: + import matplotlib as mpl + + mpl.use('Agg') + import matplotlib.pyplot as plt + except ImportError: + return None + + scale = ( + float(np.nanpercentile(np.abs(A), 99)) if np.isfinite(A).any() else 0.0 + ) + if scale <= 1e-12: + scale = float(np.nanmax(np.abs(A))) if np.isfinite(A).any() else 1.0 + if scale <= 1e-12: + scale = 1.0 + + fig, ax = plt.subplots(figsize=(max(8, L * 0.02), max(4, C * 0.35))) + im = ax.imshow( + A, + aspect='auto', + cmap='coolwarm', + interpolation='nearest', + vmin=-scale, + vmax=scale, + ) + ax.set_xlabel('Input context lag (0 = most recent)') + ax.set_ylabel('Input channel') + ax.set_yticks(range(C)) + ax.set_yticklabels(labels, fontsize=8) + xt = np.linspace(0, L - 1, min(12, L), dtype=int) + ax.set_xticks(xt) + ax.set_xticklabels((L - 1 - xt).astype(int)) + plt.colorbar(im, ax=ax, label='Signed IG attribution') + plt.tight_layout() + heatmap_path = out_dir / 'integrated_gradients_heatmap.png' + plt.savefig(heatmap_path, dpi=120) + plt.close(fig) + return heatmap_path + + +def _integrated_gradients_page( + pdf: Any, + plt: Any, + *, + integrated_gradients_report: dict[str, Any] | None, +) -> None: + """Append one PDF page for embedding integrated gradients.""" + if integrated_gradients_report is None: + return + A = np.asarray( + integrated_gradients_report.get('attribution'), dtype=np.float32 + ) + if A.ndim != 2 or A.shape[0] < 1 or A.shape[1] < 1: + return + C, L = A.shape + labels = integrated_gradients_report.get('channel_labels') + labels = ( + labels + if isinstance(labels, list) and len(labels) == C + else [f'channel_{c}' for c in range(C)] + ) + abs_effect = np.asarray( + integrated_gradients_report.get('channel_abs_effect'), dtype=np.float32 + ) + if abs_effect.shape != (C,): + abs_effect = np.abs(A).sum(axis=1) + + scale = ( + float(np.nanpercentile(np.abs(A), 99)) if np.isfinite(A).any() else 0.0 + ) + if scale <= 1e-12: + scale = float(np.nanmax(np.abs(A))) if np.isfinite(A).any() else 1.0 + if scale <= 1e-12: + scale = 1.0 + + fig = plt.figure(figsize=(11, 8.5)) + fig.text( + 0.5, + 0.95, + 'Integrated gradients (embedding sensitivity)', + ha='center', + fontsize=14, + fontweight='bold', + ) + fig.text( + 0.06, + 0.90, + 'Signed input attributions for the model embedding along the baseline-to-input path.\n' + 'Rows are input channels and columns are the context timesteps; lag 0 is the most\n' + 'recent input. Positive and negative colors show direction, while magnitude shows strength.', + ha='left', + va='top', + fontsize=9, + color='gray', + ) + + ax = fig.add_axes((0.08, 0.38, 0.58, 0.43)) + im = ax.imshow( + A, + aspect='auto', + cmap='coolwarm', + interpolation='nearest', + vmin=-scale, + vmax=scale, + ) + ax.set_xlabel('Input context lag (0 = most recent)') + ax.set_ylabel('Input channel') + ax.set_yticks(range(C)) + ax.set_yticklabels(labels, fontsize=8) + xt = np.linspace(0, L - 1, min(12, L), dtype=int) + ax.set_xticks(xt) + ax.set_xticklabels((L - 1 - xt).astype(int)) + fig.colorbar( + im, ax=ax, fraction=0.046, pad=0.04, label='Signed attribution' + ) + + axb = fig.add_axes((0.74, 0.38, 0.22, 0.43)) + y = np.arange(C) + axb.barh(y, abs_effect, color='#2a9d8f') + axb.set_yticks(y) + axb.set_yticklabels([]) + axb.invert_yaxis() + axb.set_title( + r'Channel effect' '\n' r'($\sum |\mathrm{IG}|$)', + fontsize=9, + math_fontfamily='dejavusans', + ) + axb.set_xlabel('Absolute effect', fontsize=8) + axb.tick_params(axis='both', labelsize=7) + + top_c = int(np.argmax(abs_effect)) + baseline = integrated_gradients_report.get('baseline') + reduce = integrated_gradients_report.get('reduce') + steps = integrated_gradients_report.get('n_steps') + n_baselines = integrated_gradients_report.get('n_baselines') + convergence = _scalar_to_jsonable( + integrated_gradients_report.get('convergence_delta') + ) + emb_delta = _scalar_to_jsonable( + integrated_gradients_report.get('embedding_delta') + ) + grad_norm = bool(integrated_gradients_report.get('grad_through_norm')) + note = ( + 'How to read this page\n' + '---------------------\n' + ' - Heatmap cell (channel c, lag l): signed contribution of that input value\n' + ' to the scalar embedding objective used by integrated gradients.\n' + ' - Right bar: per-channel absolute effect, summed over all context timesteps.\n' + f' - Most influential channel by absolute IG: {labels[top_c]}.\n' + f' - Config: baseline={baseline}, steps={steps}, baselines={n_baselines}, reduce={reduce}.\n' + f' - RevIN/statistics gradient path enabled: {grad_norm}.\n' + f' - Embedding delta: {emb_delta}; convergence delta: {convergence}.\n' + '\n' + 'Full values are exported as integrated_gradients_attributions.csv and\n' + 'integrated_gradients_channel_summary.csv.' + ) + fig.text( + 0.06, + 0.30, + note, + ha='left', + va='top', + fontsize=9, + family='monospace', + color='#333333', + ) + + pdf.savefig(fig) + plt.close(fig) + + +def _build_pdf_report( + pdf_path: Path, + *, + dataset_name: str | None = None, + forecast_df: pd.DataFrame, + explanation: ForecastExplanation, + target_column: str, + timestamp_column: str, + heatmap_path: Path | None, + topk_rows: list[list[str]], + top_k: int, + trajectory_report: TrajectoryStabilityReport | None = None, + feature_axis_embedding_stability_report: PerChannelEmbeddingStabilityReport + | None = None, + context_len: int | None = None, + forecast_horizon: int | None = None, + channel_labels: list[str] | None = None, + feature_axis_stability_channel_labels: list[str] | None = None, + integrated_gradients_report: dict[str, Any] | None = None, +) -> Path | None: + """Compose a multi-page PDF with the forecast and attribution heatmap. + + ``feature_axis_stability_channel_labels`` names the channels the + embedding-stability report is about, which include the series being + forecast. ``channel_labels`` names the ones the channel attribution is + about, which do not. Drawing the stability page under the latter left + the two lists different lengths and the channels numbered instead. + """ + try: + import matplotlib as mpl + + mpl.use('Agg') + import matplotlib.pyplot as plt + from matplotlib.backends.backend_pdf import PdfPages + except ImportError: + return None + + attrib = np.asarray(explanation.lag_horizon_attributions) + K, H = attrib.shape + flow_magnitudes = getattr(explanation, 'flow_magnitudes', None) + show_heatmap = heatmap_path is not None and heatmap_path.exists() + show_topk = bool(topk_rows) + show_semantic_flow = ( + context_len is not None + and forecast_horizon is not None + and flow_magnitudes is not None + and np.asarray(flow_magnitudes).size > 0 + ) + show_trajectory_stability = trajectory_report is not None + show_feature_axis = ( + getattr(explanation, 'channel_horizon_attributions', None) is not None + ) + show_feature_axis_stability = ( + feature_axis_embedding_stability_report is not None + ) + show_integrated_gradients = integrated_gradients_report is not None + + with PdfPages(pdf_path) as pdf: + fig = plt.figure(figsize=(8.5, 11)) + fig.text( + 0.5, + 0.94, + 'Kumo-Forecast Interpretability Report', + ha='center', + fontsize=18, + fontweight='bold', + ) + fig.text( + 0.5, + 0.905, + datetime.now(tz=timezone.utc).strftime('%Y-%m-%d %H:%M:%S UTC'), + ha='center', + fontsize=10, + color='gray', + ) + + sections = [ + section + for available, section in [ + ( + True, + [ + 'Forecast preview: line chart of predicted target values.' + ], + ), + ( + show_heatmap, + [ + 'Lag x Horizon attribution heatmap: how much each past step', + ' contributes to each forecast step.', + ' a) lag=0 is the most recent input.', + ' b) Softmax-normalized weights; brighter cells = time steps', + ' that contribute more to the forecast.', + ], + ), + ( + show_topk, + ['Top-k lag steps per horizon (marginal contributions).'], + ), + ( + show_semantic_flow, + [ + 'Semantic flow magnitudes: per-transition latent flow and', + ' forecast-vs-history diagnostics.', + ], + ), + ( + show_trajectory_stability, + [ + 'Latent trajectory stability: temporal-smoothness metrics', + ' over the context window.', + ], + ), + ( + show_feature_axis, + [ + 'Feature-axis attribution: which input channel drives each', + ' forecast step (multivariate inputs only).', + ], + ), + ( + show_feature_axis_stability, + [ + 'Feature-axis embedding stability: per-channel sensitivity', + ' to small, controlled input changes (multivariate inputs only).', + ], + ), + ( + show_integrated_gradients, + [ + 'Integrated gradients: signed input-channel/time', + ' sensitivity for the model embedding.', + ], + ), + ] + if available + ] + + summary = [ + 'Overview', + '--------', + f'Dataset: {dataset_name or ""}', + f'Target column: {target_column}', + f'Timestamp column: {timestamp_column}', + f'Forecast steps (H): {H}', + f'Lag context size (K): {K}', + '', + 'What is in this report', + '----------------------', + ] + for number, section in enumerate(sections, start=1): + summary.extend([f'{number}. {section[0]}', *section[1:]]) + fig.text( + 0.08, + 0.85, + '\n'.join(summary), + ha='left', + va='top', + fontsize=10, + family='monospace', + ) + pdf.savefig(fig) + plt.close(fig) + + fig, ax = plt.subplots(figsize=(11, 6)) + if ( + timestamp_column in forecast_df.columns + and f'{target_column}_forecast' in forecast_df.columns + ): + ax.plot( + forecast_df[timestamp_column], + forecast_df[f'{target_column}_forecast'], + marker='o', + linewidth=1.5, + ) + ax.set_xlabel(timestamp_column) + ax.set_ylabel(f'{target_column} (forecast, original scale)') + ax.set_title(f'Forecast preview: {target_column}') + fig.autofmt_xdate() + else: + ax.text( + 0.5, 0.5, 'Forecast columns not found', ha='center', va='center' + ) + ax.axis('off') + plt.tight_layout() + pdf.savefig(fig) + plt.close(fig) + + if show_heatmap: + try: + from matplotlib.image import imread + except ImportError: + imread = None + fig = plt.figure(figsize=(11, 8.5)) + if imread is not None: + ax = fig.add_axes((0.05, 0.18, 0.9, 0.72)) + ax.imshow(imread(str(heatmap_path))) + ax.axis('off') + else: + ax = fig.add_axes((0.05, 0.18, 0.9, 0.72)) + ax.text( + 0.5, + 0.5, + 'Heatmap PNG could not be embedded.', + ha='center', + va='center', + ) + ax.axis('off') + fig.text( + 0.5, + 0.94, + 'Lag x Horizon attribution heatmap', + ha='center', + fontsize=14, + fontweight='bold', + ) + fig.text( + 0.5, + 0.10, + 'Vertical axis: lag back from the last observation (0 = most recent).\n' + 'Horizontal axis: forecast step (0 = first predicted step).\n' + 'Brighter = that past step has more influence on that forecast step.', + ha='center', + va='center', + fontsize=9, + color='gray', + ) + pdf.savefig(fig) + plt.close(fig) + + if show_topk: + header = ['Horizon'] + for r in range(1, top_k + 1): + header.extend([f'Rank-{r}\nLag', f'Rank-{r}\nProb']) + + rows_per_page = 30 + chunks = [ + topk_rows[i : i + rows_per_page] + for i in range(0, len(topk_rows), rows_per_page) + ] + num_cols = 1 + 2 * top_k + horizon_col = 0.12 + data_col = max(0.05, (1.0 - horizon_col) / max(1, num_cols - 1)) + col_widths = [horizon_col] + [data_col] * (num_cols - 1) + + for idx, chunk in enumerate(chunks, start=1): + fig = plt.figure(figsize=(11, 8.5)) + fig.text( + 0.5, + 0.95, + f'Top-{top_k} lag steps per horizon (page {idx}/{len(chunks)})', + ha='center', + fontsize=14, + fontweight='bold', + ) + fig.text( + 0.06, + 0.91, + 'Horizon: which forecast step (0 = first predicted step).\n' + 'Rank-r Lag: how many steps back from the last observation ' + 'for the r-th most influential past step\n' + ' (1 = most recent past step). Ranked from highest to ' + 'lowest contribution.\n' + 'Rank-r Prob: marginal softmax weight of that ranked lag step ' + 'on that horizon\n' + ' -- higher means it contributed more to the forecast.', + ha='left', + va='top', + fontsize=9, + color='gray', + ) + + ax = fig.add_axes((0.04, 0.04, 0.92, 0.78)) + ax.axis('off') + table = ax.table( + cellText=chunk, + colLabels=header, + colWidths=col_widths, + loc='upper center', + cellLoc='center', + ) + table.auto_set_font_size(False) + table.set_fontsize(8) + table.scale(1.0, 1.25) + for c in range(len(header)): + cell = table[(0, c)] + cell.set_facecolor('#dddddd') + cell.set_text_props(weight='bold') + cell.set_height(cell.get_height() * 1.6) + + pdf.savefig(fig) + plt.close(fig) + + if show_semantic_flow: + try: + _semantic_flow_page( + pdf, + plt, + explanation=explanation, + context_len=int(context_len), + forecast_horizon=int(forecast_horizon), + ) + except Exception as e: + logger.warning('Semantic flow page skipped: %s', e) + + if show_trajectory_stability: + r = trajectory_report + rows = [ + [ + 'Zero-crossing rate (mean / p95)', + f'{r.zero_crossing_rate_mean:.4f}', + f'{r.zero_crossing_rate_p95:.4f}', + ], + [ + 'Direction-flip rate (mean / p95)', + f'{r.direction_flip_rate_mean:.4f}', + f'{r.direction_flip_rate_p95:.4f}', + ], + [ + 'Relative jitter (mean / p95)', + f'{r.relative_jitter_mean:.4f}', + f'{r.relative_jitter_p95:.4f}', + ], + [ + 'Occupancy positive / negative', + f'{r.occupancy_positive_mean:.4f}', + f'{r.occupancy_negative_mean:.4f}', + ], + [ + 'Latent shape (T / D)', + f'{int(r.n_time_steps)}', + f'{int(r.n_dimensions)}', + ], + ] + + fig = plt.figure(figsize=(11, 8.5)) + fig.text( + 0.5, + 0.95, + 'Latent trajectory stability', + ha='center', + fontsize=14, + fontweight='bold', + ) + fig.text( + 0.06, + 0.90, + 'Per-dimension temporal-smoothness metrics for the latent trajectory.\n' + 'Lower zero-crossing, direction-flip, and relative-jitter values indicate\n' + "a smoother embedding (supports the framework's stability assumption).\n" + r'Relative jitter compares $\mathrm{mean}(|\Delta z|)$ with ' + r'$\mathrm{mean}(|z-z_{\mathrm{center}}|)$.', + ha='left', + va='top', + fontsize=9, + fontfamily='DejaVu Sans', + math_fontfamily='dejavusans', + color='gray', + ) + + ax = fig.add_axes((0.08, 0.45, 0.84, 0.35)) + ax.axis('off') + table = ax.table( + cellText=rows, + colLabels=['Metric', 'Value 1', 'Value 2'], + colWidths=[0.5, 0.25, 0.25], + loc='upper center', + cellLoc='center', + ) + table.auto_set_font_size(False) + table.set_fontsize(9) + table.scale(1.0, 1.4) + for c in range(3): + cell = table[(0, c)] + cell.set_facecolor('#dddddd') + cell.set_text_props(weight='bold') + + interp_text = ( + 'How to read these metrics\n' + '-------------------------\n' + ' - Zero-crossing rate: fraction of consecutive steps where the centered\n' + ' latent value flips sign. Lower => trajectory stays on one side of the\n' + ' reference for longer (less oscillation).\n' + ' - Direction-flip rate: fraction of steps where the latent step direction\n' + ' reverses sign. Lower => monotone, smoother dynamics.\n' + ' - Relative jitter: average latent step size divided by average displacement\n' + ' from the reference. Lower => small smooth steps\n' + ' relative to overall amplitude.\n' + ' - Occupancy positive / negative: fraction of time the centered trajectory\n' + ' sits above / below the deadband. Asymmetry can flag regime drift.\n' + ' - Latent shape (T / D): number of latent time steps and embedding dim;\n' + ' sanity-check that T matches the context length used for this run.\n' + '\n' + 'Pair these with the diagnostics block in explanation.json\n' + '(flow_ratio_forecast_vs_history, curvature_ratio_forecast_vs_history,\n' + 'latent_diag_mahalanobis_ratio_forecast_vs_history) for the forecast-vs-\n' + 'history comparison.' + ) + fig.text( + 0.06, + 0.40, + interp_text, + ha='left', + va='top', + fontsize=9, + family='monospace', + color='#333333', + ) + pdf.savefig(fig) + plt.close(fig) + + # Feature-axis page last (and only for multivariate inputs), matching + # its position in the cover summary. + if show_feature_axis: + try: + _channel_axis_page( + pdf, + plt, + explanation=explanation, + channel_labels=channel_labels, + ) + except Exception as e: + logger.warning('Feature-axis page skipped: %s', e) + + if show_feature_axis_stability: + try: + _feature_axis_embedding_stability_page( + pdf, + plt, + report=feature_axis_embedding_stability_report, + channel_labels=feature_axis_stability_channel_labels + or channel_labels, + ) + except Exception as e: + logger.warning( + 'Feature-axis embedding-stability page skipped: %s', e + ) + + if show_integrated_gradients: + try: + _integrated_gradients_page( + pdf, + plt, + integrated_gradients_report=integrated_gradients_report, + ) + except Exception as e: + logger.warning('Integrated-gradients page skipped: %s', e) + + return pdf_path + + +def _array_to_jsonable(arr: Any) -> Any: + """Convert a numpy array (or torch tensor / scalar / None) into JSON-friendly data.""" + if arr is None: + return None + if isinstance(arr, np.ndarray): + return ( + np.where(np.isfinite(arr), arr, None).tolist() + if arr.dtype.kind == 'f' + else arr.tolist() + ) + try: + return _array_to_jsonable(np.asarray(arr)) + except Exception: + return None + + +def _scalar_to_jsonable(x: Any) -> Any: + if x is None: + return None + try: + v = float(x) + except (TypeError, ValueError): + return None + return v if np.isfinite(v) else None + + +def _trajectory_report_to_dict( + report: TrajectoryStabilityReport | None, +) -> dict[str, Any] | None: + """Convert a TrajectoryStabilityReport into a JSON-friendly dict (or None).""" + if report is None: + return None + return { + 'zero_crossing_rate_mean': _scalar_to_jsonable( + report.zero_crossing_rate_mean + ), + 'zero_crossing_rate_p95': _scalar_to_jsonable( + report.zero_crossing_rate_p95 + ), + 'direction_flip_rate_mean': _scalar_to_jsonable( + report.direction_flip_rate_mean + ), + 'direction_flip_rate_p95': _scalar_to_jsonable( + report.direction_flip_rate_p95 + ), + 'relative_jitter_mean': _scalar_to_jsonable( + report.relative_jitter_mean + ), + 'relative_jitter_p95': _scalar_to_jsonable(report.relative_jitter_p95), + 'occupancy_positive_mean': _scalar_to_jsonable( + report.occupancy_positive_mean + ), + 'occupancy_negative_mean': _scalar_to_jsonable( + report.occupancy_negative_mean + ), + 'n_time_steps': int(report.n_time_steps), + 'n_dimensions': int(report.n_dimensions), + } + + +def _feature_axis_embedding_stability_to_dict( + report: PerChannelEmbeddingStabilityReport | None, + *, + channel_labels: list[str] | None = None, +) -> dict[str, Any] | None: + """Convert a feature-axis embedding-stability report to JSON.""" + if report is None: + return None + frame = _feature_axis_embedding_stability_frame(report, channel_labels) + return { + 'channel_labels': frame['feature'].tolist(), + 'lip_ratio_mean': _array_to_jsonable( + frame['lip_ratio_mean'].to_numpy() + ), + 'lip_ratio_p50': _array_to_jsonable(frame['lip_ratio_p50'].to_numpy()), + 'lip_ratio_p95': _array_to_jsonable(frame['lip_ratio_p95'].to_numpy()), + 'lip_ratio_max': _array_to_jsonable(frame['lip_ratio_max'].to_numpy()), + 'n_trials_per_channel': _array_to_jsonable( + frame['n_trials_per_channel'].to_numpy() + ), + 'n_unique_windows': int(report.n_unique_windows), + 'step_delta_norm_mean': _scalar_to_jsonable( + report.step_delta_norm_mean + ), + } + + +def _integrated_gradients_to_dict( + integrated_gradients_report: dict[str, Any] | None, + *, + include_full_arrays: bool = True, +) -> dict[str, Any] | None: + """Convert an integrated-gradients report into a JSON-friendly dict.""" + if integrated_gradients_report is None: + return None + + payload: dict[str, Any] = { + 'baseline': integrated_gradients_report.get('baseline'), + 'reduce': integrated_gradients_report.get('reduce'), + 'n_steps': int(integrated_gradients_report.get('n_steps', 0)), + 'n_baselines': int(integrated_gradients_report.get('n_baselines', 0)), + 'embedding_dim': int( + integrated_gradients_report.get('embedding_dim', 0) + ), + 'grad_through_norm': bool( + integrated_gradients_report.get('grad_through_norm', False) + ), + 'overall_effect': _scalar_to_jsonable( + integrated_gradients_report.get('overall_effect') + ), + 'abs_effect': _scalar_to_jsonable( + integrated_gradients_report.get('abs_effect') + ), + 'embedding_delta': _scalar_to_jsonable( + integrated_gradients_report.get('embedding_delta') + ), + 'embedding_delta_abs_mean': _scalar_to_jsonable( + integrated_gradients_report.get('embedding_delta_abs_mean') + ), + 'convergence_delta': _scalar_to_jsonable( + integrated_gradients_report.get('convergence_delta') + ), + 'channel_labels': list( + integrated_gradients_report.get('channel_labels', []) + ), + 'channel_signed_effect': _array_to_jsonable( + integrated_gradients_report.get('channel_signed_effect') + ), + 'channel_abs_effect': _array_to_jsonable( + integrated_gradients_report.get('channel_abs_effect') + ), + 'channel_abs_share': _array_to_jsonable( + integrated_gradients_report.get('channel_abs_share') + ), + 'top_channels': integrated_gradients_report.get('top_channels', []), + } + if include_full_arrays: + payload['attribution'] = _array_to_jsonable( + integrated_gradients_report.get('attribution') + ) + payload['time_abs_effect'] = _array_to_jsonable( + integrated_gradients_report.get('time_abs_effect') + ) + return payload + + +def _explanation_to_dict( + forecast_df: pd.DataFrame, + explanation: ForecastExplanation, + *, + target_column: str, + timestamp_column: str = 'timestamp', + dataset_name: str | None = None, + include_full_arrays: bool = True, + trajectory_report: TrajectoryStabilityReport | None = None, + feature_axis_embedding_stability_report: PerChannelEmbeddingStabilityReport + | None = None, + channel_labels: list[str] | None = None, + integrated_gradients_report: dict[str, Any] | None = None, +) -> dict[str, Any]: + """Render the (forecast, explanation) pair as a JSON-serializable dict.""" + fc = forecast_df.copy() + if timestamp_column in fc.columns and pd.api.types.is_datetime64_any_dtype( + fc[timestamp_column] + ): + fc[timestamp_column] = fc[timestamp_column].dt.strftime( + '%Y-%m-%dT%H:%M:%S' + ) + forecast_records = fc.to_dict(orient='records') + + base = np.asarray(explanation.baseline_forecast) + scores = np.asarray(explanation.lag_horizon_scores) + attrib = np.asarray(explanation.lag_horizon_attributions) + C, H = base.shape if base.ndim == 2 else (None, None) + K = attrib.shape[0] if attrib.ndim == 2 else None + + surrogate_block: dict[str, Any] | None + if explanation.surrogate_coef is not None: + surrogate_block = { + 'coef': _array_to_jsonable(explanation.surrogate_coef), + 'intercept': _array_to_jsonable(explanation.surrogate_intercept), + 'feature_layout': explanation.surrogate_feature_layout, + } + else: + surrogate_block = None + + explanation_block: dict[str, Any] = { + 'shapes': { + 'C_channels': int(C) if C is not None else None, + 'H_horizon': int(H) if H is not None else None, + 'K_lags': int(K) if K is not None else None, + }, + 'baseline_forecast': _array_to_jsonable(base), + 'lag_horizon_scores': _array_to_jsonable(scores), + 'lag_horizon_attributions': _array_to_jsonable(attrib), + 'surrogate': surrogate_block, + 'diagnostics': { + 'flow_ratio_forecast_vs_history': _scalar_to_jsonable( + explanation.flow_ratio_forecast_vs_history + ), + 'flow_variance_ratio_forecast_vs_history': _scalar_to_jsonable( + explanation.flow_variance_ratio_forecast_vs_history + ), + 'curvature_ratio_forecast_vs_history': _scalar_to_jsonable( + explanation.curvature_ratio_forecast_vs_history + ), + 'latent_diag_mahalanobis_ratio_forecast_vs_history': _scalar_to_jsonable( + explanation.latent_diag_mahalanobis_ratio_forecast_vs_history + ), + 'latent_trajectory_shape': ( + list(np.asarray(explanation.latent_trajectory).shape) + if getattr(explanation, 'latent_trajectory', None) is not None + else None + ), + }, + 'trajectory_stability': _trajectory_report_to_dict(trajectory_report), + } + + # Feature-axis (channel) attribution -- only present for multivariate inputs. + chan_attrib = getattr(explanation, 'channel_horizon_attributions', None) + stability_block = _feature_axis_embedding_stability_to_dict( + feature_axis_embedding_stability_report, + channel_labels=channel_labels, + ) + if chan_attrib is not None or stability_block is not None: + feature_axis: dict[str, Any] = {} + if chan_attrib is not None: + feature_axis.update( + { + 'method': getattr(explanation, 'channel_flow_method', None), + 'channel_horizon_attributions': _array_to_jsonable( + np.asarray(chan_attrib) + ), + 'residual_ratio_mean': _scalar_to_jsonable( + explanation.channel_flow_residual_ratio_mean + ), + 'residual_ratio_p95': _scalar_to_jsonable( + explanation.channel_flow_residual_ratio_p95 + ), + } + ) + if ( + include_full_arrays + and getattr(explanation, 'per_channel_flow', None) is not None + ): + feature_axis['per_channel_flow'] = _array_to_jsonable( + np.asarray(explanation.per_channel_flow) + ) + if stability_block is not None: + feature_axis['embedding_stability'] = stability_block + explanation_block['feature_axis'] = feature_axis + + if include_full_arrays: + explanation_block['flow_magnitudes'] = _array_to_jsonable( + explanation.flow_magnitudes + ) + explanation_block['latent_trajectory'] = _array_to_jsonable( + explanation.latent_trajectory + ) + + ig_block = _integrated_gradients_to_dict( + integrated_gradients_report, + include_full_arrays=include_full_arrays, + ) + if ig_block is not None: + explanation_block['integrated_gradients'] = ig_block + + return { + 'metadata': { + 'dataset_name': dataset_name, + 'target_column': target_column, + 'timestamp_column': timestamp_column, + 'generated_at': datetime.now(tz=timezone.utc).strftime( + '%Y-%m-%dT%H:%M:%SZ' + ), + 'include_full_arrays': bool(include_full_arrays), + }, + 'forecast': forecast_records, + 'explanation': explanation_block, + } + + +def _save_explanation_json( + *, + forecast_df: pd.DataFrame, + explanation: ForecastExplanation, + path: str | Path, + target_column: str, + timestamp_column: str = 'timestamp', + dataset_name: str | None = None, + include_full_arrays: bool = True, + indent: int | None = 2, + trajectory_report: TrajectoryStabilityReport | None = None, + feature_axis_embedding_stability_report: PerChannelEmbeddingStabilityReport + | None = None, + channel_labels: list[str] | None = None, + integrated_gradients_report: dict[str, Any] | None = None, +) -> Path: + """Persist the (forecast, explanation) pair as a JSON file.""" + out_path = Path(path) + out_path.parent.mkdir(parents=True, exist_ok=True) + + payload = _explanation_to_dict( + forecast_df, + explanation, + target_column=target_column, + timestamp_column=timestamp_column, + dataset_name=dataset_name, + include_full_arrays=include_full_arrays, + trajectory_report=trajectory_report, + feature_axis_embedding_stability_report=feature_axis_embedding_stability_report, + channel_labels=channel_labels, + integrated_gradients_report=integrated_gradients_report, + ) + with out_path.open('w', encoding='utf-8') as fh: + json.dump(payload, fh, indent=indent, allow_nan=False) + return out_path diff --git a/packages/structured-data-models-client/src/sdm_client/explain/_explain.py b/packages/structured-data-models-client/src/sdm_client/explain/_explain.py new file mode 100644 index 000000000..d3b9eef95 --- /dev/null +++ b/packages/structured-data-models-client/src/sdm_client/explain/_explain.py @@ -0,0 +1,375 @@ +# SPDX-FileCopyrightText: Copyright (c) 2026, NVIDIA CORPORATION & AFFILIATES. +# All rights reserved. +# SPDX-License-Identifier: Apache-2.0 + +r"""Running the attribution over a history, and saying what it found. + +The ported pipeline wants the context as channels by steps and the model +behind a protocol; the client holds a history as a frame and a loaded +structured-data-models forecaster. This is what stands between them, and the +dict it returns is what travels as the ``explanation`` output field. +""" + +from __future__ import annotations + +from dataclasses import replace +from typing import Any + +import numpy as np +import pandas as pd + +from sdm_client.errors import StructuredDataError + +#: How far back the lag attribution looks, and how finely. Upstream's +#: defaults; both cost time roughly in proportion. +_LAGS = 128 + +#: How many times each channel is nudged when the stability of the embedding +#: is measured. Upstream's default, named here because the memory the probes +#: take is worked out from it before they are built. +_STABILITY_TRIALS = 30 + +#: The most the stability probes may take. They are one window per channel +#: per trial and a copy of each, so the memory grows with the square of the +#: number of channels: forty channels of a 512-step window is already most of +#: a gigabyte once both stacks are counted. +_STABILITY_BYTES = 256 * 1024 * 1024 + +#: How finely the path from a reference window to the real one is walked +#: when the embedding is attributed step by step, and how many of those +#: points are embedded at once. Upstream's step count; the batch bounds the +#: activations rather than the answer, which does not depend on it. +_GRADIENT_STEPS = 64 +_GRADIENT_BATCH = 8 + +#: What of the embedding the attribution explains the movement of. Upstream +#: explains the length of it, which cannot be the answer here: this +#: forecaster's embedding is a retrieval key and is scaled to unit length +#: before it is returned, so its length is one whatever it was given, and +#: attributing a constant attributed nothing. Measured on the published +#: weights: the length moved by 2e-07 between a real window and a reference +#: one and every reading came back a billionth, where the sum moves and is +#: explained. +_GRADIENT_OBJECTIVE = 'sum' + + +def explanation_of( + model: Any, + history: np.ndarray, + *, + channels: list[str], + target: str, + horizon: int, + forecast: np.ndarray, + feature_axis: bool = False, + integrated_gradients: bool = False, +) -> dict[str, Any]: + r"""Attribute ``forecast`` to the history it was made from. + + Args: + model: The loaded ``sdm.models.KumoForecast``. + history: The context as ``[C, R]``, channels by steps, in the order + ``channels`` names them. + channels: What each channel is called. + target: Which of them was forecast. + horizon: How many steps were asked for. + forecast: What came back, one value per step. + feature_axis: Also attribute across channels rather than only across + lags. It costs several times the rest put together. + integrated_gradients: Also attribute the model's own reading of the + window, reading by reading, by walking the path from a reference + window to this one. It is the only attribution here that reads + the model's gradients rather than watching its output move. + + Raises: + StructuredDataError: If the history is shorter than the model reads, + if the forecaster cannot mix channels while more than one + travelled, or, for the feature axis, if the window it reads has + a gap in it or the horizon runs past one forward pass. + + Without channel mixing and without retrieval, a column measured + alongside the series cannot reach the forecast at all, while the + embedding still pools it, so an attribution would move when it moves and + report an influence the forecast does not have. Feature-axis attribution + replaces a channel with its own average over the window it reads, and a + gap makes that average undefined, which reads as a channel with no + influence: a confident answer about a column nothing was learnt about. + Both are refused rather than reported. + + The window is standardised first, as the model's own path standardises + before it reads anything, so the attribution works in the space the + model works in. Handing it raw readings attributed a model being fed + numbers it never sees. + """ + + from sdm_client.explain._attribution.interpretability import ( + explain_forecast, + ) + from sdm_client.explain._model import Forecaster + + forecaster = Forecaster(model) + if history.shape[-1] < forecaster.context_size: + raise StructuredDataError( + f'an explanation attributes a forecast to the window the model ' + f'reads, which is {forecaster.context_size} steps, and this ' + f'history is {history.shape[-1]}', + code='UNSUPPORTED_SHAPE', + ) + if len(channels) > 1 and not forecaster.mixes_channels: + raise StructuredDataError( + 'this forecaster does not mix channels, so nothing measured ' + 'alongside the series can reach the forecast, and an attribution ' + 'over them would report an influence there is none of. Explain a ' + 'history of the series alone, or use a forecaster that mixes ' + 'channels', + code='UNSUPPORTED_REQUEST', + ) + window_only = history[..., -forecaster.context_size :] + over_the_window = [ + name + for name, asked in ( + ('the feature axis', feature_axis), + ('integrated gradients', integrated_gradients), + ) + if asked + ] + if over_the_window and not np.isfinite(window_only).all(): + raise StructuredDataError( + f'this explanation was asked for ' + f'{" and ".join(over_the_window)}, and each of those measures ' + f'against a baseline worked out from the window it reads -- a ' + f'channel replaced by its own average, or the window replaced by ' + f'noise. A gap makes that baseline undefined, and every ' + f'attribution taken against it is then NaN, which reads as no ' + f'influence at all. The window is the last ' + f'{forecaster.context_size} steps; fill its gaps, or ask for the ' + f'explanation without them', + code='UNSUPPORTED_SHAPE', + ) + if feature_axis and horizon > forecaster.prediction_size: + raise StructuredDataError( + f'feature-axis attribution reads one forward pass, which covers ' + f'{forecaster.prediction_size} steps, and this forecast is ' + f'{horizon}. Ask for it over a horizon the model reaches in one ' + f'pass, or ask for the explanation without it', + code='UNSUPPORTED_SHAPE', + ) + device = next(model.parameters()).device + window = _standardised(model, window_only) + explanation = explain_forecast( + forecaster, + x_context_ct=np.ascontiguousarray(window, dtype='float32'), + input_mask_l=np.ones(forecaster.context_size, dtype='float32'), + model_horizon=forecaster.prediction_size, + forecast_horizon=horizon, + device=device, + n_lags=min(_LAGS, forecaster.context_size), + surrogate=False, + channel_axis=feature_axis, + channel_target=channels.index(target) if feature_axis else None, + channel_output_aware=feature_axis, + ) + return _as_dict( + model, + explanation, + channels, + target, + horizon, + forecast, + smoothness=_smoothness_of(explanation, forecaster.context_size), + stability=( + _stability_of(forecaster, window, device) if feature_axis else None + ), + gradients=( + _gradients_of(forecaster, window, channels, device) + if integrated_gradients + else None + ), + ) + + +def _smoothness_of(explanation: Any, context_size: int) -> Any: + r"""How smoothly the model's latent state moved over the history. + + Read off the trajectory the attribution already walked rather than walked + again. That trajectory runs the history and then the forecast, one state + per step, and its first ``context_size`` states are exactly the states a + second walk over the history alone would produce, because each one is the + window ending at its own step and the forecast is not in any of them. + """ + from sdm_client.explain._attribution.interpretability import ( + summarize_trajectory_stability, + ) + + trajectory = np.asarray(explanation.latent_trajectory) + history = trajectory[:context_size] + if history.shape[0] < 2: + return None + return summarize_trajectory_stability(history) + + +def _stability_of(forecaster: Any, window: np.ndarray, device: Any) -> Any: + r"""How much the embedding moves when one channel is nudged. + + Asked for alongside the feature axis, because it answers the question the + feature axis raises: an influence attributed to a channel the embedding + treats erratically is an influence measured through a derivative that is + not there. + """ + import warnings + + from sdm_client.core.warnings import SDMWarning + from sdm_client.explain._attribution.channel_stability import ( + compute_per_channel_embedding_stability, + ) + + channels, steps = window.shape + probes = 2 * (1 + _STABILITY_TRIALS * channels) * channels * steps * 4 + if probes > _STABILITY_BYTES: + warnings.warn( + f'the stability of the embedding is measured by nudging each of ' + f'these {channels} channels {_STABILITY_TRIALS} times, which ' + f'would take {probes // (1024 * 1024)} MiB of probes at once. ' + f'That page is left out of this explanation; the rest of the ' + f'feature axis is not', + SDMWarning, + stacklevel=2, + ) + return None + return compute_per_channel_embedding_stability( + forecaster, + np.ascontiguousarray(window, dtype='float32'), + seq_len=int(steps), + input_mask_t=np.ones(steps, dtype='float32'), + device=device, + n_trials=_STABILITY_TRIALS, + ) + + +def _standardised(model: Any, window: np.ndarray) -> np.ndarray: + r"""``window`` through the model's own frozen standardisation.""" + import pandas as pd + from sdm import TableTensor + + frame = pd.DataFrame( + {str(i): row for i, row in enumerate(np.asarray(window, dtype=float))} + ) + table = TableTensor.from_pandas( + frame, dict.fromkeys(frame.columns, 'numerical') + ) + standardised = model.default_recipe().target.transform(table) + return standardised.numerical.detach().cpu().numpy().T + + +def _in_original_scale(model: Any, values: np.ndarray) -> np.ndarray: + r"""The inverse of :func:`_standardised`, for what is drawn.""" + import pandas as pd + from sdm import TableTensor + + array = np.asarray(values, dtype=float) + frame = pd.DataFrame({str(i): row for i, row in enumerate(array)}) + table = TableTensor.from_pandas( + frame, dict.fromkeys(frame.columns, 'numerical') + ) + restored = model.default_recipe().target.inverse_transform(table) + return restored.numerical.detach().cpu().numpy().T + + +def _gradients_of( + forecaster: Any, window: np.ndarray, channels: list[str], device: Any +) -> Any: + r"""What the model read, reading by reading, by integrated gradients. + + Held inside the forecaster's differentiable normalisation, because a + gradient taken outside it describes a forward pass with each window's own + statistics frozen, which is a different pass from the one that answered. + What that costs is measurable and was measured, on the published + weights because an untrained forecaster's embedding barely moves at all + and the measure divides by how far it moved: an attribution has to add + up to the movement it explains, and taken outside this it accounted for + none of that movement and overshot it by half again, where taken inside + it accounts for all but a twenty-fifth of a percent. The ported code offers + a patch of its own for the same purpose and finds nothing to patch here, + since it looks for a method this forecaster spells another way; the flag + it records is true either way, and true. + """ + from sdm_client.explain._attribution.pages import ( + _compute_integrated_gradients_report, + ) + + with forecaster.differentiable_normalisation(): + return _compute_integrated_gradients_report( + model=forecaster, + x_context_ct=np.ascontiguousarray(window, dtype='float32'), + input_mask_l=np.ones(window.shape[-1], dtype='float32'), + device=device, + channel_labels=list(channels), + baseline='noise', + n_steps=_GRADIENT_STEPS, + n_baselines=1, + internal_batch_size=_GRADIENT_BATCH, + reduce=_GRADIENT_OBJECTIVE, + seed=0, + grad_through_norm=True, + ) + + +def _as_dict( + model: Any, + explanation: Any, + channels: list[str], + target: str, + horizon: int, + forecast: np.ndarray, + *, + smoothness: Any = None, + stability: Any = None, + gradients: Any = None, +) -> dict[str, Any]: + r"""The explanation as the contract carries one: plain JSON data. + + Rendered by the code that drew it, so a report built from this and one + built where that code came from say the same things in the same words. + + The attribution works standardised, so what it calls the baseline + forecast is standardised too, and the report draws it beside readings; + it is put back in their scale before it travels. The channel labels + travel with every explanation rather than only with the feature axis, + which is where that code keeps them: the client knows them either way, + and a report that cannot say which channel is which is harder to read + than one that can. + + The feature axis perturbs each channel and watches the forecast move. + Perturbing the series being forecast moves it by construction, so that + channel's own effect is set aside rather than measured and reaches the + page as a zero beside measured numbers. Saying which channel that was is + what keeps a reader from taking it for the least influential one. + """ + from sdm_client.explain._attribution.pages import _explanation_to_dict + + explanation = replace( + explanation, + baseline_forecast=_in_original_scale( + model, np.asarray(explanation.baseline_forecast) + ), + ) + frame = pd.DataFrame( + { + 'forecast_step': range(1, horizon + 1), + f'{target}_forecast': np.asarray(forecast, dtype='float32'), + } + ) + rendered = _explanation_to_dict( + frame, + explanation, + target_column=target, + timestamp_column='forecast_step', + channel_labels=list(channels), + trajectory_report=smoothness, + feature_axis_embedding_stability_report=stability, + integrated_gradients_report=gradients, + ) + rendered.setdefault('metadata', {})['channel_labels'] = list(channels) + if rendered.get('explanation', {}).get('feature_axis'): + rendered['metadata']['feature_axis_excludes'] = target + return rendered diff --git a/packages/structured-data-models-client/src/sdm_client/explain/_model.py b/packages/structured-data-models-client/src/sdm_client/explain/_model.py new file mode 100644 index 000000000..c12b873a0 --- /dev/null +++ b/packages/structured-data-models-client/src/sdm_client/explain/_model.py @@ -0,0 +1,207 @@ +# SPDX-FileCopyrightText: Copyright (c) 2026, NVIDIA CORPORATION & AFFILIATES. +# All rights reserved. +# SPDX-License-Identifier: Apache-2.0 + +r"""structured-data-models' forecaster, as the attribution code expects one. + +The ported attribution is written against a protocol of two methods rather +than against a class: a forward pass that returns a forecast, and an embedding +pass that returns one vector per window. structured-data-models' forecaster +has both, under its own names, so what stands between them is this. + +The embedding is the model's own, the one it builds retrieval keys from. An +attribution is a statement about what the model did, so reducing its encoder +output some other way here would attribute something the model never computed. + +The windows it is handed are padded, and which steps are padding arrives as a +mask. structured-data-models' forecaster takes no mask: it reads an +unobserved step as ``NaN``, and its normalisation ignores those when it takes +a window's statistics. So the mask is applied as ``NaN`` here. Dropping it +instead made padding into observed zeros, and a flat series then showed the +latent trajectory moving when it had not. +""" + +from __future__ import annotations + +from collections.abc import Iterator +from contextlib import contextmanager +from dataclasses import dataclass +from typing import Any + +import torch + + +@dataclass(frozen=True) +class _Forecast: + forecast: torch.Tensor + + +@dataclass(frozen=True) +class _Embedding: + embeddings: torch.Tensor + + +class Forecaster: + r"""Wraps ``sdm.models.KumoForecast`` for the attribution code. + + Args: + model: The loaded ``KumoForecast``. + """ + + def __init__(self, model: Any) -> None: + self._inner = model.model + + @property + def context_size(self) -> int: + r"""How many steps the model reads.""" + return int(self._inner.context_size) + + @property + def mixes_channels(self) -> bool: + r"""Whether a channel can reach the forecast of another one. + + Without it, a column measured alongside the series contributes + nothing to the forecast, though the embedding still pools it. + """ + return self._inner.cross_channel is not None + + def modules(self) -> Iterator[torch.nn.Module]: + r"""The forecaster's own modules, for code that walks them.""" + return self._inner.modules() + + @contextmanager + def differentiable_normalisation(self) -> Iterator[None]: + r"""The forecaster with its normalisation carrying gradients. + + Each window is divided by statistics taken over the window itself, + and those are taken without gradients. A gradient through the model + as it stands therefore measures what a step does with the mean and + the spread of its own window held still, which is not what the step + does: the attribution came out some hundreds of times larger than the + change the same perturbation actually makes. + + So the statistics are taken again, differentiably, for as long as + this is held. Everything else about the forward pass is unchanged, + and the numbers it produces are the same ones. + + What each module had before is put back rather than deleted. Two of + these held at once over the same forecaster left the inner one + deleting the outer one's patch on its way out, and the outer one + then raising on a name that was no longer there; a module that + carried its own statistics before any of this lost them outright. + """ + from sdm.nn import RevIN + + held: list[tuple[torch.nn.Module, bool, Any]] = [] + try: + for module in self._inner.modules(): + if not isinstance(module, RevIN): + continue + held.append( + ( + module, + 'stats' in module.__dict__, + module.__dict__.get('stats'), + ) + ) + module.stats = _statistics + yield + finally: + for module, had_its_own, previous in reversed(held): + if had_its_own: + module.stats = previous + else: + module.__dict__.pop('stats', None) + + @property + def prediction_size(self) -> int: + r"""How many steps it forecasts in one pass.""" + return int(self._inner.prediction_size) + + def __call__( + self, *, x_enc: torch.Tensor, input_mask: torch.Tensor | None = None + ) -> _Forecast: + r"""The forecast for ``x_enc`` of shape ``[B, C, R]``. + + Deliberately not differentiable. The attribution reaches for autograd + where the forecast carries gradients and falls back to finite + differences where it does not, and autograd is the wrong answer for + this forecaster: it normalises each window by statistics it takes + without gradients, so a gradient through it measures sensitivity with + that normalisation held still. It came out some hundreds of times + larger than the difference the same perturbation actually makes. + + The upstream package patches its own normaliser to carry those + gradients, by a method name this one does not have, so the patch + finds nothing here and passes in silence. + """ + with torch.no_grad(): + return _Forecast(forecast=self._inner(_observed(x_enc, input_mask))) + + def embed( + self, *, x_enc: torch.Tensor, input_mask: torch.Tensor | None = None + ) -> _Embedding: + r"""One embedding per window of ``x_enc``, shaped ``[B, D]``.""" + return _Embedding(embeddings=self.embed_tensor(x_enc, input_mask)) + + def embed_tensor( + self, x_enc: torch.Tensor, input_mask: torch.Tensor | None = None + ) -> torch.Tensor: + r"""The embedding as a plain tensor, differentiably. + + Kept apart from :meth:`embed` because integrated gradients needs the + path from the input to it to carry gradients, and the protocol's own + method is called where they are not wanted. + """ + from sdm.models.kumo.timeseries.forecast.darr import embed + + encoded, _, _ = self._inner.encode(_observed(x_enc, input_mask)) + return embed(encoded) + + +def _observed(x: torch.Tensor, mask: torch.Tensor | None) -> torch.Tensor: + r"""``x`` with the steps the mask calls padding marked unobserved. + + The forecaster has no mask argument and reads ``NaN`` as unobserved: its + normalisation takes a window's statistics over what is there, and zeroes + what is not once they are taken. + + The mask's last axis is steps and anything before it is the window the + steps belong to; the readings have a channel axis between the two. It is + one mask for every channel of a window, so the channel axis is where the + singleton goes. + """ + if mask is None: + return x + keep = torch.as_tensor(mask, device=x.device).bool() + if keep.all(): + return x + keep = keep.unsqueeze(-2) + while keep.ndim < x.ndim: + keep = keep.unsqueeze(0) + return x.masked_fill(~keep.expand_as(x), float('nan')) + + +def _statistics( + x: torch.Tensor, + mask: torch.Tensor | None = None, + correction: int = 1, +) -> tuple[torch.Tensor, torch.Tensor]: + r"""``RevIN.stats``, computed so that gradients reach the input. + + The same arithmetic as the method it stands in for, which is what makes + the forward pass it takes part in produce the same numbers. + """ + if mask is not None: + x = x.masked_fill(mask, torch.nan) + x = x.double() + mean = x.nanmean(dim=-1, keepdim=True) + variance = (x - mean).square().nanmean(dim=-1, keepdim=True) + if correction != 0: + count = (~x.isnan()).sum(dim=-1, keepdim=True) + variance = variance * ( + count.double() / (count - correction).clamp(min=1) + ) + deviation = variance.sqrt() + absent = mean.isnan() + return mean.masked_fill(absent, 0.0), deviation.masked_fill(absent, 1.0) diff --git a/packages/structured-data-models-client/src/sdm_client/in_process/forecast.py b/packages/structured-data-models-client/src/sdm_client/in_process/forecast.py index 524d34560..bff8546e8 100644 --- a/packages/structured-data-models-client/src/sdm_client/in_process/forecast.py +++ b/packages/structured-data-models-client/src/sdm_client/in_process/forecast.py @@ -20,6 +20,7 @@ from __future__ import annotations from collections.abc import Mapping, Sequence +from dataclasses import replace from typing import Any from sdm_api.generated.tfm_api import PredictionItem @@ -39,14 +40,20 @@ _NEIGHBOURS = 64 _TEMPERATURE = 0.05 -_KNOBS = ('alpha', 'k', 'temperature') +_KNOBS = ( + 'alpha', + 'k', + 'temperature', + 'feature_axis', + 'integrated_gradients', +) class Forecast: r"""Reads a ``kumo-forecast`` request into the model.""" model_id = 'kumo-forecast' - outputs = {'forecasting': ('prediction',)} + outputs = {'forecasting': ('prediction', 'explanation')} @staticmethod def installed() -> bool: @@ -228,10 +235,90 @@ def answer( 'the model answered with a malformed output', code='INTERNAL_ERROR', ) - return [ + items = [ PredictionItem(row_index=0, forecast_step=step, prediction=value) for step, value in enumerate(forecast.tolist(), start=1) ] + if 'explanation' in fields: + self._refuse_where_retrieval_answered( + model, + alpha, + len(payload['context']['instance_table']['rows']), + horizon, + ) + if 'explanation' in fields and items: + items[0] = replace( + items[0], + explanation=self._explained( + model, payload, target, horizon, forecast, alongside + ), + ) + return items + + def _explained( + self, + model: Any, + payload: Mapping[str, Any], + target: str, + horizon: int, + forecast: Any, + alongside: Any, + ) -> dict[str, Any]: + r"""Why that forecast, attributed to the history it was made from. + + The attribution reads the model's gradients and walks its latent + trajectory, so it reads the model itself rather than its answer, and + exists only where the model runs here. + """ + from sdm_client.explain import explanation_of + + table = payload['context']['instance_table'] + spec = payload['schema']['instance_table'] + keys = key_columns(spec) - {target} + channels = [name for name in table['columns'] if name not in keys] + history = Shape.of(spec, dict.fromkeys(channels, 'numerical')).tensor( + table, 'the history' + ) + options = payload.get('inference') or {} + return explanation_of( + model, + history.numerical.detach().cpu().numpy().T, + channels=channels, + target=target, + horizon=horizon, + forecast=forecast.detach().cpu().numpy(), + feature_axis=bool(options.get('feature_axis', False)), + integrated_gradients=bool( + options.get('integrated_gradients', False) + ), + ) + + @staticmethod + def _refuse_where_retrieval_answered( + model: Any, alpha: float, history: int, horizon: int + ) -> None: + r"""Refuse to explain a forecast retrieval had a hand in. + + The attribution describes the model's own forward pass. Where + retrieval contributes, the forecast returned is a blend of that pass + and windows pulled from history, and attributing the pass would + describe a number nobody was given. + """ + if alpha >= 1.0: + return + needed = model.model.context_size + max( + model.model.prediction_size, horizon + ) + if history < needed: + return + raise StructuredDataError( + f'alpha={alpha} blends retrieved history into this forecast, and ' + f"an explanation describes the model's own forward pass only. " + f'Explaining it would describe a forecast that was not returned. ' + f'Ask for the explanation with alpha=1, or ask for the forecast ' + f'without one', + code='UNSUPPORTED_REQUEST', + ) @staticmethod def _warn_where_retrieval_does_nothing( diff --git a/packages/structured-data-models-client/src/sdm_client/models.py b/packages/structured-data-models-client/src/sdm_client/models.py index fd45023f0..9ab71b5cf 100644 --- a/packages/structured-data-models-client/src/sdm_client/models.py +++ b/packages/structured-data-models-client/src/sdm_client/models.py @@ -197,9 +197,17 @@ profile=TIMESERIES, runtime=RuntimeContract( tasks=frozenset({'forecasting'}), - outputs=frozenset({'prediction'}), + outputs=frozenset({'prediction', 'explanation'}), sessions=False, - inference_options=frozenset({'alpha', 'k', 'temperature'}), + inference_options=frozenset( + { + 'alpha', + 'k', + 'temperature', + 'feature_axis', + 'integrated_gradients', + } + ), ), ) diff --git a/packages/structured-data-models-client/src/sdm_client/reporting/__init__.py b/packages/structured-data-models-client/src/sdm_client/reporting/__init__.py index 5064ac7af..1330ed172 100644 --- a/packages/structured-data-models-client/src/sdm_client/reporting/__init__.py +++ b/packages/structured-data-models-client/src/sdm_client/reporting/__init__.py @@ -10,5 +10,6 @@ """ from sdm_client.reporting.anomaly import anomaly_report +from sdm_client.reporting.forecast import forecast_report -__all__ = ['anomaly_report'] +__all__ = ['anomaly_report', 'forecast_report'] diff --git a/packages/structured-data-models-client/src/sdm_client/reporting/forecast.py b/packages/structured-data-models-client/src/sdm_client/reporting/forecast.py new file mode 100644 index 000000000..7655829b6 --- /dev/null +++ b/packages/structured-data-models-client/src/sdm_client/reporting/forecast.py @@ -0,0 +1,414 @@ +# SPDX-FileCopyrightText: Copyright (c) 2026, NVIDIA CORPORATION & AFFILIATES. +# All rights reserved. +# SPDX-License-Identifier: Apache-2.0 + +r"""A forecast explanation, drawn as it was written to be drawn. + +What is new is that the pages are drawn from an explanation that travelled as +data: the client carries one as the contract's ``explanation`` field, plain +JSON, because that is what an output field is. The arrays the pages read are +all in it, so the drawing reads them back. + +A page whose data is not there is not drawn. Feature-axis attribution is the +one that is usually absent, because it costs several times the rest and is +asked for separately. +""" + +from __future__ import annotations + +import json +import math +import numbers +import tempfile +from collections.abc import Iterator +from contextlib import contextmanager +from pathlib import Path +from typing import TYPE_CHECKING, Any + +import numpy as np + +from sdm_client.errors import MissingExtraError, StructuredDataError + +if TYPE_CHECKING: # pragma: no cover - imported for typing only. + from sdm_client.result import PredictionResult + + +def forecast_report( + result: PredictionResult, + output_path: str | Path, + *, + dataset_name: str | None = None, + top_k: int = 5, + artifacts_dir: str | Path | None = None, +) -> Path: + r"""Draw why ``result`` is the forecast it is. + + Args: + result: What :meth:`SDMClient.predict ` + answered for a forecast asked with ``'explanation'`` among its + output fields. + output_path: Where to write the PDF. + dataset_name: A name for the run, shown on the first page. + top_k: How many lags to list per horizon. + artifacts_dir: Where to keep the CSVs and images the pages are drawn + from. They are written either way, because the attribution + heatmap is a page drawn from an image on disk; naming a + directory is what keeps them afterwards. + + Raises: + MissingExtraError: If matplotlib is not installed. + StructuredDataError: If the answer carries no explanation. + + The feature axis sets the forecast series' own effect aside rather than + measuring it, and it arrives as a zero. Left in, the page ranks it among + measured channels and has called it the most influential of them, so it + is taken out along with its label: a row that is not a measurement does + not belong in a matrix of measurements. + + The lags are ranked from the scores rather than from the attributions. + That helper differences a cumulative score into a per-step weight, and + handing it the normalised attribution ranked the lags in very nearly the + opposite order. It returns those per-step weights, which are what the + heatmap's own caption describes; drawn from the cumulative scores + instead, the heatmap read a run of flat history as the most influential + part of the window while the table beside it ranked the newest step + first. + + Each artifact is written where the data behind it was computed, because + the pages name those files and a report that draws the pages and writes + none of them points a reader at nothing. + + >>> result = client.predict( + ... request, model=KumoForecast(), + ... outputs=['prediction', 'explanation'], + ... ) + >>> forecast_report(result, 'forecast.pdf') + """ + carried = next( + (item.explanation for item in result.items if item.explanation), None + ) + if not carried: + raise StructuredDataError( + 'this answer carries no explanation. Ask for one with ' + "outputs=['prediction', 'explanation']; it is not computed " + 'unless it is asked for, because it costs far more than the ' + 'forecast does', + code='INVALID_REQUEST', + ) + pages = _pages() + frame, target, step = _forecast_frame(carried) + explanation = _explanation(carried) + explanation, channels = _without_the_unmeasured( + explanation, _channels(carried), carried + ) + attributions = np.asarray(explanation.lag_horizon_attributions) + marginal, topk_rows = pages._topk_lag_steps_per_horizon( + np.asarray(explanation.lag_horizon_scores), top_k=top_k + ) + per_step = attributions if marginal is None else np.asarray(marginal) + smoothness = _smoothness(carried) + stability, stability_channels = _stability(carried) + gradients = (carried.get('explanation') or {}).get('integrated_gradients') + with _artifacts(artifacts_dir) as out_dir: + _saved_as_json(out_dir, carried) + heatmap = pages._save_lag_horizon_artifacts( + out_dir, + per_step, + np.asarray(explanation.lag_horizon_scores), + ) + horizon = attributions.shape[1] + context = _context_len(carried, horizon) + if explanation.flow_magnitudes is not None and context: + pages._save_semantic_flow_csv( + out_dir, + np.asarray(explanation.flow_magnitudes), + context_len=context, + forecast_horizon=horizon, + ) + if explanation.channel_horizon_attributions is not None: + pages._save_channel_axis_artifacts( + out_dir, + np.asarray(explanation.channel_horizon_attributions), + channel_labels=channels, + ) + if gradients is not None: + pages._save_integrated_gradients_artifacts(out_dir, gradients) + if stability is not None: + pages._save_feature_axis_embedding_stability_csv( + out_dir, stability, stability_channels + ) + drawn = pages._build_pdf_report( + Path(output_path), + dataset_name=dataset_name, + forecast_df=frame, + explanation=explanation, + target_column=target, + timestamp_column=step, + heatmap_path=heatmap, + topk_rows=topk_rows, + top_k=top_k, + context_len=_context_len(carried, attributions.shape[1]), + forecast_horizon=attributions.shape[1], + channel_labels=channels, + trajectory_report=smoothness, + feature_axis_embedding_stability_report=stability, + feature_axis_stability_channel_labels=stability_channels, + integrated_gradients_report=gradients, + ) + if drawn is None: # pragma: no cover - matplotlib is present by here + raise MissingExtraError('report', 'matplotlib') + return drawn + + +def _pages() -> Any: + try: + from sdm_client.explain._attribution import pages + except ImportError as error: # pragma: no cover - the extra is absent + raise MissingExtraError('report', 'matplotlib') from error + return pages + + +def _explanation(carried: dict[str, Any]) -> Any: + r"""The explanation as the drawing expects it, read back from the data. + + Only the arrays the pages read are restored. A field the explanation did + not carry stays absent, and the page that would have drawn it is not + drawn, which is what "this was not computed" looks like on paper. + + The channel attribution is serialised under ``feature_axis`` rather than + beside the lag arrays. Read flat it was found nowhere, and the page that + draws it was skipped although it had been computed, which costs minutes. + """ + from sdm_client.explain._attribution.interpretability import ( + ForecastExplanation, + ) + + block = carried.get('explanation') or {} + feature_axis = block.get('feature_axis') or {} + diagnostics = block.get('diagnostics') or {} + + def array(source: dict[str, Any], name: str) -> Any: + value = source.get(name) + return None if value is None else np.asarray(value, dtype=float) + + def scalar(name: str) -> float | None: + value = diagnostics.get(name) + return None if value is None else float(value) + + return ForecastExplanation( + baseline_forecast=array(block, 'baseline_forecast'), + lag_horizon_scores=array(block, 'lag_horizon_scores'), + lag_horizon_attributions=array(block, 'lag_horizon_attributions'), + flow_magnitudes=array(block, 'flow_magnitudes'), + latent_trajectory=array(block, 'latent_trajectory'), + channel_horizon_attributions=array( + feature_axis, 'channel_horizon_attributions' + ), + per_channel_flow=array(feature_axis, 'per_channel_flow'), + channel_flow_method=feature_axis.get('method'), + flow_ratio_forecast_vs_history=scalar('flow_ratio_forecast_vs_history'), + flow_variance_ratio_forecast_vs_history=scalar( + 'flow_variance_ratio_forecast_vs_history' + ), + curvature_ratio_forecast_vs_history=scalar( + 'curvature_ratio_forecast_vs_history' + ), + latent_diag_mahalanobis_ratio_forecast_vs_history=scalar( + 'latent_diag_mahalanobis_ratio_forecast_vs_history' + ), + ) + + +def _smoothness(carried: dict[str, Any]) -> Any: + r"""How smoothly the latent state moved, read back from the data.""" + from sdm_client.explain._attribution.interpretability import ( + TrajectoryStabilityReport, + ) + + block = (carried.get('explanation') or {}).get('trajectory_stability') + if not block: + return None + rates = ( + 'zero_crossing_rate_mean', + 'zero_crossing_rate_p95', + 'direction_flip_rate_mean', + 'direction_flip_rate_p95', + 'relative_jitter_mean', + 'relative_jitter_p95', + 'occupancy_positive_mean', + 'occupancy_negative_mean', + ) + if any(block.get(name) is None for name in rates): + return None + read = {name: float(block[name]) for name in rates} + return TrajectoryStabilityReport( + zero_crossing_rate_mean=read['zero_crossing_rate_mean'], + zero_crossing_rate_p95=read['zero_crossing_rate_p95'], + direction_flip_rate_mean=read['direction_flip_rate_mean'], + direction_flip_rate_p95=read['direction_flip_rate_p95'], + relative_jitter_mean=read['relative_jitter_mean'], + relative_jitter_p95=read['relative_jitter_p95'], + occupancy_positive_mean=read['occupancy_positive_mean'], + occupancy_negative_mean=read['occupancy_negative_mean'], + n_time_steps=int(block.get('n_time_steps') or 0), + n_dimensions=int(block.get('n_dimensions') or 0), + ) + + +def _stability(carried: dict[str, Any]) -> tuple[Any, list[str] | None]: + r"""How much the embedding moved when a channel was nudged, and the + channels it is about. + + The labels it carries are its own and are handed back beside it. There + are as many of them as there are channels, and that count includes the + series being forecast, which the channel attribution beside it sets + aside. Drawn under the explanation's labels instead, the two lists were + different lengths, and the page fell back to numbering the channels. + """ + from sdm_client.explain._attribution.channel_stability import ( + PerChannelEmbeddingStabilityReport, + ) + + feature_axis = (carried.get('explanation') or {}).get('feature_axis') or {} + block = feature_axis.get('embedding_stability') + if not block: + return None, None + labels = [str(name) for name in block.get('channel_labels') or []] + ratios = { + name: np.asarray(block.get(name), dtype=float) + for name in ( + 'lip_ratio_mean', + 'lip_ratio_max', + 'lip_ratio_p50', + 'lip_ratio_p95', + ) + } + reference = block.get('step_delta_norm_mean') + return PerChannelEmbeddingStabilityReport( + **ratios, + n_trials_per_channel=np.asarray( + block.get('n_trials_per_channel'), dtype='int64' + ), + n_unique_windows=int(block.get('n_unique_windows') or 0), + step_delta_norm_mean=float('nan') + if reference is None + else float(reference), + n_channels=len(labels), + ), labels + + +def _forecast_frame(carried: dict[str, Any]) -> tuple[Any, str, str]: + import pandas as pd + + rows = carried.get('forecast') or [] + frame = pd.DataFrame(rows) + target = str((carried.get('metadata') or {}).get('target_column') or '') + step = 'forecast_step' + if f'{target}_forecast' not in frame.columns: + raise StructuredDataError( + f'this explanation names {target!r} as the series forecast and ' + f'carries {sorted(frame.columns)}, which does not include it', + code='INVALID_RESPONSE', + ) + return frame, target, step + + +def _channels(carried: dict[str, Any]) -> list[str] | None: + labels = (carried.get('metadata') or {}).get('channel_labels') + return None if labels is None else [str(name) for name in labels] + + +def _context_len(carried: dict[str, Any], horizon: int) -> int | None: + r"""How many of the trajectory's steps are history. + + The trajectory runs the context and then the horizon, so its length is + both put together. Reading it as the context alone told the page every + transition was history and none was forecast. + """ + block = (carried.get('explanation') or {}).get('diagnostics') or {} + shape = block.get('latent_trajectory_shape') + if not shape: + return None + steps = int(shape[0]) - horizon + return steps if steps > 0 else None + + +@contextmanager +def _artifacts(named: str | Path | None) -> Iterator[Path]: + r"""Where the images and CSVs the pages read are written. + + The attribution heatmap is a page drawn from a file, so there is always + somewhere for it to be. A caller who named a directory keeps what was + written there; one who did not gets a temporary one that goes away. + """ + if named is not None: + out_dir = Path(named) + out_dir.mkdir(parents=True, exist_ok=True) + yield out_dir + return + with tempfile.TemporaryDirectory(prefix='sdm-forecast-') as temporary: + yield Path(temporary) + + +def _saved_as_json(out_dir: Path, carried: dict[str, Any]) -> Path: + r"""The explanation these pages were drawn from, written out beside them. + + Three of the pages send the reader to ``explanation.json`` for the + diagnostics block and for the values they only summarise, and nothing + wrote one, so the reader was sent to a file that was never there. + + What is written is the answer's own explanation: the pages read nothing + else, so anything derived here could disagree with them. The only thing + changed on the way out is that a value no JSON reader accepts is + written as null, which is what the explanation already does to the + arrays it carries and had not done to the summaries nested inside them. + Writing one as it stood raised, and this is written before a page is + drawn, so one such value cost the whole report. + """ + out_path = out_dir / 'explanation.json' + with out_path.open('w', encoding='utf-8') as handle: + json.dump(_readable(carried), handle, indent=2, allow_nan=False) + return out_path + + +def _readable(value: Any) -> Any: + r"""``value`` with everything JSON has no spelling for written as null. + + A whole number is handed back as it is rather than read as a float: JSON + spells one of any size, and one too large to be a float raised here and + cost the report the float was never needed for. + """ + if isinstance(value, dict): + return {name: _readable(held) for name, held in value.items()} + if isinstance(value, (list, tuple)): + return [_readable(held) for held in value] + if isinstance(value, (bool, int)) or not isinstance(value, numbers.Real): + return value + return None if not math.isfinite(float(value)) else value + + +def _without_the_unmeasured( + explanation: Any, channels: list[str] | None, carried: dict[str, Any] +) -> tuple[Any, list[str] | None]: + r"""``explanation`` with any channel it did not measure removed.""" + from dataclasses import replace + + excluded = (carried.get('metadata') or {}).get('feature_axis_excludes') + attributions = explanation.channel_horizon_attributions + if excluded is None or attributions is None or not channels: + return explanation, channels + if excluded not in channels: + return explanation, channels + keep = [name != excluded for name in channels] + return ( + replace( + explanation, + channel_horizon_attributions=np.asarray(attributions)[keep], + per_channel_flow=( + None + if explanation.per_channel_flow is None + else np.asarray(explanation.per_channel_flow)[keep] + ), + ), + [name for name in channels if name != excluded], + ) diff --git a/packages/structured-data-models-client/src/sdm_client/result.py b/packages/structured-data-models-client/src/sdm_client/result.py index 14d0cebe3..fb4a67afa 100644 --- a/packages/structured-data-models-client/src/sdm_client/result.py +++ b/packages/structured-data-models-client/src/sdm_client/result.py @@ -158,7 +158,9 @@ def _carries(self, name: str) -> bool: was refused before the request was sent. """ if name == 'explanation': - return bool(self._explanations.gradients) + return bool(self._explanations.gradients) or any( + getattr(item, 'explanation', None) for item in self.items + ) if name not in _ITEM_FIELDS: return True return any( diff --git a/packages/structured-data-models-client/tests/test_a_forecast_says_what_it_rested_on.py b/packages/structured-data-models-client/tests/test_a_forecast_says_what_it_rested_on.py new file mode 100644 index 000000000..82a3163b5 --- /dev/null +++ b/packages/structured-data-models-client/tests/test_a_forecast_says_what_it_rested_on.py @@ -0,0 +1,925 @@ +# SPDX-FileCopyrightText: Copyright (c) 2026, NVIDIA CORPORATION & AFFILIATES. +# All rights reserved. +# SPDX-License-Identifier: Apache-2.0 + +"""Why a forecast is the forecast it is, and the report that draws it. + +An explanation walks a window per step of the model's context, so it costs +tens of seconds where a forecast costs a fraction of one. It is computed once +here and read by every test that needs one. +""" + +from __future__ import annotations + +import warnings + +import numpy as np +import pandas as pd +import pytest +from sdm_api.generated.tfm_api import PredictionItem + +from sdm_client import ( + KumoForecast, + Request, + SDMClient, + SDMWarning, + StructuredDataError, +) + +pytest.importorskip('matplotlib', reason='needs the report extra') +pytest.importorskip('torch', reason='the attribution runs on torch') + +from sdm_client.reporting import forecast_report # noqa: E402 + +pytestmark = pytest.mark.filterwarnings('ignore') + + +def history(rows: int = 600) -> pd.DataFrame: + step = np.arange(rows, dtype=float) + return pd.DataFrame({'flow': np.sin(step / 9), 'temp': np.cos(step / 7)}) + + +@pytest.fixture(scope='module') +def answered(forecast): + """An explained forecast, and what the client warned of answering it.""" + with warnings.catch_warnings(record=True) as caught: + warnings.simplefilter('always') + with SDMClient.in_process(forecast) as client: + result = client.predict( + Request.forecast(history(), target='flow', horizon=4), + model=KumoForecast(), + outputs=['prediction', 'explanation'], + ) + return result, [ + str(warning.message) + for warning in caught + if issubclass(warning.category, SDMWarning) + or 'explanation' in str(warning.message) + ] + + +@pytest.fixture(scope='module') +def explained(answered): + return answered[0] + + +def carried_by(result): + """The explanation an answer carries, on the step it came back on.""" + return next( + (item.explanation for item in result.items if item.explanation), None + ) + + +class Carrying: + """An answer carrying an explanation, for drawing one that was edited. + + A result's explanation is what it came back with and cannot be assigned + over, and a page is drawn or not drawn by whether its block is there. + """ + + def __init__(self, explanation): + self.items = ( + PredictionItem( + row_index=0, forecast_step=1, explanation=explanation + ), + ) + + +def without(result, *names, under=None): + """What `result` carries, less the block(s) `names` asks for.""" + carried = dict(carried_by(result)) + block = dict(carried['explanation']) + if under is None: + for name in names: + block.pop(name, None) + else: + block[under] = { + key: value + for key, value in block[under].items() + if key not in names + } + carried['explanation'] = block + return Carrying(carried) + + +def pages(path) -> int: + raw = path.read_bytes() + return raw.count(b'/Type /Page') - raw.count(b'/Type /Pages') + + +def test_an_explanation_comes_back_when_it_is_asked_for(explained): + """It reads the model's gradients and its latent trajectory, so it is + produced where the model runs and nowhere else.""" + carried = carried_by(explained) + + assert isinstance(carried, dict) + assert set(carried) >= {'forecast', 'explanation', 'metadata'} + + +def test_an_explained_forecast_is_answered_as_it_was_asked(answered): + """The explanation rides on the forecast's first step. The answer is + not said to be missing it, is not built through a deprecated argument, + and carries no column analysis, which reads labelled rows and a + history is not that.""" + result, warned = answered + + assert warned == [] + assert result.explanations.columns is None + + +def test_the_report_reads_no_deprecated_part_of_the_answer(explained, tmp_path): + with warnings.catch_warnings(): + warnings.filterwarnings( + 'error', + message=r'result\.explanation is deprecated', + category=DeprecationWarning, + ) + forecast_report(explained, tmp_path / 'f.pdf') + + +def test_the_attribution_covers_every_lag_and_every_step(explained): + block = carried_by(explained)['explanation'] + attributions = np.asarray(block['lag_horizon_attributions']) + + assert attributions.shape == (block['shapes']['K_lags'], 4) + assert np.isfinite(attributions).all() + + +def test_an_explanation_is_data_rather_than_an_object(explained): + """It travels as the contract's `explanation` field, so it has to be + what that field carries.""" + import json + + assert json.loads(json.dumps(carried_by(explained))) + + +def test_a_forecast_asked_without_one_does_not_pay_for_it(forecast): + """It costs far more than the forecast, so it is not computed unless it + was asked for.""" + with SDMClient.in_process(forecast) as client: + result = client.predict( + Request.forecast(history(), target='flow', horizon=4), + model=KumoForecast(), + outputs=['prediction'], + ) + + assert carried_by(result) is None + + +def test_a_flat_series_has_almost_nowhere_to_move(forecast): + """The trajectory builder pads its windows and says which steps are + padding. Reading the padding as observed zeros made a constant series + look like it moved.""" + flat = pd.DataFrame({'flow': np.full(600, 10.0)}) + with SDMClient.in_process(forecast) as client: + result = client.predict( + Request.forecast(flat, target='flow', horizon=4), + model=KumoForecast(), + outputs=['prediction', 'explanation'], + ) + + flow = np.asarray(carried_by(result)['explanation']['flow_magnitudes']) + assert float(flow.sum()) < 0.5 + + +def test_a_forecast_retrieval_had_a_hand_in_is_not_explained(forecast): + """The attribution describes the model's own forward pass. Where + retrieval contributes, explaining that pass describes a number the + caller was never given.""" + history_long = history(600) + with SDMClient.in_process(forecast) as client: + with pytest.raises(StructuredDataError) as caught: + client.predict( + Request.forecast( + history_long, + target='flow', + horizon=4, + inference={'alpha': 0.0}, + ), + model=KumoForecast(), + outputs=['prediction', 'explanation'], + ) + assert 'alpha' in str(caught.value) + + +def test_the_attribution_reads_the_model_s_own_scale(forecast): + """The model standardises before it reads anything, so the attribution + works there too. Handing it raw readings attributed a model being fed + numbers it never sees.""" + from sdm_client.explain._explain import _standardised + + raw = np.array([[1.0, 2.0, 3.0]]) + standardised = _standardised(forecast, raw) + + assert not np.allclose(standardised, raw) + assert np.allclose( + standardised, (raw + 5.671202659606934) / 8.693312644958496, atol=1e-4 + ) + + +def test_what_is_drawn_is_in_the_readings_own_scale(explained): + """The attribution works standardised; a reader does not.""" + baseline = np.asarray( + carried_by(explained)['explanation']['baseline_forecast'] + ) + + assert np.abs(baseline).max() < 5.0 + + +def test_the_feature_axis_needs_a_horizon_one_pass_reaches(forecast): + """It reads a single forward pass, which covers the model's own horizon + and no more.""" + with SDMClient.in_process(forecast) as client: + with pytest.raises(StructuredDataError) as caught: + client.predict( + Request.forecast( + history(600), + target='flow', + horizon=80, + inference={'feature_axis': True}, + ), + model=KumoForecast(), + outputs=['prediction', 'explanation'], + ) + assert 'feature-axis' in str(caught.value) + + +def test_the_diagnostics_survive_being_written_and_read(explained): + """They are computed, serialised, and read back for the page that prints + them, which printed n/a for every one of them.""" + from sdm_client.reporting.forecast import _explanation + + restored = _explanation(carried_by(explained)) + + assert restored.flow_ratio_forecast_vs_history is not None + assert restored.curvature_ratio_forecast_vs_history is not None + + +def test_the_top_lags_are_ranked_from_the_scores(explained, tmp_path): + """That helper differences a cumulative score into a per-step weight, so + handing it the normalised attribution ranks the lags near-backwards. + + Asserted on what the report passes. Comparing the helper against itself + said nothing about the call that draws the page, and passed while the + report still handed over the wrong array. + """ + from sdm_client.explain._attribution import pages + from sdm_client.reporting import forecast as module + + seen = [] + original = pages._topk_lag_steps_per_horizon + + def watched(scores, **kwargs): + seen.append(np.asarray(scores)) + return original(scores, **kwargs) + + pages._topk_lag_steps_per_horizon = watched + try: + module.forecast_report(explained, tmp_path / 'f.pdf') + finally: + pages._topk_lag_steps_per_horizon = original + + block = carried_by(explained)['explanation'] + assert len(seen) == 1 + assert np.allclose(seen[0], np.asarray(block['lag_horizon_scores'])) + + +def test_the_history_the_page_is_told_about_excludes_the_forecast(explained): + """The trajectory runs the context and then the horizon. Reading its + length as the context said every transition was history.""" + from sdm_client.reporting.forecast import _context_len + + block = carried_by(explained)['explanation'] + steps = block['diagnostics']['latent_trajectory_shape'][0] + + assert _context_len(carried_by(explained), 4) == steps - 4 + + +def test_a_gap_outside_the_window_is_not_a_gap_in_it(forecast): + """The attribution reads the last 512 steps, so a reading missing before + them is not missing from what it reads. Checking the whole history + refused a question identical to one it answers.""" + frame = history(600) + frame.loc[0, 'temp'] = np.nan + + with SDMClient.in_process(forecast) as client: + result = client.predict( + Request.forecast( + frame, + target='flow', + horizon=4, + inference={'feature_axis': True}, + ), + model=KumoForecast(), + outputs=['prediction', 'explanation'], + ) + + assert carried_by(result) is not None + + +def test_the_files_the_pages_name_are_written(explained, tmp_path): + """A page that names a file beside a report a reader cannot find points + them at nothing.""" + artifacts = tmp_path / 'artifacts' + forecast_report(explained, tmp_path / 'f.pdf', artifacts_dir=artifacts) + written = {path.name for path in artifacts.iterdir()} + + assert 'lag_horizon_heatmap.png' in written + assert 'semantic_flow.csv' in written + assert 'explanation.json' in written + + +def test_a_value_json_cannot_spell_does_not_cost_the_report( + explained, tmp_path +): + """The explanation is written out before any page is drawn, so one + value no JSON reader accepts took the whole report with it.""" + import json + + artifacts = tmp_path / 'artifacts' + carried = dict(carried_by(explained)) + carried['diagnostics'] = {'top': [{'share': float('nan'), 'n': 2**1024}]} + + forecast_report( + Carrying(carried), tmp_path / 'f.pdf', artifacts_dir=artifacts + ) + written = json.loads((artifacts / 'explanation.json').read_text()) + + assert written['diagnostics']['top'][0]['share'] is None + assert written['diagnostics']['top'][0]['n'] == 2**1024 + + +def test_the_series_own_channel_is_not_ranked_among_the_measured( + forecast, tmp_path +): + """Its effect is set aside rather than measured, so it arrives as a zero. + Left among real numbers the page ranked it, and with small effects + elsewhere it called the excluded channel the most influential of all.""" + from sdm_client.reporting.forecast import ( + _channels, + _explanation, + _without_the_unmeasured, + ) + + with SDMClient.in_process(forecast) as client: + result = client.predict( + Request.forecast( + history(600), + target='flow', + horizon=4, + inference={'feature_axis': True}, + ), + model=KumoForecast(), + outputs=['prediction', 'explanation'], + ) + + carried = carried_by(result) + assert carried['metadata']['feature_axis_excludes'] == 'flow' + _, channels = _without_the_unmeasured( + _explanation(carried), _channels(carried), carried + ) + assert channels == ['temp'] + + +def test_a_forecaster_that_cannot_use_a_covariate_does_not_attribute_one( + sdm, +): + """Without channel mixing a column measured alongside the series reaches + the forecast not at all, while the embedding still pools it, so an + attribution moves for something that changes nothing.""" + import torch + + torch.manual_seed(0) + flat = sdm.models.KumoForecast( + cross_channel=False, pretrained=False, device='cpu' + ) + with SDMClient.in_process(flat) as client: + with pytest.raises(StructuredDataError) as caught: + client.predict( + Request.forecast(history(600), target='flow', horizon=2), + model=KumoForecast(), + outputs=['prediction', 'explanation'], + ) + assert 'mix channels' in str(caught.value) + + +def test_the_heatmap_shows_what_its_caption_says(explained, tmp_path): + """Its rows are single past steps, and it was handed the cumulative + scores those are differenced out of, so a flat run read as the most + influential part of the window while the table ranked the newest first. + """ + from sdm_client.explain._attribution import pages + + seen = [] + original = pages._save_lag_horizon_artifacts + + def watched(out_dir, attributions, scores=None, **kwargs): + seen.append(np.asarray(attributions)) + return original(out_dir, attributions, scores, **kwargs) + + pages._save_lag_horizon_artifacts = watched + try: + forecast_report(explained, tmp_path / 'f.pdf') + finally: + pages._save_lag_horizon_artifacts = original + + block = carried_by(explained)['explanation'] + marginal, _ = pages._topk_lag_steps_per_horizon( + np.asarray(block['lag_horizon_scores']), top_k=5 + ) + assert len(seen) == 1 + assert np.allclose(seen[0], np.asarray(marginal)) + + +def test_the_channel_effects_are_measured_not_differentiated(forecast): + """This forecaster normalises each window by statistics it takes without + gradients, so a gradient through it holds that normalisation still and + reports a sensitivity hundreds of times what a perturbation produces. + The forward pass is not differentiable, which is what selects the + difference the attribution would otherwise skip.""" + import torch + + from sdm_client.explain._model import Forecaster + + shim = Forecaster(forecast) + window = torch.zeros(1, 2, shim.context_size, requires_grad=True) + + assert not shim(x_enc=window).forecast.requires_grad + + +def test_the_attribution_heatmap_is_drawn(explained, tmp_path): + """It is a page drawn from an image on disk, and hardcoding no image + dropped it from every report although the matrix was right there.""" + artifacts = tmp_path / 'artifacts' + written = forecast_report( + explained, tmp_path / 'f.pdf', artifacts_dir=artifacts + ) + + assert (artifacts / 'lag_horizon_heatmap.png').exists() + assert pages(written) >= 4 + + +def test_the_artifacts_are_kept_only_where_a_place_was_named( + explained, tmp_path +): + """They are written either way, because a page reads one of them.""" + before = set(tmp_path.iterdir()) + forecast_report(explained, tmp_path / 'f.pdf') + + assert set(tmp_path.iterdir()) - before == {tmp_path / 'f.pdf'} + + +def test_a_channel_with_a_gap_is_not_called_uninfluential(forecast): + """The feature axis replaces a channel with its own average, which a gap + makes undefined; the channel then reads as having no influence at all.""" + frame = history(600) + frame.loc[599, 'temp'] = np.nan + + with SDMClient.in_process(forecast) as client: + with pytest.raises(StructuredDataError) as caught: + client.predict( + Request.forecast( + frame, + target='flow', + horizon=4, + inference={'feature_axis': True}, + ), + model=KumoForecast(), + outputs=['prediction', 'explanation'], + ) + assert 'gap' in str(caught.value) + + +def test_a_gradient_over_a_gap_is_not_an_attribution(forecast): + """Integrated gradients measure against a baseline of noise over the + window, and one gap makes the whole baseline NaN: every attribution + taken against it reads as no influence at all.""" + frame = history(600) + frame.loc[599, 'temp'] = np.nan + + with SDMClient.in_process(forecast) as client: + with pytest.raises(StructuredDataError) as caught: + client.predict( + Request.forecast( + frame, + target='flow', + horizon=4, + inference={'integrated_gradients': True}, + ), + model=KumoForecast(), + outputs=['prediction', 'explanation'], + ) + assert 'integrated gradients' in str(caught.value) + + +def test_a_report_is_drawn_from_an_explanation(explained, tmp_path): + written = forecast_report(explained, tmp_path / 'forecast.pdf') + + assert written.exists() + assert pages(written) >= 3 + + +def test_the_report_names_the_series_and_the_lag_window(explained, tmp_path): + """Read off the data the page is drawn from. The text in this PDF is + compressed, so sniffing its bytes for a word tests the encoder rather + than the report.""" + metadata = carried_by(explained)['metadata'] + + assert metadata['target_column'] == 'flow' + assert metadata['channel_labels'] == ['flow', 'temp'] + assert forecast_report( + explained, tmp_path / 'forecast.pdf', dataset_name='flow' + ).exists() + + +def test_a_forecast_with_no_explanation_says_how_to_ask_for_one( + forecast, tmp_path +): + with SDMClient.in_process(forecast) as client: + result = client.predict( + Request.forecast(history(), target='flow', horizon=4), + model=KumoForecast(), + outputs=['prediction'], + ) + + with pytest.raises(StructuredDataError) as caught: + forecast_report(result, tmp_path / 'forecast.pdf') + assert 'explanation' in str(caught.value) + + +def test_a_history_shorter_than_the_model_reads_cannot_be_attributed( + forecast, +): + """The attribution is about the window the model read, and a history + shorter than that window is not one it read.""" + with SDMClient.in_process(forecast) as client: + with pytest.raises(StructuredDataError) as caught: + client.predict( + Request.forecast(history(100), target='flow', horizon=2), + model=KumoForecast(), + outputs=['prediction', 'explanation'], + ) + assert '512' in str(caught.value) + + +def test_only_this_model_is_asked_to_explain_a_forecast(anomaly): + """`explanation` is a field the forecaster produces, not every model.""" + from sdm_client import KumoAnomaly + + frame = pd.DataFrame({'flow': np.sin(np.arange(60) / 9)}) + with SDMClient.in_process(anomaly) as client: + with pytest.raises(StructuredDataError) as caught: + client.predict( + Request.anomaly(frame, inference={'num_samples': 1}), + model=KumoAnomaly(), + outputs=['prediction', 'explanation'], + ) + assert 'explanation' in str(caught.value) + + +def test_the_smoothness_of_the_latent_state_is_measured(explained): + """Reported as null for every run before it was computed, so its page + was never drawn.""" + block = carried_by(explained)['explanation']['trajectory_stability'] + + assert block is not None + assert block['n_time_steps'] == 512 + assert 0.0 <= block['zero_crossing_rate_mean'] <= 1.0 + + +def test_the_smoothness_is_the_history_walked_once(explained, forecast): + """It is read off the trajectory the attribution already walked rather + than walked again, so it has to be what a second walk would say.""" + import torch + + from sdm_client.explain._attribution.interpretability import ( + compute_trajectory_stability, + ) + from sdm_client.explain._explain import _standardised + from sdm_client.explain._model import Forecaster + + carried = carried_by(explained) + window = _standardised( + forecast, history().to_numpy().T[:, -512:].astype('float32') + ) + walked = compute_trajectory_stability( + Forecaster(forecast), + np.ascontiguousarray(window, dtype='float32'), + seq_len=512, + input_mask_t=np.ones(512, dtype='float32'), + device=torch.device('cpu'), + ) + + read = carried['explanation']['trajectory_stability'] + assert read['relative_jitter_mean'] == pytest.approx( + walked.relative_jitter_mean, rel=1e-5 + ) + assert read['zero_crossing_rate_mean'] == pytest.approx( + walked.zero_crossing_rate_mean, rel=1e-5 + ) + + +def test_the_smoothness_page_is_drawn(explained, tmp_path): + before = pages(forecast_report(explained, tmp_path / 'f.pdf')) + stripped = without(explained, 'trajectory_stability') + + after = pages(forecast_report(stripped, tmp_path / 'g.pdf')) + + assert before == after + 1 + + +@pytest.fixture(scope='module') +def over_channels(forecast): + with SDMClient.in_process(forecast) as client: + return client.predict( + Request.forecast( + history(), + target='flow', + horizon=4, + inference={'feature_axis': True}, + ), + model=KumoForecast(), + outputs=['prediction', 'explanation'], + ) + + +def test_the_embedding_is_measured_for_every_channel(over_channels): + """Asked for alongside the feature axis, because it answers the question + the feature axis raises: an influence attributed through a derivative + that is not there is not an influence.""" + block = carried_by(over_channels)['explanation']['feature_axis'] + measured = block['embedding_stability'] + + assert measured['channel_labels'] == ['flow', 'temp'] + assert all(count > 0 for count in measured['n_trials_per_channel']) + assert all(np.isfinite(measured['lip_ratio_mean'])) + + +def test_the_embedding_is_not_measured_without_the_feature_axis(explained): + """It costs a window per channel per trial, which is the feature axis's + own order of cost and not the lag attribution's.""" + block = carried_by(explained)['explanation'].get('feature_axis') or {} + + assert 'embedding_stability' not in block + + +def test_the_embedding_stability_page_is_drawn(over_channels, tmp_path): + before = pages(forecast_report(over_channels, tmp_path / 'f.pdf')) + stripped = without( + over_channels, 'embedding_stability', under='feature_axis' + ) + + after = pages(forecast_report(stripped, tmp_path / 'g.pdf')) + + assert before == after + 1 + + +def test_the_stability_csv_names_the_channels_it_measured( + over_channels, tmp_path +): + """The channels it measured include the series being forecast, which the + channel attribution beside it sets aside. Drawn under the attribution's + labels the two lists were different lengths, and the page numbered the + channels instead of naming them.""" + import pandas as pd + + artifacts = tmp_path / 'artifacts' + forecast_report(over_channels, tmp_path / 'f.pdf', artifacts_dir=artifacts) + written = pd.read_csv(artifacts / 'feature_axis_embedding_stability.csv') + + assert written['feature'].tolist() == ['flow', 'temp'] + + +@pytest.mark.parametrize('reference', [0.0, 1.5, None]) +def test_a_reference_scale_of_zero_is_a_reference_scale(reference): + """A trajectory that does not move has a mean step of zero, which read + as a measurement that was never taken.""" + from sdm_client.reporting.forecast import _stability + + report, labels = _stability( + { + 'explanation': { + 'feature_axis': { + 'embedding_stability': { + 'channel_labels': ['flow', 'temp'], + 'lip_ratio_mean': [1.0, 2.0], + 'lip_ratio_max': [1.0, 2.0], + 'lip_ratio_p50': [1.0, 2.0], + 'lip_ratio_p95': [1.0, 2.0], + 'n_trials_per_channel': [3, 3], + 'n_unique_windows': 4, + 'step_delta_norm_mean': reference, + } + } + } + } + ) + + assert labels == ['flow', 'temp'] + read = report.step_delta_norm_mean + assert np.isnan(read) if reference is None else read == reference + + +def test_too_many_channels_leave_the_page_out_rather_than_the_rest(forecast): + """The probes are a window per channel per trial and a copy of each, so + their memory grows with the square of the channels. Past the cap the + page is left out and the feature axis it was asked beside is not.""" + import warnings + + from sdm_client.core.warnings import SDMWarning + from sdm_client.explain import _explain + + frame = history() + with SDMClient.in_process(forecast) as client: + request = Request.forecast( + frame, + target='flow', + horizon=4, + inference={'feature_axis': True}, + ) + with warnings.catch_warnings(record=True) as raised: + warnings.simplefilter('always') + kept = _explain._STABILITY_BYTES + _explain._STABILITY_BYTES = 1 + try: + result = client.predict( + request, + model=KumoForecast(), + outputs=['prediction', 'explanation'], + ) + finally: + _explain._STABILITY_BYTES = kept + + block = carried_by(result)['explanation']['feature_axis'] + assert 'embedding_stability' not in block + assert block['channel_horizon_attributions'] is not None + assert any( + issubclass(one.category, SDMWarning) + and 'MiB of probes' in str(one.message) + for one in raised + ) + + +@pytest.fixture(scope='module') +def by_gradient(forecast): + with SDMClient.in_process(forecast) as client: + return client.predict( + Request.forecast( + history(), + target='flow', + horizon=4, + inference={'integrated_gradients': True}, + ), + model=KumoForecast(), + outputs=['prediction', 'explanation'], + ) + + +def test_the_gradient_attribution_covers_the_window_it_read(by_gradient): + block = carried_by(by_gradient)['explanation']['integrated_gradients'] + + assert np.asarray(block['attribution']).shape == (2, 512) + assert block['channel_labels'] == ['flow', 'temp'] + assert sum(block['channel_abs_share']) == pytest.approx(1.0, rel=1e-5) + + +@pytest.mark.parametrize( + ('differentiable', 'reads'), + [(False, False), (True, True)], +) +def test_the_gradient_is_taken_through_the_normalisation( + sdm, differentiable, reads +): + """Each window is divided by statistics taken over the window itself, + and those are taken without gradients. A gradient through the model as it + stands therefore describes a pass with each window's own mean and spread + held still, which is not the pass that answered. + + Measured against an invariant rather than against the model, so it holds + whatever the weights are: a normalised window has the same sum of squares + whatever it was made from, so moving the window cannot change it and the + true derivative is exactly zero. + """ + import torch + from sdm.nn import RevIN + + from sdm_client.explain._model import _statistics + + torch.manual_seed(0) + revin = RevIN(eps=1e-5) + window = torch.randn(1, 3, 16, dtype=torch.float32) + direction = torch.randn_like(window) + direction /= direction.norm() + + moved = window.clone().requires_grad_(True) + statistics = _statistics if differentiable else RevIN.stats + mean, scale = statistics(moved, correction=0) + revin(moved, mean, scale).square().sum().backward() + along = float((moved.grad * direction).sum()) + + assert (abs(along) < 1e-4) is reads + + +def test_the_normalisation_is_left_as_it_was_found(forecast): + """It is patched for the length of one attribution. Left patched, every + forecast after it runs through a normaliser this client replaced.""" + from sdm_client.explain._model import Forecaster + + shim = Forecaster(forecast) + with shim.differentiable_normalisation(): + patched = [ + 'stats' in vars(module) + for module in shim.modules() + if hasattr(module, 'eps') and hasattr(module, 'stats') + ] + + assert any(patched) + assert not any( + 'stats' in vars(module) + for module in shim.modules() + if hasattr(module, 'eps') and hasattr(module, 'stats') + ) + + +def test_the_normalisation_survives_being_held_twice(forecast): + """The inner one deleted the outer one's patch on its way out, and the + outer one then raised on a name that was no longer there.""" + from sdm_client.explain._model import Forecaster + + shim = Forecaster(forecast) + revins = [ + module + for module in shim.modules() + if hasattr(module, 'eps') and hasattr(module, 'stats') + ] + with shim.differentiable_normalisation(): + with shim.differentiable_normalisation(): + pass + inner = [vars(module).get('stats') for module in revins] + + assert all(held is not None for held in inner) + assert not any('stats' in vars(module) for module in revins) + + +def test_a_normalisation_of_its_own_is_put_back(forecast): + """A module that carried its own statistics before any of this lost + them outright: the patch was deleted rather than replaced.""" + from sdm_client.explain._model import Forecaster + + shim = Forecaster(forecast) + revin = next( + module + for module in shim.modules() + if hasattr(module, 'eps') and hasattr(module, 'stats') + ) + theirs = revin.stats + revin.stats = theirs + + with shim.differentiable_normalisation(): + pass + + assert vars(revin).get('stats') is theirs + + +def test_the_length_of_the_embedding_is_not_what_is_explained(forecast): + """This forecaster's embedding is a retrieval key, scaled to unit length + before it is returned, so its length is one whatever it was given. + Explaining that explains a constant, and every reading came back zero.""" + import torch + + from sdm_client.explain._explain import _standardised + from sdm_client.explain._model import Forecaster + + shim = Forecaster(forecast) + window = _standardised( + forecast, history().to_numpy().T[:, -512:].astype('float32') + ) + embedded = shim.embed( + x_enc=torch.as_tensor(window, dtype=torch.float32)[None], + input_mask=torch.ones(1, 512), + ).embeddings + + assert float(embedded.norm()) == pytest.approx(1.0, rel=1e-5) + + +def test_a_forecast_asked_without_gradients_does_not_pay_for_them(explained): + """They walk a path of sixty-four windows and take a gradient at each.""" + assert 'integrated_gradients' not in carried_by(explained)['explanation'] + + +def test_the_gradient_page_is_drawn(by_gradient, tmp_path): + before = pages(forecast_report(by_gradient, tmp_path / 'f.pdf')) + stripped = without(by_gradient, 'integrated_gradients') + + after = pages(forecast_report(stripped, tmp_path / 'g.pdf')) + + assert before == after + 1 + + +def test_the_files_the_gradient_page_names_are_written(by_gradient, tmp_path): + artifacts = tmp_path / 'artifacts' + forecast_report(by_gradient, tmp_path / 'f.pdf', artifacts_dir=artifacts) + written = {path.name for path in artifacts.iterdir()} + + assert 'integrated_gradients_attributions.csv' in written + assert 'integrated_gradients_channel_summary.csv' in written diff --git a/packages/structured-data-models-client/tests/test_the_ported_pages_resolve_what_they_name.py b/packages/structured-data-models-client/tests/test_the_ported_pages_resolve_what_they_name.py new file mode 100644 index 000000000..d57b7cbe6 --- /dev/null +++ b/packages/structured-data-models-client/tests/test_the_ported_pages_resolve_what_they_name.py @@ -0,0 +1,94 @@ +# SPDX-FileCopyrightText: Copyright (c) 2026, NVIDIA CORPORATION & AFFILIATES. +# All rights reserved. +# SPDX-License-Identifier: Apache-2.0 + +"""Every name the ported attribution reads is a name it can reach. + +Moving a module into a package rewrites where its imports point, and a name +that was resolved by the layout it came from is resolved by nothing here. The +failure is a `NameError` at the moment the line runs, which for a page drawn +once in a long explanation is a long way from the move that caused it. These +walk every function of the ported modules and check up front. +""" + +from __future__ import annotations + +import ast +import builtins +import importlib +import pkgutil +import symtable +from pathlib import Path + +import pytest + +pytest.importorskip('torch', reason='the ported attribution runs on torch') + +PORTED = 'sdm_client.explain._attribution' +NAMES = sorted( + found.name + for found in pkgutil.iter_modules(importlib.import_module(PORTED).__path__) +) +MODULES = [f'{PORTED}.{name}' for name in NAMES] + + +def read_as_globals(source: str, filename: str) -> set[str]: + """Every name the module's code reads and expects to find around it. + + Asked of Python's own scope analysis rather than worked out from the + tree. Collecting bindings by walking merges every scope into one, and a + parameter named `logger` in one function then resolves a `logger` that + another function reads and nothing defines. + """ + found: set[str] = set() + pending = [symtable.symtable(source, filename, 'exec')] + while pending: + scope = pending.pop() + pending.extend(scope.get_children()) + found.update( + symbol.get_name() + for symbol in scope.get_symbols() + if symbol.is_referenced() and symbol.is_global() + ) + return found + + +@pytest.mark.parametrize('module_name', MODULES) +def test_the_ported_module_resolves_every_name_it_reads(module_name): + module = importlib.import_module(module_name) + source = Path(module.__file__).read_text(encoding='utf-8') + unresolved = { + name + for name in read_as_globals(source, module.__file__) + if not hasattr(module, name) and not hasattr(builtins, name) + } + + assert not unresolved + + +@pytest.mark.parametrize('module_name', MODULES) +def test_the_ported_module_imports_nothing_from_where_it_came_from( + module_name, +): + """An import of a bare top-level module is the shape the move leaves + behind: upstream ran these as scripts beside one another. Both spellings + of it, because `import channel_flow` leaves the same module missing as + `from channel_flow import ...` does.""" + module = importlib.import_module(module_name) + source = ast.parse(Path(module.__file__).read_text(encoding='utf-8')) + sibling = { + named + for node in ast.walk(source) + for named in ( + [node.module] + if isinstance(node, ast.ImportFrom) + and node.level == 0 + and node.module is not None + else [alias.name for alias in node.names] + if isinstance(node, ast.Import) + else [] + ) + if named.split('.')[0] in NAMES + } + + assert not sibling diff --git a/pyproject.toml b/pyproject.toml index 22aaba07f..39eb6f008 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -48,6 +48,12 @@ target-version = "py310" # illustrated. extend-exclude = [ "packages/structured-data-models-pql/src/predictive_query/grammar", + # The forecast attribution, kept as it was written, down + # to putting `from __future__` above its own module docstrings. Excluded + # from mypy for the same reason; the two lists move together. Checked for + # the lints that are not style first: an undefined name here would be a + # line this move dropped, and two were. + "packages/structured-data-models-client/src/sdm_client/explain/_attribution", "packages/structured-data-models-api/src/sdm_api/generated/tfm_api.py", "*.md", ] @@ -86,6 +92,10 @@ exclude = [ # ANTLR's output, regenerated from the grammar rather than edited. Excluded # from ruff for the same reason; the two lists move together. "packages/structured-data-models-pql/src/predictive_query/grammar/", + # The forecast attribution, kept as it was written. An + # attribution is a statement about what a model did, so the arithmetic + # that makes it is not this repository's to retype. + "packages/structured-data-models-client/src/sdm_client/explain/_attribution/", ] # --- Baseline recorded 2026-09-17 ------------------------------------------- diff --git a/tests/test_release_contract.py b/tests/test_release_contract.py index 294f7ad35..4040098ed 100644 --- a/tests/test_release_contract.py +++ b/tests/test_release_contract.py @@ -1240,8 +1240,9 @@ def test_every_advertised_extra_of_the_client_resolves_to_a_real_target( one of the few it does not. databricks-sdk and structured-data-models are imported by the - client's own transports, and matplotlib by the one module that draws - an answer, so the client is the distribution that declares them. + client's own transports, and matplotlib and torch by the modules + that draw an answer, so the client is the distribution that declares + them. """ client = _pyproject('structured-data-models-client')['project'] known = set(_distributions()) @@ -1258,6 +1259,7 @@ def test_every_advertised_extra_of_the_client_resolves_to_a_real_target( 'requests-mock', 'databricks-sdk', 'matplotlib', + 'torch', 'structured-data-models', }, ( f'extra {extra!r} requires {name!r}, which is not one of ' diff --git a/uv.lock b/uv.lock index 78ab2dcf7..f9a38e768 100644 --- a/uv.lock +++ b/uv.lock @@ -895,7 +895,7 @@ name = "cuda-bindings" version = "13.4.4" source = { registry = "https://pypi.org/simple" } dependencies = [ - { name = "cuda-pathfinder", marker = "python_full_version >= '3.11' and sys_platform != 'emscripten' and sys_platform != 'win32'" }, + { name = "cuda-pathfinder", marker = "(python_full_version < '3.11' and sys_platform == 'emscripten') or (python_full_version < '3.11' and sys_platform == 'win32') or (sys_platform != 'emscripten' and sys_platform != 'win32')" }, ] wheels = [ { url = "https://files.pythonhosted.org/packages/9b/1e/d90a8af3d589776c70e92d43d7a0234260709a1d552d105f4dd3bdf48fa3/cuda_bindings-13.4.4-cp310-cp310-manylinux_2_24_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:90f85a00fc89dd4a8f7c4beb0a2f3f788b845c8496fe84adc1217830206db9e0", size = 6512106, upload-time = "2026-10-14T12:35:04.07Z" }, @@ -930,43 +930,43 @@ wheels = [ [package.optional-dependencies] cublas = [ - { name = "nvidia-cublas", marker = "(python_full_version >= '3.11' and platform_machine == 'aarch64' and sys_platform == 'linux') or (python_full_version >= '3.11' and platform_machine == 'x86_64' and sys_platform == 'linux')" }, - { name = "nvidia-cuda-nvrtc", marker = "(python_full_version >= '3.11' and platform_machine == 'aarch64' and sys_platform == 'linux') or (python_full_version >= '3.11' and platform_machine == 'x86_64' and sys_platform == 'linux')" }, + { name = "nvidia-cublas", marker = "(python_full_version < '3.11' and platform_machine == 'AMD64' and sys_platform == 'win32') or (platform_machine == 'aarch64' and sys_platform == 'linux') or (platform_machine == 'x86_64' and sys_platform == 'linux')" }, + { name = "nvidia-cuda-nvrtc", marker = "(python_full_version < '3.11' and platform_machine == 'AMD64' and sys_platform == 'win32') or (platform_machine == 'aarch64' and sys_platform == 'linux') or (platform_machine == 'x86_64' and sys_platform == 'linux')" }, ] cudart = [ - { name = "nvidia-cuda-runtime", marker = "(python_full_version >= '3.11' and platform_machine == 'aarch64' and sys_platform == 'linux') or (python_full_version >= '3.11' and platform_machine == 'x86_64' and sys_platform == 'linux')" }, + { name = "nvidia-cuda-runtime", marker = "(python_full_version < '3.11' and platform_machine == 'AMD64' and sys_platform == 'win32') or (platform_machine == 'aarch64' and sys_platform == 'linux') or (platform_machine == 'x86_64' and sys_platform == 'linux')" }, ] cufft = [ - { name = "nvidia-cufft", marker = "(python_full_version >= '3.11' and platform_machine == 'aarch64' and sys_platform == 'linux') or (python_full_version >= '3.11' and platform_machine == 'x86_64' and sys_platform == 'linux')" }, - { name = "nvidia-nvjitlink", marker = "(python_full_version >= '3.11' and platform_machine == 'aarch64' and sys_platform == 'linux') or (python_full_version >= '3.11' and platform_machine == 'x86_64' and sys_platform == 'linux')" }, + { name = "nvidia-cufft", marker = "(python_full_version < '3.11' and platform_machine == 'AMD64' and sys_platform == 'win32') or (platform_machine == 'aarch64' and sys_platform == 'linux') or (platform_machine == 'x86_64' and sys_platform == 'linux')" }, + { name = "nvidia-nvjitlink", marker = "(python_full_version < '3.11' and platform_machine == 'AMD64' and sys_platform == 'win32') or (platform_machine == 'aarch64' and sys_platform == 'linux') or (platform_machine == 'x86_64' and sys_platform == 'linux')" }, ] cufile = [ - { name = "nvidia-cufile", marker = "(python_full_version >= '3.11' and platform_machine == 'aarch64' and sys_platform == 'linux') or (python_full_version >= '3.11' and platform_machine == 'x86_64' and sys_platform == 'linux')" }, + { name = "nvidia-cufile", marker = "(platform_machine == 'aarch64' and sys_platform == 'linux') or (platform_machine == 'x86_64' and sys_platform == 'linux')" }, ] cupti = [ - { name = "nvidia-cuda-cupti", marker = "(python_full_version >= '3.11' and platform_machine == 'aarch64' and sys_platform == 'linux') or (python_full_version >= '3.11' and platform_machine == 'x86_64' and sys_platform == 'linux')" }, + { name = "nvidia-cuda-cupti", marker = "(python_full_version < '3.11' and platform_machine == 'AMD64' and sys_platform == 'win32') or (platform_machine == 'aarch64' and sys_platform == 'linux') or (platform_machine == 'x86_64' and sys_platform == 'linux')" }, ] curand = [ - { name = "nvidia-curand", marker = "(python_full_version >= '3.11' and platform_machine == 'aarch64' and sys_platform == 'linux') or (python_full_version >= '3.11' and platform_machine == 'x86_64' and sys_platform == 'linux')" }, + { name = "nvidia-curand", marker = "(python_full_version < '3.11' and platform_machine == 'AMD64' and sys_platform == 'win32') or (platform_machine == 'aarch64' and sys_platform == 'linux') or (platform_machine == 'x86_64' and sys_platform == 'linux')" }, ] cusolver = [ - { name = "nvidia-cublas", marker = "(python_full_version >= '3.11' and platform_machine == 'aarch64' and sys_platform == 'linux') or (python_full_version >= '3.11' and platform_machine == 'x86_64' and sys_platform == 'linux')" }, - { name = "nvidia-cusolver", marker = "(python_full_version >= '3.11' and platform_machine == 'aarch64' and sys_platform == 'linux') or (python_full_version >= '3.11' and platform_machine == 'x86_64' and sys_platform == 'linux')" }, - { name = "nvidia-cusparse", marker = "(python_full_version >= '3.11' and platform_machine == 'aarch64' and sys_platform == 'linux') or (python_full_version >= '3.11' and platform_machine == 'x86_64' and sys_platform == 'linux')" }, - { name = "nvidia-nvjitlink", marker = "(python_full_version >= '3.11' and platform_machine == 'aarch64' and sys_platform == 'linux') or (python_full_version >= '3.11' and platform_machine == 'x86_64' and sys_platform == 'linux')" }, + { name = "nvidia-cublas", marker = "(python_full_version < '3.11' and platform_machine == 'AMD64' and sys_platform == 'win32') or (platform_machine == 'aarch64' and sys_platform == 'linux') or (platform_machine == 'x86_64' and sys_platform == 'linux')" }, + { name = "nvidia-cusolver", marker = "(python_full_version < '3.11' and platform_machine == 'AMD64' and sys_platform == 'win32') or (platform_machine == 'aarch64' and sys_platform == 'linux') or (platform_machine == 'x86_64' and sys_platform == 'linux')" }, + { name = "nvidia-cusparse", marker = "(python_full_version < '3.11' and platform_machine == 'AMD64' and sys_platform == 'win32') or (platform_machine == 'aarch64' and sys_platform == 'linux') or (platform_machine == 'x86_64' and sys_platform == 'linux')" }, + { name = "nvidia-nvjitlink", marker = "(python_full_version < '3.11' and platform_machine == 'AMD64' and sys_platform == 'win32') or (platform_machine == 'aarch64' and sys_platform == 'linux') or (platform_machine == 'x86_64' and sys_platform == 'linux')" }, ] cusparse = [ - { name = "nvidia-cusparse", marker = "(python_full_version >= '3.11' and platform_machine == 'aarch64' and sys_platform == 'linux') or (python_full_version >= '3.11' and platform_machine == 'x86_64' and sys_platform == 'linux')" }, - { name = "nvidia-nvjitlink", marker = "(python_full_version >= '3.11' and platform_machine == 'aarch64' and sys_platform == 'linux') or (python_full_version >= '3.11' and platform_machine == 'x86_64' and sys_platform == 'linux')" }, + { name = "nvidia-cusparse", marker = "(python_full_version < '3.11' and platform_machine == 'AMD64' and sys_platform == 'win32') or (platform_machine == 'aarch64' and sys_platform == 'linux') or (platform_machine == 'x86_64' and sys_platform == 'linux')" }, + { name = "nvidia-nvjitlink", marker = "(python_full_version < '3.11' and platform_machine == 'AMD64' and sys_platform == 'win32') or (platform_machine == 'aarch64' and sys_platform == 'linux') or (platform_machine == 'x86_64' and sys_platform == 'linux')" }, ] nvjitlink = [ - { name = "nvidia-nvjitlink", marker = "(python_full_version >= '3.11' and platform_machine == 'aarch64' and sys_platform == 'linux') or (python_full_version >= '3.11' and platform_machine == 'x86_64' and sys_platform == 'linux')" }, + { name = "nvidia-nvjitlink", marker = "(python_full_version < '3.11' and platform_machine == 'AMD64' and sys_platform == 'win32') or (platform_machine == 'aarch64' and sys_platform == 'linux') or (platform_machine == 'x86_64' and sys_platform == 'linux')" }, ] nvrtc = [ - { name = "nvidia-cuda-nvrtc", marker = "(python_full_version >= '3.11' and platform_machine == 'aarch64' and sys_platform == 'linux') or (python_full_version >= '3.11' and platform_machine == 'x86_64' and sys_platform == 'linux')" }, + { name = "nvidia-cuda-nvrtc", marker = "(python_full_version < '3.11' and platform_machine == 'AMD64' and sys_platform == 'win32') or (platform_machine == 'aarch64' and sys_platform == 'linux') or (platform_machine == 'x86_64' and sys_platform == 'linux')" }, ] nvtx = [ - { name = "nvidia-nvtx", marker = "(python_full_version >= '3.11' and platform_machine == 'aarch64' and sys_platform == 'linux') or (python_full_version >= '3.11' and platform_machine == 'x86_64' and sys_platform == 'linux')" }, + { name = "nvidia-nvtx", marker = "(python_full_version < '3.11' and platform_machine == 'AMD64' and sys_platform == 'win32') or (platform_machine == 'aarch64' and sys_platform == 'linux') or (platform_machine == 'x86_64' and sys_platform == 'linux')" }, ] [[package]] @@ -2530,7 +2530,7 @@ name = "nvidia-cublas" version = "13.1.1.3" source = { registry = "https://pypi.org/simple" } dependencies = [ - { name = "nvidia-cuda-nvrtc", marker = "python_full_version >= '3.11' and sys_platform != 'emscripten' and sys_platform != 'win32'" }, + { name = "nvidia-cuda-nvrtc", marker = "(python_full_version < '3.11' and sys_platform == 'emscripten') or (python_full_version < '3.11' and sys_platform == 'win32') or (sys_platform != 'emscripten' and sys_platform != 'win32')" }, ] wheels = [ { url = "https://files.pythonhosted.org/packages/a7/a1/0bd24ee8c8d03adac032fd2909426a00c88f8c57961b1277ded97f91119f/nvidia_cublas-13.1.1.3-py3-none-manylinux_2_27_aarch64.whl", hash = "sha256:b7a210458267ac818974c53038fbec2e969d5c99f305ab15c72522fa9f001dd5", size = 542848918, upload-time = "2026-04-08T18:46:22.985Z" }, @@ -2569,7 +2569,7 @@ name = "nvidia-cudnn-cu13" version = "9.24.0.43" source = { registry = "https://pypi.org/simple" } dependencies = [ - { name = "nvidia-cublas", marker = "python_full_version >= '3.11' and sys_platform != 'emscripten' and sys_platform != 'win32'" }, + { name = "nvidia-cublas", marker = "(python_full_version < '3.11' and sys_platform == 'emscripten') or (python_full_version < '3.11' and sys_platform == 'win32') or (sys_platform != 'emscripten' and sys_platform != 'win32')" }, ] wheels = [ { url = "https://files.pythonhosted.org/packages/ca/30/7c257e3d5cb4fecb147b93895c66e29c93f8e76d74b45bb418ff0587c4ec/nvidia_cudnn_cu13-9.24.0.43-py3-none-manylinux_2_27_aarch64.whl", hash = "sha256:a6812a554a1ff0413e9c52b84c26c050380649ab9615f9c16bded368ce9f421f", size = 650976863, upload-time = "2026-07-02T16:23:39.248Z" }, @@ -2581,7 +2581,7 @@ name = "nvidia-cufft" version = "12.0.0.61" source = { registry = "https://pypi.org/simple" } dependencies = [ - { name = "nvidia-nvjitlink", marker = "python_full_version >= '3.11' and sys_platform != 'emscripten' and sys_platform != 'win32'" }, + { name = "nvidia-nvjitlink", marker = "(python_full_version < '3.11' and sys_platform == 'emscripten') or (python_full_version < '3.11' and sys_platform == 'win32') or (sys_platform != 'emscripten' and sys_platform != 'win32')" }, ] wheels = [ { url = "https://files.pythonhosted.org/packages/8b/ae/f417a75c0259e85c1d2f83ca4e960289a5f814ed0cea74d18c353d3e989d/nvidia_cufft-12.0.0.61-py3-none-manylinux2014_aarch64.manylinux_2_17_aarch64.whl", hash = "sha256:2708c852ef8cd89d1d2068bdbece0aa188813a0c934db3779b9b1faa8442e5f5", size = 214053554, upload-time = "2025-09-04T08:31:38.196Z" }, @@ -2611,9 +2611,9 @@ name = "nvidia-cusolver" version = "12.0.4.66" source = { registry = "https://pypi.org/simple" } dependencies = [ - { name = "nvidia-cublas", marker = "python_full_version >= '3.11' and sys_platform != 'emscripten' and sys_platform != 'win32'" }, - { name = "nvidia-cusparse", marker = "python_full_version >= '3.11' and sys_platform != 'emscripten' and sys_platform != 'win32'" }, - { name = "nvidia-nvjitlink", marker = "python_full_version >= '3.11' and sys_platform != 'emscripten' and sys_platform != 'win32'" }, + { name = "nvidia-cublas", marker = "(python_full_version < '3.11' and sys_platform == 'emscripten') or (python_full_version < '3.11' and sys_platform == 'win32') or (sys_platform != 'emscripten' and sys_platform != 'win32')" }, + { name = "nvidia-cusparse", marker = "(python_full_version < '3.11' and sys_platform == 'emscripten') or (python_full_version < '3.11' and sys_platform == 'win32') or (sys_platform != 'emscripten' and sys_platform != 'win32')" }, + { name = "nvidia-nvjitlink", marker = "(python_full_version < '3.11' and sys_platform == 'emscripten') or (python_full_version < '3.11' and sys_platform == 'win32') or (sys_platform != 'emscripten' and sys_platform != 'win32')" }, ] wheels = [ { url = "https://files.pythonhosted.org/packages/c8/c3/b30c9e935fc01e3da443ec0116ed1b2a009bb867f5324d3f2d7e533e776b/nvidia_cusolver-12.0.4.66-py3-none-manylinux_2_27_aarch64.whl", hash = "sha256:02c2457eaa9e39de20f880f4bd8820e6a1cfb9f9a34f820eb12a155aa5bc92d2", size = 223467760, upload-time = "2025-09-04T08:33:04.222Z" }, @@ -2625,7 +2625,7 @@ name = "nvidia-cusparse" version = "12.6.3.3" source = { registry = "https://pypi.org/simple" } dependencies = [ - { name = "nvidia-nvjitlink", marker = "python_full_version >= '3.11' and sys_platform != 'emscripten' and sys_platform != 'win32'" }, + { name = "nvidia-nvjitlink", marker = "(python_full_version < '3.11' and sys_platform == 'emscripten') or (python_full_version < '3.11' and sys_platform == 'win32') or (sys_platform != 'emscripten' and sys_platform != 'win32')" }, ] wheels = [ { url = "https://files.pythonhosted.org/packages/f8/94/5c26f33738ae35276672f12615a64bd008ed5be6d1ebcb23579285d960a9/nvidia_cusparse-12.6.3.3-py3-none-manylinux2014_aarch64.manylinux_2_17_aarch64.whl", hash = "sha256:80bcc4662f23f1054ee334a15c72b8940402975e0eab63178fc7e670aa59472c", size = 162155568, upload-time = "2025-09-04T08:33:42.864Z" }, @@ -4426,6 +4426,7 @@ relational = [ report = [ { name = "matplotlib", version = "3.10.9", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version < '3.11'" }, { name = "matplotlib", version = "3.11.2", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version >= '3.11'" }, + { name = "torch" }, ] s3 = [ { name = "structured-data-models-connectors", extra = ["s3"] }, @@ -4462,6 +4463,7 @@ requires-dist = [ { name = "structured-data-models-connectors", extras = ["sqlite"], marker = "extra == 'sqlite'", editable = "packages/structured-data-models-connectors" }, { name = "structured-data-models-pql", editable = "packages/structured-data-models-pql" }, { name = "structured-data-models-relational-engine", marker = "extra == 'relational'", editable = "packages/structured-data-models-relational-engine" }, + { name = "torch", marker = "extra == 'report'", specifier = ">=2.7" }, { name = "urllib3", specifier = ">=1.26" }, ] provides-extras = ["relational", "sqlite", "duckdb", "snowflake", "databricks", "postgres", "lakebase", "s3", "databricks-serving", "in-process", "report", "all", "test"] @@ -4791,21 +4793,22 @@ name = "torch" version = "2.14.1" source = { registry = "https://pypi.org/simple" } dependencies = [ - { name = "cuda-bindings", marker = "python_full_version >= '3.11' and sys_platform == 'linux'" }, - { name = "cuda-toolkit", extra = ["cublas", "cudart", "cufft", "cufile", "cupti", "curand", "cusolver", "cusparse", "nvjitlink", "nvrtc", "nvtx"], marker = "python_full_version >= '3.11' and sys_platform == 'linux'" }, - { name = "filelock", marker = "python_full_version >= '3.11'" }, - { name = "fsspec", marker = "python_full_version >= '3.11'" }, - { name = "jinja2", marker = "python_full_version >= '3.11'" }, + { name = "cuda-bindings", marker = "sys_platform == 'linux'" }, + { name = "cuda-toolkit", extra = ["cublas", "cudart", "cufft", "cufile", "cupti", "curand", "cusolver", "cusparse", "nvjitlink", "nvrtc", "nvtx"], marker = "sys_platform == 'linux'" }, + { name = "filelock" }, + { name = "fsspec" }, + { name = "jinja2" }, + { name = "networkx", version = "3.4.2", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version < '3.11'" }, { name = "networkx", version = "3.6.1", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version == '3.11.*'" }, { name = "networkx", version = "3.7", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version >= '3.12'" }, - { name = "nvidia-cudnn-cu13", marker = "python_full_version >= '3.11' and sys_platform == 'linux'" }, - { name = "nvidia-cusparselt-cu13", marker = "python_full_version >= '3.11' and sys_platform == 'linux'" }, - { name = "nvidia-nccl-cu13", marker = "python_full_version >= '3.11' and sys_platform == 'linux'" }, - { name = "nvidia-nvshmem-cu13", marker = "python_full_version >= '3.11' and sys_platform == 'linux'" }, - { name = "setuptools", marker = "python_full_version >= '3.11'" }, - { name = "sympy", marker = "python_full_version >= '3.11'" }, - { name = "triton", marker = "python_full_version >= '3.11' and sys_platform == 'linux'" }, - { name = "typing-extensions", marker = "python_full_version >= '3.11'" }, + { name = "nvidia-cudnn-cu13", marker = "sys_platform == 'linux'" }, + { name = "nvidia-cusparselt-cu13", marker = "sys_platform == 'linux'" }, + { name = "nvidia-nccl-cu13", marker = "sys_platform == 'linux'" }, + { name = "nvidia-nvshmem-cu13", marker = "sys_platform == 'linux'" }, + { name = "setuptools" }, + { name = "sympy" }, + { name = "triton", marker = "sys_platform == 'linux'" }, + { name = "typing-extensions" }, ] wheels = [ { url = "https://files.pythonhosted.org/packages/7a/45/b0c389051ed02d77227202caf2c2abb1706ca4362781eb79bd6707359970/torch-2.14.1-cp310-cp310-macosx_14_0_arm64.whl", hash = "sha256:e24b9815001d18e73e76eae1ea25f8ef908c6103e857378ad20f8f6cf5c954f5", size = 127249640, upload-time = "2026-09-30T17:43:48.426Z" },