Skip to content
Draft
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
9 changes: 9 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down
6 changes: 5 additions & 1 deletion packages/structured-data-models-client/pyproject.toml
Original file line number Diff line number Diff line change
Expand Up @@ -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]",
]
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -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,
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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:
Expand Down
Original file line number Diff line number Diff line change
@@ -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']
Original file line number Diff line number Diff line change
@@ -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.
"""
Loading
Loading