From 094108b684291a78eb64b05362c3cb7caf8d51cb Mon Sep 17 00:00:00 2001 From: Manush Murali Date: Mon, 2 Nov 2026 21:27:32 -0800 Subject: [PATCH 1/8] Continue a series for as many steps as were asked for Adds `kumo-forecast`, served by structured-data-models in this process. ```python client.predict(Request.forecast(history, target='flow', horizon=24), model=KumoForecast()) ``` It reads a context and fits nothing, so it joins the anomaly model behind the protocol that was named for the one case there was: a model that answers in one pass holds nothing afterwards, and neither has a session. The history travels as the context, and the horizon as one row per step carrying the series being asked about and nothing in it. The model reads no column of those rows and takes the horizon from how many there are. A table of no columns would say the same and is not a table the contract has. Nothing known about the future is sent, because nothing about it is read: the model discards a future covariate with a warning nobody is obliged to see, so the constructor offers no way to supply one. Retrieval is the knob worth a word. `alpha` below one blends historical windows into the forecast, and the model ignores it in silence unless the history is longer than one context window plus the horizon, so a caller who sets it on a short history is told their forecast is the direct one. The threshold is read off the model rather than written down. The refusal naming which models `in_process()` takes read two of them from a sentence; it now reads them from the models that are served. Co-Authored-By: Claude Opus 5 Signed-off-by: Manush Murali --- .../src/sdm_client/__init__.py | 2 + .../src/sdm_client/adapters/__init__.py | 3 +- .../src/sdm_client/adapters/anomaly.py | 26 +- .../src/sdm_client/adapters/forecast.py | 221 ++++++++++++++++ .../src/sdm_client/adapters/single_table.py | 18 ++ .../src/sdm_client/client.py | 4 + .../src/sdm_client/in_process/backend.py | 41 +-- .../src/sdm_client/in_process/forecast.py | 241 ++++++++++++++++++ .../src/sdm_client/models.py | 39 ++- .../src/sdm_client/request.py | 94 +++++++ .../tests/conftest.py | 8 + .../test_a_model_runs_in_this_process.py | 1 + ..._a_series_is_continued_from_its_history.py | 201 +++++++++++++++ scripts/check_wire_payloads.py | 7 +- scripts/snapshot_wire_payloads.py | 15 ++ tests/golden/public_api.json | 13 + tests/golden/wire_payloads.json | 132 ++++++++++ tests/test_release_contract.py | 18 +- 18 files changed, 1033 insertions(+), 51 deletions(-) create mode 100644 packages/structured-data-models-client/src/sdm_client/adapters/forecast.py create mode 100644 packages/structured-data-models-client/src/sdm_client/in_process/forecast.py create mode 100644 packages/structured-data-models-client/tests/test_a_series_is_continued_from_its_history.py diff --git a/packages/structured-data-models-client/src/sdm_client/__init__.py b/packages/structured-data-models-client/src/sdm_client/__init__.py index 1b20c794c..d3ecff16e 100644 --- a/packages/structured-data-models-client/src/sdm_client/__init__.py +++ b/packages/structured-data-models-client/src/sdm_client/__init__.py @@ -37,6 +37,7 @@ ) from sdm_client.models import ( KumoAnomaly, + KumoForecast, KumoRelational, KumoTabular, Model, @@ -60,6 +61,7 @@ 'FittedModel', 'GradientExplanations', 'KumoAnomaly', + 'KumoForecast', 'KumoRelational', 'KumoTabular', 'MissingExtraError', diff --git a/packages/structured-data-models-client/src/sdm_client/adapters/__init__.py b/packages/structured-data-models-client/src/sdm_client/adapters/__init__.py index de347bcb2..12b8475b7 100644 --- a/packages/structured-data-models-client/src/sdm_client/adapters/__init__.py +++ b/packages/structured-data-models-client/src/sdm_client/adapters/__init__.py @@ -5,6 +5,7 @@ """Per-model adapters. One module per model.""" from sdm_client.adapters.anomaly import AnomalyAdapter +from sdm_client.adapters.forecast import ForecastAdapter from sdm_client.adapters.tabular import TabularAdapter -__all__ = ['AnomalyAdapter', 'TabularAdapter'] +__all__ = ['AnomalyAdapter', 'ForecastAdapter', 'TabularAdapter'] diff --git a/packages/structured-data-models-client/src/sdm_client/adapters/anomaly.py b/packages/structured-data-models-client/src/sdm_client/adapters/anomaly.py index 7725e3a23..9cfe3b3ab 100644 --- a/packages/structured-data-models-client/src/sdm_client/adapters/anomaly.py +++ b/packages/structured-data-models-client/src/sdm_client/adapters/anomaly.py @@ -26,8 +26,7 @@ ) from sdm_client.adapters.single_table import ( - MEANING_OF, - coherent_stype, + meaning_a_single_meaning_model_reads, named_entities, ) from sdm_client.base import ModelSpec @@ -170,7 +169,9 @@ def _envelope( 'columns': { name: { 'dtype': dtypes[name], - 'stype': _meaning(table[name], dtypes[name]), + 'stype': meaning_a_single_meaning_model_reads( + table[name], dtypes[name] + ), } for name in readings.columns } @@ -203,22 +204,3 @@ def _envelope( json_ready(request.inference) ) return envelope - - -def _meaning(column: Any, dtype: str) -> str: - r"""What to declare a column as, for a model that reads one meaning. - - `coherent_stype` holds a placeholder meaning only where the dtype cannot - carry it, and a float can be categorical, so a column with nothing in it - to read stays categorical and this model then refuses it. The readings are - numbers and the model reconstructs numbers, so there the meaning follows - the dtype instead. - - Only that column, and only where nothing was said about it either. A - column that holds values carries a claim, and so does one a caller typed - by hand though it held none; both are left alone to be refused on their - own terms. - """ - if not column.untyped or column.stype_declared: - return coherent_stype(column.stype, dtype, column) - return MEANING_OF.get(dtype) or coherent_stype(column.stype, dtype, column) diff --git a/packages/structured-data-models-client/src/sdm_client/adapters/forecast.py b/packages/structured-data-models-client/src/sdm_client/adapters/forecast.py new file mode 100644 index 000000000..c80561968 --- /dev/null +++ b/packages/structured-data-models-client/src/sdm_client/adapters/forecast.py @@ -0,0 +1,221 @@ +# SPDX-FileCopyrightText: Copyright (c) 2026, NVIDIA CORPORATION & AFFILIATES. +# All rights reserved. +# SPDX-License-Identifier: Apache-2.0 + +r"""Shaping a request for ``kumo-forecast``. + +The history travels as the context, and the horizon as rows to score that +carry no columns. That is the model's own shape: it reads nothing from those +rows, and the count of them is the number of steps asked for. + +Nothing known about the future goes out, because nothing known about the +future is read. The model discards a future covariate with a warning nobody +is obliged to see, so `Request.forecast` offers no way to supply one rather +than accepting a column and dropping it. +""" + +from __future__ import annotations + +import uuid +from collections.abc import Iterator, Mapping, Sequence +from typing import Any + +from sdm_api.generated.tfm_api import ( + PredictionItem, + PredictionResponse, + ResponseContractError, +) + +from sdm_client.adapters.single_table import ( + meaning_a_single_meaning_model_reads, +) +from sdm_client.base import ModelSpec +from sdm_client.errors import StructuredDataError, UnsupportedRequestError +from sdm_client.models import KUMO_FORECAST +from sdm_client.request import Request +from sdm_client.result import PredictionResult +from sdm_client.wire import ( + UNTYPED, + encode_table, + infer_tfm_dtype, + json_ready, + widen_tfm_dtype, +) +from sdm_client.wire.inference import typed_inference + +_DEFAULT_OUTPUTS = ('prediction',) + + +def _request_id() -> str: + return f'sdm-{uuid.uuid4().hex[:12]}' + + +class ForecastAdapter: + r"""Shapes and reads ``kumo-forecast`` requests.""" + + spec: ModelSpec = KUMO_FORECAST + + def default_output(self, request: Request) -> tuple[str, ...]: + return _DEFAULT_OUTPUTS + + def prediction_plan( + self, request: Request, outputs: tuple[str, ...] + ) -> Iterator[dict[str, Any]]: + r"""One payload. Each step is forecast from the ones before it, so + splitting the horizon would ask a different question of each part.""" + yield self._envelope(request, outputs) + + def session_plan( + self, request: Request, outputs: tuple[str, ...] + ) -> dict[str, Any]: + raise UnsupportedRequestError( + f'{self.spec.model_id} holds no session: it fits nothing, so ' + f'there is no context to pin. Call predict(), which sends the ' + f'history with every call' + ) + + def session_prediction_plan( + self, + request: Request, + outputs: tuple[str, ...], + pinned: Mapping[str, Any] | None = None, + ) -> Iterator[dict[str, Any]]: + raise UnsupportedRequestError(f'{self.spec.model_id} holds no session') + + def normalize( + self, + response: dict[str, Any], + outputs: tuple[str, ...], + payload: dict[str, Any] | None = None, + ) -> PredictionResult: + try: + parsed = PredictionResponse.from_dict(response) + except (ResponseContractError, TypeError, ValueError) as error: + raise StructuredDataError( + f'{self.spec.model_id} returned a response that does not ' + f'match the contract: {error}', + code='INVALID_RESPONSE', + ) from error + return self.answered( + parsed.predictions, + outputs, + payload, + model=parsed.model, + request_id=parsed.id, + metadata=parsed.metadata, + ) + + def answered( + self, + items: Sequence[PredictionItem], + outputs: tuple[str, ...], + payload: dict[str, Any] | None, + *, + model: str, + request_id: str = '', + metadata: Mapping[str, Any] | None = None, + ) -> PredictionResult: + unstepped = [ + item.row_index for item in items if item.forecast_step is None + ] + if unstepped: + raise StructuredDataError( + f'a forecast answer for row(s) {unstepped} names no step, so ' + f'it cannot be put in order', + code='INVALID_RESPONSE', + ) + result = PredictionResult( + model=model, + request_id=request_id, + items=items, + metadata=dict(metadata or {}), + outputs=outputs, + ) + result._names_its_rows = False + result._names_its_step = True + return result + + def explain_error( + self, error: Exception, payload: dict[str, Any] + ) -> Exception: + r"""Nothing to add: a refusal here is about the history, which the + caller handed over whole.""" + return error + + def close(self) -> None: + r"""Nothing to release.""" + + def _envelope( + self, request: Request, outputs: tuple[str, ...] + ) -> dict[str, Any]: + if request.payloads is not None: + raise UnsupportedRequestError( + f'this request was gathered for another model and carries ' + f'the sampled payloads that model reads; ' + f'{self.spec.model_id} is asked with Request.forecast(...)' + ) + request.schema.check_consistent() + + table = request.schema[request.entity_table] + history = request.context.instance_table + target = request.task.target.column_name + + dtypes = { + name: (UNTYPED if column.untyped else column.dtype) + for name, column in table.columns.items() + } + for name in history.columns: + if name in dtypes: + dtypes[name] = widen_tfm_dtype( + (dtypes[name], infer_tfm_dtype(history[name])) + ) + dtypes = {name: dtype or 'string' for name, dtype in dtypes.items()} + + missing = [name for name in history.columns if name not in dtypes] + if missing: + raise StructuredDataError( + f'schema does not describe column(s) {missing}', + code='INVALID_REQUEST', + ) + + instance_schema: dict[str, Any] = { + 'columns': { + name: { + 'dtype': dtypes[name], + 'stype': meaning_a_single_meaning_model_reads( + table[name], dtypes[name] + ), + } + for name in history.columns + } + } + key = table.primary_key + if key: + instance_schema['primary_key'] = ( + [key] if isinstance(key, str) else list(key) + ) + + envelope: dict[str, Any] = { + 'model': self.spec.model_id, + 'task': { + 'kind': request.task.kind, + 'target': { + 'column_name': target, + 'dtype': dtypes[target], + }, + }, + 'schema': {'instance_table': instance_schema}, + 'context': {'instance_table': encode_table(history, dtypes)}, + 'predict': { + 'instance_table': encode_table( + request.predict.instance_table, dtypes + ) + }, + 'output': {'fields': list(outputs)}, + 'metadata': {'request_id': _request_id()}, + } + if request.inference: + envelope['inference'] = typed_inference( + json_ready(request.inference) + ) + return envelope diff --git a/packages/structured-data-models-client/src/sdm_client/adapters/single_table.py b/packages/structured-data-models-client/src/sdm_client/adapters/single_table.py index 122fc3c7d..b05accc86 100644 --- a/packages/structured-data-models-client/src/sdm_client/adapters/single_table.py +++ b/packages/structured-data-models-client/src/sdm_client/adapters/single_table.py @@ -223,3 +223,21 @@ def coherent_stype(stype: str, dtype: str, column: Column) -> str: if dtype.startswith('timestamp'): return 'timestamp' return MEANING_OF.get(dtype, 'categorical') + + +def meaning_a_single_meaning_model_reads(column: Column, dtype: str) -> str: + r"""What to declare a column as, for a model that reads one meaning. + + `coherent_stype` holds a placeholder meaning only where the dtype cannot + carry it, and a float can be categorical, so a column with nothing in it + to read stays categorical and a model that reads only numbers then + refuses it. There the meaning follows the dtype instead. + + Only that column, and only where nothing was said about it either. A + column that holds values carries a claim, and so does one a caller typed + by hand though it held none; both are left alone to be refused on their + own terms. + """ + if not column.untyped or column.stype_declared: + return coherent_stype(column.stype, dtype, column) + return MEANING_OF.get(dtype) or coherent_stype(column.stype, dtype, column) 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 8325e004e..47c1efa81 100644 --- a/packages/structured-data-models-client/src/sdm_client/client.py +++ b/packages/structured-data-models-client/src/sdm_client/client.py @@ -86,6 +86,10 @@ def _adapter_for(spec: ModelSpec) -> ModelAdapter: from sdm_client.adapters.anomaly import AnomalyAdapter return AnomalyAdapter() + if spec.model_id == 'kumo-forecast': + from sdm_client.adapters.forecast import ForecastAdapter + + return ForecastAdapter() raise UnknownModelError(spec.model_id, list(MODELS)) diff --git a/packages/structured-data-models-client/src/sdm_client/in_process/backend.py b/packages/structured-data-models-client/src/sdm_client/in_process/backend.py index 7250be495..01c8b29f7 100644 --- a/packages/structured-data-models-client/src/sdm_client/in_process/backend.py +++ b/packages/structured-data-models-client/src/sdm_client/in_process/backend.py @@ -36,6 +36,7 @@ regressed, ) from sdm_client.in_process.columns import Context +from sdm_client.in_process.forecast import Forecast from sdm_client.in_process.relational import Relational from sdm_client.in_process.tabular import Tabular @@ -48,21 +49,23 @@ _ESTIMATORS = 1 _SERVED = { - served.model_id: served for served in (Tabular(), Relational(), Anomaly()) + served.model_id: served + for served in (Tabular(), Relational(), Anomaly(), Forecast()) } #: What reads a request for one model. -Served = Tabular | Relational | Anomaly +Served = Tabular | Relational | Anomaly | Forecast @runtime_checkable -class ScoresRowsAlone(Protocol): - r"""A model shown no labelled rows, which therefore fits no context. - - It answers from the rows it is given and nothing carries over, so there - is no fitted context to pin and no session to hold. Declaring that as a - protocol rather than a flag is what lets the two shapes be told apart - where it matters, by what a reader actually has to offer. +class AnswersWithoutFitting(Protocol): + r"""A model that answers a request in one pass, fitting nothing. + + One is shown no labelled rows at all; another reads a history and a + horizon and continues the series from them. Neither holds anything + afterwards, so neither has a fitted context to pin or a session over it. + Declaring that as a protocol rather than a flag is what lets the two + shapes be told apart where it matters, by what a reader has to offer. """ def row_ids( @@ -189,7 +192,7 @@ def predict( ) served, model = self._serving(payload['model']) _check_loaded_for(served, model, task['kind']) - if isinstance(served, ScoresRowsAlone): + if isinstance(served, AnswersWithoutFitting): items = _scored(served, model, payload, fields) else: context = served.context(payload) @@ -230,11 +233,11 @@ def create_session( with self._running(): kind = payload['task']['kind'] served = self._reader(payload['model']) - if isinstance(served, ScoresRowsAlone): + if isinstance(served, AnswersWithoutFitting): raise StructuredDataError( - f'{served.model_id} holds no session: it is shown no ' - f'labelled rows, so there is no fitted context to pin. ' - f'Call predict() instead', + f'{served.model_id} holds no session: it fits nothing, ' + f'so there is no fitted context to pin. Call predict() ' + f'instead, which sends the whole question every time', code='SESSIONS_UNSUPPORTED', ) _fields(served, kind, payload) @@ -412,10 +415,10 @@ def _served_by(model: Any) -> Served: for served in _SERVED.values(): if served.accepts(model): return served + taken = ', '.join(sorted(served.model_id for served in _SERVED.values())) raise StructuredDataError( - f'in_process() takes the KumoTabular and KumoRelational models of ' - f'structured-data-models, and got a {type(model).__name__}; the ' - f'client asks no other model', + f'in_process() takes the structured-data-models behind {taken}, and ' + f'got a {type(model).__name__}; the client asks no other model', code='INVALID_CONFIGURATION', ) @@ -468,7 +471,7 @@ def _check_loaded_for(served: Served, model: Any, kind: str) -> None: no head to package. It answers the one task it is for or it is not that model. """ - if isinstance(served, ScoresRowsAlone): + if isinstance(served, AnswersWithoutFitting): return needed = 'regression' if kind == 'regression' else 'classification' loaded = sorted(str(task) for task in model.tasks) @@ -584,7 +587,7 @@ def _autocast(device: Any) -> Any: def _scored( - served: ScoresRowsAlone, + served: AnswersWithoutFitting, model: Any, payload: Mapping[str, Any], fields: list[str], 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 new file mode 100644 index 000000000..0ac666577 --- /dev/null +++ b/packages/structured-data-models-client/src/sdm_client/in_process/forecast.py @@ -0,0 +1,241 @@ +# SPDX-FileCopyrightText: Copyright (c) 2026, NVIDIA CORPORATION & AFFILIATES. +# All rights reserved. +# SPDX-License-Identifier: Apache-2.0 + +r"""``kumo-forecast`` in process: a series continued for a number of steps. + +It reads a context and fits nothing. The history, the series to continue and +the number of steps all travel on every call, and the model answers from them +in one pass, so there is no fitted context to hold and no session over it. + +The rows to score carry the series being asked about and nothing in it: one +unknown value per step. The model reads no column of them and takes the +horizon from how many there are. It discards a future covariate with a +warning nobody is obliged to see, so `Request.forecast` gives no way to +supply one; a column the caller cannot pass is one they cannot believe was +used. +""" + +from __future__ import annotations + +from collections.abc import Mapping, Sequence +from typing import Any + +from sdm_api.generated.tfm_api import PredictionItem + +from sdm_client.errors import StructuredDataError +from sdm_client.in_process.columns import ( + Shape, + check_columns, + key_columns, + stype_of, +) + +#: Retrieval blends historical windows into the forecast. One is the direct +#: forecast alone, which is what the model does when it is not asked. +_ALPHA = 1.0 +_NEIGHBOURS = 64 +_TEMPERATURE = 0.05 + +_KNOBS = ('alpha', 'k', 'temperature') + + +class Forecast: + r"""Reads a ``kumo-forecast`` request into the model.""" + + model_id = 'kumo-forecast' + outputs = {'forecasting': ('prediction',)} + + @staticmethod + def installed() -> bool: + r"""Whether the structured-data-models here carries this model.""" + try: + _model_type() + except StructuredDataError: + return False + return True + + @staticmethod + def load(device: Any) -> Any: + return _model_type()(device=device) + + @staticmethod + def accepts(model: Any) -> bool: + r"""Whether ``model`` is this one. + + Asked of every model handed to the client, including ones this does + not serve, so an installed structured-data-models that predates + ``KumoForecast`` has to answer no rather than raise. + """ + try: + return isinstance(model, _model_type()) + except StructuredDataError: + return False + + def check_inference( + self, + options: Mapping[str, Any], + task: Mapping[str, Any], + settled: bool = False, + ) -> None: + r"""Refuse an inference option this model does not act on.""" + remaining = dict(options) + if remaining.pop('inference_config', {}): + raise StructuredDataError( + 'inference_config is reserved for API compatibility and must ' + 'be omitted or empty', + code='INVALID_REQUEST', + ) + unknown = sorted(set(remaining) - set(_KNOBS)) + if unknown: + raise StructuredDataError( + f'unsupported inference options: {unknown}', + code='INVALID_REQUEST', + ) + alpha = remaining.get('alpha') + if alpha is not None and not 0.0 <= float(alpha) <= 1.0: + raise StructuredDataError( + f'alpha is {alpha}; it is between zero and one, where one is ' + f'the direct forecast alone and zero is retrieval alone', + code='INVALID_REQUEST', + ) + neighbours = remaining.get('k') + if neighbours is not None and ( + not isinstance(neighbours, int) + or isinstance(neighbours, bool) + or neighbours < 1 + ): + raise StructuredDataError( + f'k is {neighbours!r}; it is a whole number of at least 1', + code='INVALID_REQUEST', + ) + + def series( + self, payload: Mapping[str, Any], target: str + ) -> tuple[Any, Any]: + r"""The history, split into the series to continue and what else was + measured alongside it.""" + spec = payload['schema']['instance_table'] + table = payload['context']['instance_table'] + check_columns(table, spec, 'the history') + if target not in table['columns']: + raise StructuredDataError( + f'the history carries no column {target!r}, which is the ' + f'series being forecast', + code='INVALID_REQUEST', + ) + keys = key_columns(spec) + stypes = { + name: stype_of(name, spec['columns'][name]) + for name in table['columns'] + if name not in keys + } + unread = sorted( + name for name, stype in stypes.items() if stype != 'numerical' + ) + if unread: + raise StructuredDataError( + f'{self.model_id} forecasts numbers from numbers, and ' + f'{unread} is not numerical. Leave it out of the history', + code='UNSUPPORTED_DTYPE', + ) + measured = { + name: stype for name, stype in stypes.items() if name != target + } + history = Shape.of(spec, {target: stypes[target]}).tensor( + table, 'the history' + ) + alongside = Shape.of(spec, measured).tensor(table, 'the history') + return history, alongside + + @staticmethod + def row_ids( + table: Mapping[str, Any], spec: Mapping[str, Any] + ) -> list[str | None]: + r"""A forecast answers about a step rather than a row of the request, + so each answer names its step and carries no id.""" + return [None] * len(table['rows']) + + def answer( + self, + model: Any, + payload: Mapping[str, Any], + ids: Sequence[Any], + fields: Sequence[str], + generator: Any = None, + ) -> list[PredictionItem]: + r"""Continue the series for as many steps as were asked for.""" + target = payload['task']['target']['column_name'] + history, alongside = self.series(payload, target) + horizon = len(payload['predict']['instance_table']['rows']) + if horizon == 0: + return [] + options = payload.get('inference') or {} + alpha = float(options.get('alpha', _ALPHA)) + self._warn_where_retrieval_does_nothing( + model, + alpha, + len(payload['context']['instance_table']['rows']), + horizon, + ) + if generator is not None: + history = history.to(generator.device) + alongside = alongside.to(generator.device) + out = model( + alongside, + history, + alongside[:horizon, ..., :0], + alpha=alpha, + k=int(options.get('k', _NEIGHBOURS)), + temperature=options.get('temperature', _TEMPERATURE), + ) + forecast = out[target].numerical[..., 0] + if not bool(forecast.isfinite().all()): + raise StructuredDataError( + 'the model answered with a malformed output', + code='INTERNAL_ERROR', + ) + return [ + PredictionItem(row_index=step, forecast_step=step, prediction=value) + for step, value in enumerate(forecast.tolist()) + ] + + @staticmethod + def _warn_where_retrieval_does_nothing( + model: Any, alpha: float, history: int, horizon: int + ) -> None: + r"""Retrieval needs a history longer than one window to retrieve from, + and below that the model ignores ``alpha`` without saying so.""" + import warnings + + from sdm_client.core.warnings import SDMWarning, caller_stacklevel + + if alpha >= 1.0: + return + needed = model.model.context_size + max( + model.model.prediction_size, horizon + ) + if history >= needed: + return + warnings.warn( + f'alpha={alpha} asks for retrieval, which needs at least ' + f'{needed} rows of history to retrieve from and this has ' + f'{history}. The forecast is the direct one, as though alpha ' + f'were 1.', + category=SDMWarning, + stacklevel=caller_stacklevel(), + ) + + +def _model_type() -> Any: + r"""``sdm.models.KumoForecast``, or why it could not be reached.""" + try: + from sdm.models import KumoForecast + except ImportError as error: + raise StructuredDataError( + 'this structured-data-models carries no KumoForecast. The model ' + 'is on its main and in no release, so until one ships it is ' + 'reached by installing that package from source', + code='MODEL_NOT_READY', + ) from error + return KumoForecast 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 f4e79d2e3..e5d308f71 100644 --- a/packages/structured-data-models-client/src/sdm_client/models.py +++ b/packages/structured-data-models-client/src/sdm_client/models.py @@ -32,7 +32,7 @@ from __future__ import annotations -from predictive_query import ANOMALY, RELATIONAL, TABULAR +from predictive_query import ANOMALY, RELATIONAL, TABULAR, TIMESERIES from sdm_api import TFM_MODEL_KUMO_RELATIONAL, TFM_MODEL_KUMO_TABULAR from sdm_client.base import ModelSpec, RuntimeContract @@ -185,6 +185,22 @@ ) +TFM_MODEL_KUMO_FORECAST = 'kumo-forecast' + +KUMO_FORECAST = ModelSpec( + model_id=TFM_MODEL_KUMO_FORECAST, + profile=TIMESERIES, + runtime=RuntimeContract( + tasks=frozenset({'forecasting'}), + outputs=frozenset({'prediction'}), + # Every call carries the history, the horizon and nothing held over: + # the model fits no context, so there is none to pin. + sessions=False, + inference_options=frozenset({'alpha', 'k', 'temperature'}), + ), +) + + class Model: r"""Base for the model handles. Not useful on its own.""" @@ -254,11 +270,32 @@ class KumoAnomaly(Model): _spec = KUMO_ANOMALY +class KumoForecast(Model): + r"""A history in, the next steps of it out. + + Takes ``forecasting`` only, and produces ``prediction``, one row per step + with the step named. Built with + :meth:`Request.forecast `, which takes the + history and how many steps to continue it for. It holds no session, + because it fits nothing. + + Served in this process only, through + :meth:`SDMClient.in_process `: no + deployment answers for this id yet. + + Needs a structured-data-models that carries ``KumoForecast``, which no + release does yet. + """ + + _spec = KUMO_FORECAST + + #: Every model this client can send to, by id. MODELS = { KUMO_TABULAR.model_id: KUMO_TABULAR, KUMO_RELATIONAL.model_id: KUMO_RELATIONAL, KUMO_ANOMALY.model_id: KUMO_ANOMALY, + KUMO_FORECAST.model_id: KUMO_FORECAST, } diff --git a/packages/structured-data-models-client/src/sdm_client/request.py b/packages/structured-data-models-client/src/sdm_client/request.py index 900becc35..8a5242b75 100644 --- a/packages/structured-data-models-client/src/sdm_client/request.py +++ b/packages/structured-data-models-client/src/sdm_client/request.py @@ -627,6 +627,100 @@ def anomaly( request.entity_table = entity_table return request + @classmethod + def forecast( + cls, + history: pd.DataFrame, + *, + target: str, + horizon: int, + schema: Schema | None = None, + entity_table: str = 'instance', + inference: Mapping[str, Any] | None = None, + ) -> Request: + r"""Continue a series for ``horizon`` steps beyond its history. + + The rows of ``history`` are time steps in the order they happened. + There are no rows to score: the question is about steps that have not + been measured, so the horizon is a count rather than a frame, and + nothing known about the future travels, because the model reads + nothing about it. + + Args: + history: The series so far, one row per step. Must carry + ``target``; every other numerical column is read as something + measured alongside it. + target: The column being forecast. + horizon: How many steps to continue it for. + schema: Override the inferred schema. Rarely needed. + entity_table: The name the instance table is known by. + inference: Gathering knobs passed to the adapter. + + Raises: + StructuredDataError: If ``history`` is not a DataFrame, carries no + ``target``, or has no rows, or ``horizon`` is not a positive + whole number. + + >>> request = Request.forecast(readings, target='flow', horizon=24) + >>> client.predict(request, model=KumoForecast()) + """ + history = _require_frame(history, 'history') + if isinstance(horizon, bool) or not isinstance(horizon, int): + raise StructuredDataError( + f'horizon is {horizon!r}; it is a whole number of steps', + code='INVALID_REQUEST', + ) + if horizon < 1: + raise StructuredDataError( + f'horizon is {horizon}; a forecast of no steps is not a ' + f'question with an answer', + code='INVALID_REQUEST', + ) + if len(history) == 0: + raise StructuredDataError( + 'history has no rows, so there is no series to continue', + code='INVALID_REQUEST', + ) + if target not in history.columns: + raise StructuredDataError( + f'history has no column {target!r}, which is the series ' + f'being forecast; it has ' + f'{sorted(map(str, history.columns))}', + code='INVALID_REQUEST', + ) + if schema is None: + schema = Schema.from_data({entity_table: history}) + _check_scored_values_mean_what_the_schema_says( + history, schema, entity_table + ) + + request = cls.__new__(cls) + request.schema = schema + request.task = Task( + kind='forecasting', + target=Target( + column_name=target, + dtype=schema[entity_table][target].dtype, + table_name=entity_table, + ), + ) + request.horizon = horizon + # The history is what the model is shown, which is the context. The + # half to score is one row per step, carrying the series being asked + # about and nothing in it: those are the steps whose value is not + # known, which is the question. A table of no columns would say the + # same and is not a table the contract has. + request._context = Split(instance_table=history) + request._predict = Split( + instance_table=pd.DataFrame( + {target: [None] * horizon}, dtype='object' + ) + ) + request.inference = dict(inference or {}) + request.requested_inference = dict(inference or {}) + request.entity_table = entity_table + return request + @property def _question(self) -> Question: r"""What this request asks. See :class:`Question`.""" diff --git a/packages/structured-data-models-client/tests/conftest.py b/packages/structured-data-models-client/tests/conftest.py index bdda5ae67..cbe0270e3 100644 --- a/packages/structured-data-models-client/tests/conftest.py +++ b/packages/structured-data-models-client/tests/conftest.py @@ -40,6 +40,14 @@ def anomaly(sdm): return sdm.models.KumoAnomaly(pretrained=False, device='cpu') +@pytest.fixture(scope='module') +def forecast(sdm): + import torch + + torch.manual_seed(0) + return sdm.models.KumoForecast(pretrained=False, device='cpu') + + @pytest.fixture(scope='module') def relational(sdm): pytest.importorskip('sdm_relational_engine', reason='needs [relational]') diff --git a/packages/structured-data-models-client/tests/test_a_model_runs_in_this_process.py b/packages/structured-data-models-client/tests/test_a_model_runs_in_this_process.py index a8c08ce52..48b70b59d 100644 --- a/packages/structured-data-models-client/tests/test_a_model_runs_in_this_process.py +++ b/packages/structured-data-models-client/tests/test_a_model_runs_in_this_process.py @@ -270,6 +270,7 @@ def load(**kwargs): 'kumo-tabular', 'kumo-relational', 'kumo-anomaly', + 'kumo-forecast', ] assert loads == [] client.predict(request, model=KumoTabular()) diff --git a/packages/structured-data-models-client/tests/test_a_series_is_continued_from_its_history.py b/packages/structured-data-models-client/tests/test_a_series_is_continued_from_its_history.py new file mode 100644 index 000000000..485364d0e --- /dev/null +++ b/packages/structured-data-models-client/tests/test_a_series_is_continued_from_its_history.py @@ -0,0 +1,201 @@ +# SPDX-FileCopyrightText: Copyright (c) 2026, NVIDIA CORPORATION & AFFILIATES. +# All rights reserved. +# SPDX-License-Identifier: Apache-2.0 + +"""``kumo-forecast`` asked to continue a series it is shown the history of. + +A small random-weight model stands in for the published one, so nothing is +downloaded and no GPU is needed. +""" + +from __future__ import annotations + +import numpy as np +import pandas as pd +import pytest + +from sdm_client import ( + KumoForecast, + KumoTabular, + Request, + SDMClient, + StructuredDataError, + UnsupportedRequestError, +) +from sdm_client.core.warnings import SDMWarning + +pytestmark = pytest.mark.filterwarnings('ignore') + +#: The published model reads 512 steps and forecasts 72, so retrieval needs a +#: history longer than both put together before it has anything to retrieve. +RETRIEVAL_NEEDS = 512 + 72 + + +def history(rows: int = 200) -> pd.DataFrame: + step = np.arange(rows, dtype=float) + return pd.DataFrame({'flow': np.sin(step / 9), 'temp': np.cos(step / 7)}) + + +def forecast_of(model, frame: pd.DataFrame, horizon: int = 6, **inference): + with SDMClient.in_process(model) as client: + request = Request.forecast( + frame, target='flow', horizon=horizon, inference=inference or None + ) + return client.predict(request, model=KumoForecast()).to_pandas() + + +def test_one_row_per_step_comes_back_in_order(forecast): + answer = forecast_of(forecast, history(), horizon=6) + + assert list(answer.columns) == ['row_index', 'forecast_step', 'prediction'] + assert answer['forecast_step'].tolist() == list(range(6)) + assert np.isfinite(answer['prediction']).all() + + +@pytest.mark.parametrize('horizon', [1, 6, 80]) +def test_the_horizon_is_how_many_steps_are_asked_for(forecast, horizon): + """Beyond the model's own 72 the forecast is extended autoregressively, + which is still the horizon that was asked for.""" + assert len(forecast_of(forecast, history(), horizon=horizon)) == horizon + + +def test_the_answer_is_the_one_the_model_gives_when_called_directly( + sdm, forecast +): + """Nothing is computed on the way through: the client shapes the request + and reads the answer back, and the numbers are the model's own.""" + import torch + + frame = history() + answer = forecast_of(forecast, frame, horizon=6) + target = sdm.TableTensor.from_pandas(frame[['flow']], {'flow': 'numerical'}) + alongside = sdm.TableTensor.from_pandas( + frame[['temp']], {'temp': 'numerical'} + ) + direct = forecast(alongside, target, alongside[:6, ..., :0]) + + torch.testing.assert_close( + torch.tensor(answer['prediction'].to_numpy()), + direct['flow'].numerical[..., 0].double(), + ) + + +def test_the_same_history_forecasts_the_same_twice(forecast): + frame = history() + + assert forecast_of(forecast, frame)['prediction'].tolist() == ( + pytest.approx(forecast_of(forecast, frame)['prediction'].tolist()) + ) + + +def test_a_key_column_is_not_read_as_history(forecast): + """`reading_id` names the step. Forecasting from it would read a counter + that rises for ever as though it were something measured.""" + frame = history() + keyed = frame.assign(reading_id=np.arange(len(frame))) + + assert forecast_of(forecast, keyed)['prediction'].tolist() == ( + pytest.approx(forecast_of(forecast, frame)['prediction'].tolist()) + ) + + +@pytest.mark.parametrize('horizon', [0, -1, 1.5, True]) +def test_a_horizon_that_is_not_a_count_of_steps_is_refused(forecast, horizon): + with pytest.raises(StructuredDataError) as caught: + Request.forecast(history(), target='flow', horizon=horizon) + assert 'horizon' in str(caught.value) + + +def test_a_history_without_the_series_is_refused(forecast): + with pytest.raises(StructuredDataError) as caught: + Request.forecast(history(), target='missing', horizon=4) + assert 'missing' in str(caught.value) + + +def test_a_history_with_no_rows_is_refused(forecast): + with pytest.raises(StructuredDataError) as caught: + Request.forecast(history().iloc[:0], target='flow', horizon=4) + assert 'no rows' in str(caught.value) + + +def test_a_column_the_model_cannot_forecast_from_is_refused(forecast): + frame = history() + frame['site'] = 'north' + + with pytest.raises(StructuredDataError) as caught: + forecast_of(forecast, frame) + assert 'site' in str(caught.value) + + +def test_retrieval_that_has_nothing_to_retrieve_from_says_so(forecast): + """Below one window plus a horizon the model ignores `alpha` without + saying anything, so a caller who set it would read a direct forecast and + believe it was blended.""" + with pytest.warns(SDMWarning, match='retrieval'): + forecast_of(forecast, history(200), alpha=0.2) + + +def test_retrieval_that_can_run_is_not_warned_about(forecast): + import warnings + + with warnings.catch_warnings(): + warnings.simplefilter('error', SDMWarning) + forecast_of(forecast, history(RETRIEVAL_NEEDS), alpha=0.2) + + +def test_retrieval_changes_the_forecast_where_it_runs(forecast): + """The premise of the warning above: with enough history it does + something, so a run that is silently skipped is worth saying.""" + frame = history(RETRIEVAL_NEEDS) + direct = forecast_of(forecast, frame)['prediction'].tolist() + blended = forecast_of(forecast, frame, alpha=0.2)['prediction'].tolist() + + assert direct != pytest.approx(blended) + + +@pytest.mark.parametrize( + ('option', 'value'), + [('alpha', -0.1), ('alpha', 1.5), ('k', 0), ('k', 1.5)], +) +def test_a_retrieval_knob_outside_its_range_is_refused(forecast, option, value): + with pytest.raises(StructuredDataError) as caught: + forecast_of(forecast, history(), **{option: value}) + assert option in str(caught.value) + + +def test_there_is_no_session_to_pin(forecast): + with SDMClient.in_process(forecast) as client: + with pytest.raises( + (UnsupportedRequestError, StructuredDataError) + ) as caught: + client.fit( + Request.forecast(history(), target='flow', horizon=4), + model=KumoForecast(), + ) + assert 'session' in str(caught.value) + + +def test_another_model_is_not_asked_this_question(tabular): + with SDMClient.in_process(tabular) as client: + with pytest.raises(StructuredDataError): + client.predict( + Request.forecast(history(), target='flow', horizon=4), + model=KumoTabular(), + ) + + +def test_a_structured_data_models_without_this_model_still_answers( + sdm, monkeypatch +): + monkeypatch.delattr(sdm.models, 'KumoForecast', raising=False) + + with pytest.raises(StructuredDataError) as caught: + SDMClient.in_process(object()) + assert caught.value.code == 'INVALID_CONFIGURATION' + + +def test_a_model_that_is_not_installed_is_not_offered(sdm, monkeypatch): + monkeypatch.delattr(sdm.models, 'KumoForecast', raising=False) + + with SDMClient.in_process() as client: + assert 'kumo-forecast' not in client.models() diff --git a/scripts/check_wire_payloads.py b/scripts/check_wire_payloads.py index 95358f350..2693e1f47 100755 --- a/scripts/check_wire_payloads.py +++ b/scripts/check_wire_payloads.py @@ -151,7 +151,12 @@ def recorded_bodies(payloads: Path) -> list[tuple[str, dict[str, Any]]]: #: process only. Everything else about such a body is still policed, so an #: envelope that is wrong in any other way still fails here. NOT_IN_THE_CONTRACT = { - 'kumo-anomaly': {'model': 'kumo-anomaly', 'task.kind': 'anomaly_detection'} + 'kumo-anomaly': { + 'model': 'kumo-anomaly', + 'task.kind': 'anomaly_detection', + }, + # `forecasting` is a kind the contract carries; only the id is new. + 'kumo-forecast': {'model': 'kumo-forecast'}, } diff --git a/scripts/snapshot_wire_payloads.py b/scripts/snapshot_wire_payloads.py index a27a07738..24cca85b0 100644 --- a/scripts/snapshot_wire_payloads.py +++ b/scripts/snapshot_wire_payloads.py @@ -20,6 +20,7 @@ import pandas as pd from sdm_client import PredictiveQuery, Request, Schema from sdm_client.adapters.anomaly import AnomalyAdapter +from sdm_client.adapters.forecast import ForecastAdapter from sdm_client.adapters.relational import RelationalAdapter from sdm_client.adapters.tabular import TabularAdapter @@ -138,6 +139,19 @@ def _anomaly_cases() -> dict[str, list[dict[str, Any]]]: return recorded +def _forecast_cases() -> dict[str, list[dict[str, Any]]]: + history = _people()[['user_id', 'age', 'churn']] + adapter = ForecastAdapter() + request = Request.forecast(history, target='age', horizon=3) + recorded: dict[str, list[dict[str, Any]]] = {} + for label, outputs in _output_sets(adapter, request): + recorded[f'forecast/direct-history{label}'] = [ + _normalize(payload) + for payload in adapter.prediction_plan(request, outputs) + ] + return recorded + + def _relational_cases() -> dict[str, list[dict[str, Any]]]: schema = Schema.from_data({'people': _people(), 'orders': _orders()}) request = PredictiveQuery( @@ -165,6 +179,7 @@ def _relational_available() -> bool: def collect() -> dict[str, Any]: recorded: dict[str, Any] = dict(_tabular_cases()) recorded.update(_anomaly_cases()) + recorded.update(_forecast_cases()) if _relational_available(): recorded.update(_relational_cases()) return recorded diff --git a/tests/golden/public_api.json b/tests/golden/public_api.json index 1f777c1bf..c4a9dba9b 100644 --- a/tests/golden/public_api.json +++ b/tests/golden/public_api.json @@ -117,6 +117,7 @@ "FittedModel", "GradientExplanations", "KumoAnomaly", + "KumoForecast", "KumoRelational", "KumoTabular", "MissingExtraError", @@ -212,6 +213,17 @@ "public_methods": {}, "signature": "()" }, + "KumoForecast": { + "bases": [ + "sdm_client.models.Model" + ], + "kind": "class", + "public_attributes": [ + "name" + ], + "public_methods": {}, + "signature": "()" + }, "KumoRelational": { "bases": [ "sdm_client.models.Model" @@ -321,6 +333,7 @@ ], "public_methods": { "anomaly": "(readings: 'pd.DataFrame', *, schema: 'Schema | None' = None, entity_table: 'str' = 'instance', inference: 'Mapping[str, Any] | None' = None) -> 'Request'", + "forecast": "(history: 'pd.DataFrame', *, target: 'str', horizon: 'int', schema: 'Schema | None' = None, entity_table: 'str' = 'instance', inference: 'Mapping[str, Any] | None' = None) -> 'Request'", "materialized": "(*, payloads: 'tuple[dict[str, Any], ...]', schema: 'Schema', query: 'str', indices: 'list[Any]', entity_table: 'str | None' = None, windowed: 'bool' = False, requested_inference: 'Mapping[str, Any] | None' = None) -> 'Request'" }, "signature": "(context: 'pd.DataFrame', predict: 'pd.DataFrame', *, target: 'str', task: 'str', related_tables: 'Mapping[str, pd.DataFrame] | None' = None, schema: 'Schema | None' = None, entity_table: 'str' = 'instance', inference: 'Mapping[str, Any] | None' = None, task_options: 'Mapping[str, Any] | None' = None) -> 'None'" diff --git a/tests/golden/wire_payloads.json b/tests/golden/wire_payloads.json index e1d7d1555..f98066923 100644 --- a/tests/golden/wire_payloads.json +++ b/tests/golden/wire_payloads.json @@ -248,6 +248,138 @@ } } ], + "forecast/direct-history": [ + { + "context": { + "instance_table": { + "columns": [ + "user_id", + "age", + "churn" + ], + "format": "arrays", + "rows": [ + [ + 0, + 20.0, + 0 + ], + [ + 1, + 21.0, + 1 + ], + [ + 2, + 22.0, + 0 + ], + [ + 3, + 23.0, + 1 + ], + [ + 4, + 24.0, + 0 + ], + [ + 5, + 25.0, + 1 + ], + [ + 6, + 26.0, + 0 + ], + [ + 7, + 27.0, + 1 + ], + [ + 8, + 28.0, + 0 + ], + [ + 9, + 29.0, + 1 + ], + [ + 10, + 30.0, + 0 + ], + [ + 11, + 31.0, + 1 + ] + ] + } + }, + "metadata": { + "request_id": "" + }, + "model": "kumo-forecast", + "output": { + "fields": [ + "prediction" + ] + }, + "predict": { + "instance_table": { + "columns": [ + "age" + ], + "format": "arrays", + "rows": [ + [ + null + ], + [ + null + ], + [ + null + ] + ] + } + }, + "schema": { + "instance_table": { + "columns": { + "age": { + "dtype": "float64", + "stype": "numerical" + }, + "churn": { + "dtype": "int64", + "stype": "numerical" + }, + "user_id": { + "dtype": "int64", + "stype": "ID" + } + }, + "primary_key": [ + "user_id" + ] + } + }, + "task": { + "kind": "forecasting", + "target": { + "column_name": "age", + "dtype": "float64" + } + } + } + ], "relational/pql-count-aggregation": [ { "context": { diff --git a/tests/test_release_contract.py b/tests/test_release_contract.py index 8e10c3ef6..ea831ef1b 100644 --- a/tests/test_release_contract.py +++ b/tests/test_release_contract.py @@ -857,12 +857,12 @@ def test_each_request_is_read_as_the_one_it_is( ), (lambda body: body.pop('schema'), "'schema'"), ( - lambda body: body['task'].update(kind='anomaly_detectoin'), - 'anomaly_detectoin', + lambda body: body['task'].update(kind='forecastign'), + 'forecastign', ), ( - lambda body: body.update(model='kumo-anomoly'), - 'kumo-anomoly', + lambda body: body.update(model=body['model'] + 'x'), + 'x', ), ], ids=[ @@ -873,15 +873,19 @@ def test_each_request_is_read_as_the_one_it_is( 'a misspelt model id', ], ) + @pytest.mark.parametrize( + 'case', + ['anomaly/direct-readings', 'forecast/direct-history'], + ids=['anomaly', 'forecast'], + ) def test_a_model_the_contract_has_not_heard_of_is_policed_elsewhere( - self, tmp_path, mutate, said + self, tmp_path, mutate, said, case ): """`kumo-anomaly` is off the contract's model enum on purpose, and that is the only thing forgiven. A body wrong in any other way still fails, or the exemption would be a hole rather than a note.""" recorded = json.loads((GOLDEN / 'wire_payloads.json').read_text()) - body = json.loads(json.dumps(recorded['anomaly/direct-readings'][0])) - assert body['model'] == 'kumo-anomaly' + body = json.loads(json.dumps(recorded[case][0])) mutate(body) written = tmp_path / 'wire_payloads.json' From e136fbde2144c9e08943a33e39f8468fc1db60c5 Mon Sep 17 00:00:00 2001 From: Manush Murali Date: Mon, 2 Nov 2026 21:39:39 -0800 Subject: [PATCH 2/8] Ask for the horizon the contract has, and answer every step of it Four defects, three of which my own fixture hid behind a history that was always long and always had a second column. The horizon was read off how many rows the query had, and the query was the history sliced to length, so a forecast of more steps than had been seen came back short without a word. The contract already carries the horizon as `task.num_forecasts`, so it travels there, one row is scored, and the query is built to the horizon rather than cut from the past. A series with nothing measured alongside it is the ordinary case and it failed: a shape of no columns has nothing to read a length from. `forecast_step` counted from zero. The contract declares it one-based with a minimum of one, so every answer this client built was outside it. And `Request(context=..., predict=..., task='forecasting')` reached this adapter, whose rows to score are the future. It reads nothing about the future, so every value in them was discarded and the answer came from the count alone. That is refused now, naming the constructor that asks it. Co-Authored-By: Claude Opus 5 Signed-off-by: Manush Murali --- .../src/sdm_client/adapters/forecast.py | 13 +++++ .../src/sdm_client/in_process/forecast.py | 51 +++++++++++++------ .../src/sdm_client/request.py | 14 +++-- ..._a_series_is_continued_from_its_history.py | 46 ++++++++++++++++- tests/golden/wire_payloads.json | 7 +-- 5 files changed, 101 insertions(+), 30 deletions(-) diff --git a/packages/structured-data-models-client/src/sdm_client/adapters/forecast.py b/packages/structured-data-models-client/src/sdm_client/adapters/forecast.py index c80561968..bddfff7c8 100644 --- a/packages/structured-data-models-client/src/sdm_client/adapters/forecast.py +++ b/packages/structured-data-models-client/src/sdm_client/adapters/forecast.py @@ -154,6 +154,18 @@ def _envelope( f'the sampled payloads that model reads; ' f'{self.spec.model_id} is asked with Request.forecast(...)' ) + horizon = getattr(request, 'horizon', None) + if horizon is None: + # Built by the constructor that takes a half to score. Those rows + # are the future, and this model reads nothing about the future: + # it would discard every value in them and answer from the count + # alone, which is a different question answered quietly. + raise UnsupportedRequestError( + f'{self.spec.model_id} forecasts from a history and a number ' + f'of steps, and reads nothing about the steps themselves. ' + f'Build the request with ' + f'Request.forecast(history, target=..., horizon=...)' + ) request.schema.check_consistent() table = request.schema[request.entity_table] @@ -203,6 +215,7 @@ def _envelope( 'column_name': target, 'dtype': dtypes[target], }, + 'num_forecasts': horizon, }, 'schema': {'instance_table': instance_schema}, 'context': {'instance_table': encode_table(history, dtypes)}, 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 0ac666577..30e7e53ee 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 @@ -8,12 +8,13 @@ the number of steps all travel on every call, and the model answers from them in one pass, so there is no fitted context to hold and no session over it. -The rows to score carry the series being asked about and nothing in it: one -unknown value per step. The model reads no column of them and takes the -horizon from how many there are. It discards a future covariate with a -warning nobody is obliged to see, so `Request.forecast` gives no way to -supply one; a column the caller cannot pass is one they cannot believe was -used. +There is one row to score, carrying the series being asked about and nothing +in it, and `task.num_forecasts` says how many steps of it are wanted. That is +the contract's own shape for a forecast: one answer per scored row per +horizon, each naming its step from one. The model discards a future covariate +with a warning nobody is obliged to see, so `Request.forecast` gives no way +to supply one; a column the caller cannot pass is one they cannot believe +was used. """ from __future__ import annotations @@ -145,7 +146,14 @@ def series( history = Shape.of(spec, {target: stypes[target]}).tensor( table, 'the history' ) - alongside = Shape.of(spec, measured).tensor(table, 'the history') + # A series with nothing measured alongside it is the ordinary case, + # and an empty shape has no column to read a length from, so the + # history's own length is what says how long it is. + alongside = ( + Shape.of(spec, measured).tensor(table, 'the history') + if measured + else history[..., :0] + ) return history, alongside @staticmethod @@ -165,11 +173,16 @@ def answer( generator: Any = None, ) -> list[PredictionItem]: r"""Continue the series for as many steps as were asked for.""" + import torch + target = payload['task']['target']['column_name'] history, alongside = self.series(payload, target) - horizon = len(payload['predict']['instance_table']['rows']) - if horizon == 0: - return [] + horizon = int(payload['task'].get('num_forecasts') or 0) + if horizon < 1: + raise StructuredDataError( + 'a forecast asks for num_forecasts steps, and this names none', + code='INVALID_REQUEST', + ) options = payload.get('inference') or {} alpha = float(options.get('alpha', _ALPHA)) self._warn_where_retrieval_does_nothing( @@ -178,13 +191,19 @@ def answer( len(payload['context']['instance_table']['rows']), horizon, ) + device = history.device if generator is not None: - history = history.to(generator.device) - alongside = alongside.to(generator.device) + device = generator.device + history = history.to(device) + alongside = alongside.to(device) + # How many rows the query has is the horizon, and it does not depend + # on how long the history is: slicing the history to length capped a + # long forecast at the number of steps already seen. + steps = torch.empty(horizon, 0, device=device) out = model( alongside, history, - alongside[:horizon, ..., :0], + steps, alpha=alpha, k=int(options.get('k', _NEIGHBOURS)), temperature=options.get('temperature', _TEMPERATURE), @@ -195,9 +214,11 @@ def answer( 'the model answered with a malformed output', code='INTERNAL_ERROR', ) + # One row is scored, and one answer per step of it. `forecast_step` + # counts from one, which is what the contract declares it as. return [ - PredictionItem(row_index=step, forecast_step=step, prediction=value) - for step, value in enumerate(forecast.tolist()) + PredictionItem(row_index=0, forecast_step=step, prediction=value) + for step, value in enumerate(forecast.tolist(), start=1) ] @staticmethod diff --git a/packages/structured-data-models-client/src/sdm_client/request.py b/packages/structured-data-models-client/src/sdm_client/request.py index 8a5242b75..a68cf15f0 100644 --- a/packages/structured-data-models-client/src/sdm_client/request.py +++ b/packages/structured-data-models-client/src/sdm_client/request.py @@ -703,18 +703,16 @@ def forecast( dtype=schema[entity_table][target].dtype, table_name=entity_table, ), + options={'num_forecasts': horizon}, ) request.horizon = horizon - # The history is what the model is shown, which is the context. The - # half to score is one row per step, carrying the series being asked - # about and nothing in it: those are the steps whose value is not - # known, which is the question. A table of no columns would say the - # same and is not a table the contract has. + # The history is what the model is shown, which is the context. One + # row is scored, carrying the series being asked about and nothing in + # it, and the horizon travels as `task.num_forecasts`: the contract's + # own shape is one answer per scored row per horizon. request._context = Split(instance_table=history) request._predict = Split( - instance_table=pd.DataFrame( - {target: [None] * horizon}, dtype='object' - ) + instance_table=pd.DataFrame({target: [None]}, dtype='object') ) request.inference = dict(inference or {}) request.requested_inference = dict(inference or {}) diff --git a/packages/structured-data-models-client/tests/test_a_series_is_continued_from_its_history.py b/packages/structured-data-models-client/tests/test_a_series_is_continued_from_its_history.py index 485364d0e..65088d9df 100644 --- a/packages/structured-data-models-client/tests/test_a_series_is_continued_from_its_history.py +++ b/packages/structured-data-models-client/tests/test_a_series_is_continued_from_its_history.py @@ -48,7 +48,10 @@ def test_one_row_per_step_comes_back_in_order(forecast): answer = forecast_of(forecast, history(), horizon=6) assert list(answer.columns) == ['row_index', 'forecast_step', 'prediction'] - assert answer['forecast_step'].tolist() == list(range(6)) + # One row is scored, and the step counts from one, which is what the + # contract declares `forecast_step` as. + assert answer['row_index'].tolist() == [0] * 6 + assert answer['forecast_step'].tolist() == list(range(1, 7)) assert np.isfinite(answer['prediction']).all() @@ -59,6 +62,47 @@ def test_the_horizon_is_how_many_steps_are_asked_for(forecast, horizon): assert len(forecast_of(forecast, history(), horizon=horizon)) == horizon +def test_a_horizon_longer_than_the_history_is_answered_in_full(forecast): + """How many steps were asked for does not depend on how many were seen. + Reading the horizon off the history capped a long forecast at its length. + """ + answer = forecast_of(forecast, history(10), horizon=15) + + assert len(answer) == 15 + assert answer['forecast_step'].tolist() == list(range(1, 16)) + + +def test_a_series_with_nothing_measured_alongside_it_is_forecast(forecast): + """The ordinary case. Reading the covariates as a shape of no columns + left nothing to take a length from, and the request failed.""" + frame = history()[['flow']] + + assert len(forecast_of(forecast, frame, horizon=4)) == 4 + + +def test_the_supervised_constructor_will_not_build_this_question(forecast): + """Its scored half is the future, and this model reads nothing about the + future: every value in those rows would be discarded and the answer come + from the count alone.""" + frame = history() + future = pd.DataFrame({'temp': [0.0] * 4}) + + with SDMClient.in_process(forecast) as client: + with pytest.raises( + (UnsupportedRequestError, StructuredDataError) + ) as caught: + client.predict( + Request( + context=frame, + predict=future, + target='flow', + task='forecasting', + ), + model=KumoForecast(), + ) + assert 'Request.forecast' in str(caught.value) + + def test_the_answer_is_the_one_the_model_gives_when_called_directly( sdm, forecast ): diff --git a/tests/golden/wire_payloads.json b/tests/golden/wire_payloads.json index f98066923..7bab12794 100644 --- a/tests/golden/wire_payloads.json +++ b/tests/golden/wire_payloads.json @@ -338,12 +338,6 @@ ], "format": "arrays", "rows": [ - [ - null - ], - [ - null - ], [ null ] @@ -373,6 +367,7 @@ }, "task": { "kind": "forecasting", + "num_forecasts": 3, "target": { "column_name": "age", "dtype": "float64" From 2020fc82c49bd4e956c53f322de2ec955d55b5d1 Mon Sep 17 00:00:00 2001 From: Manush Murali Date: Mon, 2 Nov 2026 21:46:46 -0800 Subject: [PATCH 3/8] Hold a horizon to the most steps the contract carries `num_forecasts`, `forecast_step` and the number of predictions are each capped at ten thousand, and only the lower bound was enforced, so a longer horizon was accepted here and built an answer no deployment may return. Co-Authored-By: Claude Opus 5 Signed-off-by: Manush Murali --- .../src/sdm_client/in_process/forecast.py | 6 ++++-- .../src/sdm_client/request.py | 12 ++++++++++++ .../test_a_series_is_continued_from_its_history.py | 12 +++++++++++- 3 files changed, 27 insertions(+), 3 deletions(-) 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 30e7e53ee..08d821190 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 @@ -31,6 +31,7 @@ key_columns, stype_of, ) +from sdm_client.request import MAX_FORECAST_STEPS #: Retrieval blends historical windows into the forecast. One is the direct #: forecast alone, which is what the model does when it is not asked. @@ -178,9 +179,10 @@ def answer( target = payload['task']['target']['column_name'] history, alongside = self.series(payload, target) horizon = int(payload['task'].get('num_forecasts') or 0) - if horizon < 1: + if not 1 <= horizon <= MAX_FORECAST_STEPS: raise StructuredDataError( - 'a forecast asks for num_forecasts steps, and this names none', + f'a forecast asks for between 1 and {MAX_FORECAST_STEPS} ' + f'steps as num_forecasts, and this names {horizon or "none"}', code='INVALID_REQUEST', ) options = payload.get('inference') or {} diff --git a/packages/structured-data-models-client/src/sdm_client/request.py b/packages/structured-data-models-client/src/sdm_client/request.py index a68cf15f0..770cd09dd 100644 --- a/packages/structured-data-models-client/src/sdm_client/request.py +++ b/packages/structured-data-models-client/src/sdm_client/request.py @@ -66,6 +66,11 @@ 'anomaly_detection', ) +#: The most forecast steps the contract carries. `task.num_forecasts`, +#: `forecast_step` and the number of predictions are each capped there, so a +#: horizon past it is a request no deployment may answer. +MAX_FORECAST_STEPS = 10_000 + #: The target of a question asked about the whole row rather than one column. #: An anomaly score is joint across the channels it reconstructs, so naming #: one column would promise a score specific to it that the model never @@ -676,6 +681,13 @@ def forecast( f'question with an answer', code='INVALID_REQUEST', ) + if horizon > MAX_FORECAST_STEPS: + raise StructuredDataError( + f'horizon is {horizon}, and the contract carries at most ' + f'{MAX_FORECAST_STEPS} forecast steps, so no deployment may ' + f'answer this', + code='INVALID_REQUEST', + ) if len(history) == 0: raise StructuredDataError( 'history has no rows, so there is no series to continue', diff --git a/packages/structured-data-models-client/tests/test_a_series_is_continued_from_its_history.py b/packages/structured-data-models-client/tests/test_a_series_is_continued_from_its_history.py index 65088d9df..0d0dd3cc5 100644 --- a/packages/structured-data-models-client/tests/test_a_series_is_continued_from_its_history.py +++ b/packages/structured-data-models-client/tests/test_a_series_is_continued_from_its_history.py @@ -143,13 +143,23 @@ def test_a_key_column_is_not_read_as_history(forecast): ) -@pytest.mark.parametrize('horizon', [0, -1, 1.5, True]) +@pytest.mark.parametrize('horizon', [0, -1, 1.5, True, 10_001]) def test_a_horizon_that_is_not_a_count_of_steps_is_refused(forecast, horizon): + """The upper bound is the contract's: `num_forecasts`, `forecast_step` + and the number of predictions are each capped at ten thousand, so a + longer horizon is one no deployment may answer.""" with pytest.raises(StructuredDataError) as caught: Request.forecast(history(), target='flow', horizon=horizon) assert 'horizon' in str(caught.value) +def test_the_longest_horizon_the_contract_carries_is_accepted(forecast): + """The premise of the bound above: ten thousand is inside it.""" + request = Request.forecast(history(), target='flow', horizon=10_000) + + assert request.horizon == 10_000 + + def test_a_history_without_the_series_is_refused(forecast): with pytest.raises(StructuredDataError) as caught: Request.forecast(history(), target='missing', horizon=4) From b914e5e1bc1c8e76e30a6e94de230d24d16119b2 Mon Sep 17 00:00:00 2001 From: Manush Murali Date: Mon, 2 Nov 2026 22:00:31 -0800 Subject: [PATCH 4/8] Keep the series being forecast out of the key it looks like Schema inference reads a column of unique values as the table's key, and a key names a step rather than measuring anything, so it is not history. A series of readings that happen not to repeat is exactly such a column, and naming it as the target then dropped it: the forecast failed on a column the caller had asked about by name. The target is what settles it. Only the named series is rescued; a key beside it is still a key. Co-Authored-By: Claude Opus 5 Signed-off-by: Manush Murali --- .../src/sdm_client/in_process/forecast.py | 7 +++- .../src/sdm_client/request.py | 8 +++++ ..._a_series_is_continued_from_its_history.py | 33 +++++++++++++++++-- 3 files changed, 45 insertions(+), 3 deletions(-) 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 08d821190..a8664e1e7 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 @@ -126,7 +126,12 @@ def series( f'series being forecast', code='INVALID_REQUEST', ) - keys = key_columns(spec) + # A key names the step rather than measuring anything, so it is not + # history. The target is the exception: it was named as the series to + # forecast, and a series of values that happen to be unique is + # inferred as a key, which would drop the very column being asked + # about. + keys = key_columns(spec) - {target} stypes = { name: stype_of(name, spec['columns'][name]) for name in table['columns'] diff --git a/packages/structured-data-models-client/src/sdm_client/request.py b/packages/structured-data-models-client/src/sdm_client/request.py index 770cd09dd..51026b6cc 100644 --- a/packages/structured-data-models-client/src/sdm_client/request.py +++ b/packages/structured-data-models-client/src/sdm_client/request.py @@ -702,6 +702,14 @@ def forecast( ) if schema is None: schema = Schema.from_data({entity_table: history}) + # A series whose values happen to be unique is inferred as the + # table's key, and a key names a row rather than measuring + # anything. The caller named this column as the series to + # forecast, which settles what it is. + table = schema[entity_table] + if target in _as_key_tuple(table.primary_key): + table.primary_key = None + table[target].stype = 'numerical' _check_scored_values_mean_what_the_schema_says( history, schema, entity_table ) diff --git a/packages/structured-data-models-client/tests/test_a_series_is_continued_from_its_history.py b/packages/structured-data-models-client/tests/test_a_series_is_continued_from_its_history.py index 0d0dd3cc5..2f68629b2 100644 --- a/packages/structured-data-models-client/tests/test_a_series_is_continued_from_its_history.py +++ b/packages/structured-data-models-client/tests/test_a_series_is_continued_from_its_history.py @@ -36,10 +36,19 @@ def history(rows: int = 200) -> pd.DataFrame: return pd.DataFrame({'flow': np.sin(step / 9), 'temp': np.cos(step / 7)}) -def forecast_of(model, frame: pd.DataFrame, horizon: int = 6, **inference): +def forecast_of( + model, + frame: pd.DataFrame, + horizon: int = 6, + target: str = 'flow', + **inference, +): with SDMClient.in_process(model) as client: request = Request.forecast( - frame, target='flow', horizon=horizon, inference=inference or None + frame, + target=target, + horizon=horizon, + inference=inference or None, ) return client.predict(request, model=KumoForecast()).to_pandas() @@ -80,6 +89,26 @@ def test_a_series_with_nothing_measured_alongside_it_is_forecast(forecast): assert len(forecast_of(forecast, frame, horizon=4)) == 4 +def test_a_series_whose_values_are_unique_is_still_the_series(forecast): + """Schema inference reads a column of unique values as the table's key, + and a key names a step rather than measuring anything. Naming it as the + target settles what it is, and dropping it left nothing to forecast.""" + frame = pd.DataFrame({'grid': np.arange(40, dtype=float) * 1.5}) + + answer = forecast_of(forecast, frame, horizon=3, target='grid') + + assert len(answer) == 3 + + +def test_a_key_that_is_not_the_target_is_still_a_key(forecast): + """The premise of the test above: only the named series is rescued.""" + frame = history().assign(sensor_id=np.arange(len(history()))) + + assert forecast_of(forecast, frame)['prediction'].tolist() == ( + pytest.approx(forecast_of(forecast, history())['prediction'].tolist()) + ) + + def test_the_supervised_constructor_will_not_build_this_question(forecast): """Its scored half is the future, and this model reads nothing about the future: every value in those rows would be discarded and the answer come From 34024e5128d45af0a738cb98801ddd9beb81cb60 Mon Sep 17 00:00:00 2001 From: Manush Murali Date: Mon, 2 Nov 2026 22:12:27 -0800 Subject: [PATCH 5/8] Let the key fall to whatever is beside the target, not to nothing Taking the target out of the key by clearing the key took every other identifier with it. Two unique columns means either could be read as the key, and with the target chosen and then dropped, the real identifier beside it became history the model forecasts from. The key is now whatever inference would have chosen had the target not been there, which is the question that was being asked all along. Co-Authored-By: Claude Opus 5 Signed-off-by: Manush Murali --- .../src/sdm_client/request.py | 15 ++++++++-- ..._a_series_is_continued_from_its_history.py | 30 +++++++++++++++++++ 2 files changed, 42 insertions(+), 3 deletions(-) diff --git a/packages/structured-data-models-client/src/sdm_client/request.py b/packages/structured-data-models-client/src/sdm_client/request.py index 51026b6cc..e8a10b7b8 100644 --- a/packages/structured-data-models-client/src/sdm_client/request.py +++ b/packages/structured-data-models-client/src/sdm_client/request.py @@ -703,12 +703,21 @@ def forecast( if schema is None: schema = Schema.from_data({entity_table: history}) # A series whose values happen to be unique is inferred as the - # table's key, and a key names a row rather than measuring + # table's key, and a key names a step rather than measuring # anything. The caller named this column as the series to - # forecast, which settles what it is. + # forecast, which settles what it is. The key is then whatever + # inference would have chosen without it: clearing it outright + # left a real identifier beside the target to be read as history. table = schema[entity_table] if target in _as_key_tuple(table.primary_key): - table.primary_key = None + beside = history.drop(columns=[target]) + table.primary_key = ( + Schema.from_data({entity_table: beside})[ + entity_table + ].primary_key + if len(beside.columns) + else None + ) table[target].stype = 'numerical' _check_scored_values_mean_what_the_schema_says( history, schema, entity_table diff --git a/packages/structured-data-models-client/tests/test_a_series_is_continued_from_its_history.py b/packages/structured-data-models-client/tests/test_a_series_is_continued_from_its_history.py index 2f68629b2..8386bff17 100644 --- a/packages/structured-data-models-client/tests/test_a_series_is_continued_from_its_history.py +++ b/packages/structured-data-models-client/tests/test_a_series_is_continued_from_its_history.py @@ -109,6 +109,36 @@ def test_a_key_that_is_not_the_target_is_still_a_key(forecast): ) +@pytest.mark.parametrize( + 'order', [['grid', 'sensor_id'], ['sensor_id', 'grid']] +) +def test_an_identifier_beside_the_target_is_the_key_instead(forecast, order): + """Both columns are unique, so either could be read as the key. Taking + the target out of that choice must leave the other one holding it; + clearing the key outright let an identifier in as history.""" + rows = len(history()) + frame = pd.DataFrame( + { + 'grid': np.arange(rows, dtype=float) * 1.5, + 'sensor_id': np.arange(100, 100 + rows), + } + )[order] + + request = Request.forecast(frame, target='grid', horizon=3) + + assert request.schema['instance'].primary_key == 'sensor_id' + assert request.schema['instance']['grid'].stype == 'numerical' + + +def test_a_series_alone_has_no_key_to_fall_back_to(forecast): + """The other end of the rule above: nothing beside it means no key.""" + frame = pd.DataFrame({'grid': np.arange(40, dtype=float) * 1.5}) + + request = Request.forecast(frame, target='grid', horizon=3) + + assert request.schema['instance'].primary_key is None + + def test_the_supervised_constructor_will_not_build_this_question(forecast): """Its scored half is the future, and this model reads nothing about the future: every value in those rows would be discarded and the answer come From 422d4c4780b95992762c4f9dd04da34e9fc75505 Mon Sep 17 00:00:00 2001 From: Manush Murali Date: Mon, 2 Nov 2026 22:21:16 -0800 Subject: [PATCH 6/8] Hold every table this client writes to the length a table may be The contract caps an `arrays` table at ten thousand rows, and nothing checked it: a history or a run of readings longer than that was encoded and would have been sent. Both of this branch's models could do it, and so could anything added later. The limit belongs to the wire format rather than to a model, so it is checked where a table is written. A deployment may hold to less, which is what a model's own limits are for; this is what none of them may exceed. Co-Authored-By: Claude Opus 5 Signed-off-by: Manush Murali --- .../src/sdm_client/wire/tables.py | 21 +++++++++++++++++++ ..._a_series_is_continued_from_its_history.py | 19 +++++++++++++++++ ...st_an_anomaly_is_scored_without_a_label.py | 15 +++++++++++++ 3 files changed, 55 insertions(+) diff --git a/packages/structured-data-models-client/src/sdm_client/wire/tables.py b/packages/structured-data-models-client/src/sdm_client/wire/tables.py index f604a496e..473269455 100644 --- a/packages/structured-data-models-client/src/sdm_client/wire/tables.py +++ b/packages/structured-data-models-client/src/sdm_client/wire/tables.py @@ -10,8 +10,15 @@ import pandas as pd +from sdm_client.errors import StructuredDataError from sdm_client.wire.dtypes import serialize_column +#: The most rows the contract lets an ``arrays`` table carry +#: (``ArraysTableData.rows.maxItems``). A deployment may hold to less, which +#: is what a model's own limits are for; this is what no deployment may +#: exceed, so it is checked wherever a table is written. +MAX_TABLE_ROWS = 10_000 + def encode_table(frame: pd.DataFrame, dtypes: dict[str, str]) -> dict[str, Any]: r"""Encode ``frame`` as an ``arrays`` table. @@ -31,11 +38,25 @@ def encode_table(frame: pd.DataFrame, dtypes: dict[str, str]) -> dict[str, Any]: table is a list of empty rows rather than an empty table. The two mean different things to the server. + A table longer than the contract carries is refused here rather than by + each model in turn: the limit belongs to the wire format, so every table + this client writes is held to it whichever model the request is for. + Args: frame: The rows to encode. dtypes: Wire dtype per column name. Must cover every column of ``frame``. + + Raises: + StructuredDataError: If ``frame`` has more rows than the contract + allows a table to carry. """ + if len(frame) > MAX_TABLE_ROWS: + raise StructuredDataError( + f'a table carries at most {MAX_TABLE_ROWS:,} rows and this has ' + f'{len(frame):,}; no deployment may be sent it', + code='UNSUPPORTED_SHAPE', + ) columns = list(frame.columns) if not columns: return { diff --git a/packages/structured-data-models-client/tests/test_a_series_is_continued_from_its_history.py b/packages/structured-data-models-client/tests/test_a_series_is_continued_from_its_history.py index 8386bff17..8058ba109 100644 --- a/packages/structured-data-models-client/tests/test_a_series_is_continued_from_its_history.py +++ b/packages/structured-data-models-client/tests/test_a_series_is_continued_from_its_history.py @@ -22,6 +22,7 @@ StructuredDataError, UnsupportedRequestError, ) +from sdm_client.adapters.forecast import ForecastAdapter from sdm_client.core.warnings import SDMWarning pytestmark = pytest.mark.filterwarnings('ignore') @@ -139,6 +140,24 @@ def test_a_series_alone_has_no_key_to_fall_back_to(forecast): assert request.schema['instance'].primary_key is None +@pytest.mark.parametrize(('rows', 'refused'), [(10_000, False), (10_001, True)]) +def test_a_history_longer_than_a_table_may_be_is_refused( + forecast, rows, refused +): + """The contract caps a table at ten thousand rows, so a longer history + builds a payload no deployment may be sent.""" + frame = pd.DataFrame({'flow': np.sin(np.arange(rows) / 9)}) + request = Request.forecast(frame, target='flow', horizon=2) + plan = ForecastAdapter().prediction_plan(request, ('prediction',)) + + if not refused: + assert next(plan)['context']['instance_table']['rows'] + return + with pytest.raises(StructuredDataError) as caught: + next(plan) + assert '10,000' in str(caught.value) + + def test_the_supervised_constructor_will_not_build_this_question(forecast): """Its scored half is the future, and this model reads nothing about the future: every value in those rows would be discarded and the answer come diff --git a/packages/structured-data-models-client/tests/test_an_anomaly_is_scored_without_a_label.py b/packages/structured-data-models-client/tests/test_an_anomaly_is_scored_without_a_label.py index 33166774a..7b223b31f 100644 --- a/packages/structured-data-models-client/tests/test_an_anomaly_is_scored_without_a_label.py +++ b/packages/structured-data-models-client/tests/test_an_anomaly_is_scored_without_a_label.py @@ -313,6 +313,21 @@ def test_a_model_that_is_not_installed_is_not_offered(sdm, monkeypatch): assert 'kumo-anomaly' not in client.models() +def test_readings_longer_than_a_table_may_be_are_refused(anomaly): + """The contract caps a table at ten thousand rows, and these readings + travel as one.""" + from sdm_client.adapters.anomaly import AnomalyAdapter + + frame = pd.DataFrame({'flow': np.sin(np.arange(10_001) / 9)}) + plan = AnomalyAdapter().prediction_plan( + Request.anomaly(frame), ('prediction',) + ) + + with pytest.raises(StructuredDataError) as caught: + next(plan) + assert '10,000' in str(caught.value) + + def test_another_model_is_not_asked_this_question(tabular): """`anomaly_detection` is a task only one model here answers.""" with SDMClient.in_process(tabular) as client: From 23c899d070c014368cdc5f46463e6a4a80a6d355 Mon Sep 17 00:00:00 2001 From: Manush Murali Date: Tue, 3 Nov 2026 13:56:40 -0800 Subject: [PATCH 7/8] Say it once, where the reader is already looking The reasoning sat in comments beside the code it was about, where a reader reaches it only by reading the body. It belongs in the docstring, which is what a reader opens first and what the documentation carries, so each one is folded into the docstring of the thing it explains, or into the documented constant where there is no docstring to fold it into. Nothing is dropped. Co-Authored-By: Claude Opus 5 Signed-off-by: Manush Murali --- .../src/sdm_client/adapters/forecast.py | 12 ++++--- .../src/sdm_client/in_process/forecast.py | 35 +++++++++++-------- .../src/sdm_client/models.py | 7 ++-- .../src/sdm_client/request.py | 23 ++++++------ ..._a_series_is_continued_from_its_history.py | 4 +-- scripts/check_wire_payloads.py | 5 +-- 6 files changed, 50 insertions(+), 36 deletions(-) diff --git a/packages/structured-data-models-client/src/sdm_client/adapters/forecast.py b/packages/structured-data-models-client/src/sdm_client/adapters/forecast.py index bddfff7c8..985b7c969 100644 --- a/packages/structured-data-models-client/src/sdm_client/adapters/forecast.py +++ b/packages/structured-data-models-client/src/sdm_client/adapters/forecast.py @@ -148,6 +148,14 @@ def close(self) -> None: def _envelope( self, request: Request, outputs: tuple[str, ...] ) -> dict[str, Any]: + r"""The request on the wire, refused where it carries no horizon. + + A request without one was built by the constructor that takes a half + to score. Those rows are the future, and this model reads nothing + about the future: it would discard every value in them and answer + from the count alone, which is a different question answered + quietly. + """ if request.payloads is not None: raise UnsupportedRequestError( f'this request was gathered for another model and carries ' @@ -156,10 +164,6 @@ def _envelope( ) horizon = getattr(request, 'horizon', None) if horizon is None: - # Built by the constructor that takes a half to score. Those rows - # are the future, and this model reads nothing about the future: - # it would discard every value in them and answer from the count - # alone, which is a different question answered quietly. raise UnsupportedRequestError( f'{self.spec.model_id} forecasts from a history and a number ' f'of steps, and reads nothing about the steps themselves. ' 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 a8664e1e7..524d34560 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 @@ -116,7 +116,17 @@ def series( self, payload: Mapping[str, Any], target: str ) -> tuple[Any, Any]: r"""The history, split into the series to continue and what else was - measured alongside it.""" + measured alongside it. + + A key names the step rather than measuring anything, so it is not + history. The series being forecast is the exception: one whose values + happen to be unique is inferred as a key, and dropping it would drop + the very column being asked about. + + Nothing measured alongside it is the ordinary case. An empty shape + has no column to read a length from, so the history's own length is + what says how long it is. + """ spec = payload['schema']['instance_table'] table = payload['context']['instance_table'] check_columns(table, spec, 'the history') @@ -126,11 +136,6 @@ def series( f'series being forecast', code='INVALID_REQUEST', ) - # A key names the step rather than measuring anything, so it is not - # history. The target is the exception: it was named as the series to - # forecast, and a series of values that happen to be unique is - # inferred as a key, which would drop the very column being asked - # about. keys = key_columns(spec) - {target} stypes = { name: stype_of(name, spec['columns'][name]) @@ -152,9 +157,6 @@ def series( history = Shape.of(spec, {target: stypes[target]}).tensor( table, 'the history' ) - # A series with nothing measured alongside it is the ordinary case, - # and an empty shape has no column to read a length from, so the - # history's own length is what says how long it is. alongside = ( Shape.of(spec, measured).tensor(table, 'the history') if measured @@ -178,7 +180,15 @@ def answer( fields: Sequence[str], generator: Any = None, ) -> list[PredictionItem]: - r"""Continue the series for as many steps as were asked for.""" + r"""Continue the series for as many steps as were asked for. + + How many rows the query carries is the horizon, and that does not + depend on how long the history is: slicing the history to length + capped a long forecast at the number of steps already seen. + + One row is scored, and one answer per step of it, with + ``forecast_step`` counting from one as the contract declares it. + """ import torch target = payload['task']['target']['column_name'] @@ -203,9 +213,6 @@ def answer( device = generator.device history = history.to(device) alongside = alongside.to(device) - # How many rows the query has is the horizon, and it does not depend - # on how long the history is: slicing the history to length capped a - # long forecast at the number of steps already seen. steps = torch.empty(horizon, 0, device=device) out = model( alongside, @@ -221,8 +228,6 @@ def answer( 'the model answered with a malformed output', code='INTERNAL_ERROR', ) - # One row is scored, and one answer per step of it. `forecast_step` - # counts from one, which is what the contract declares it as. return [ PredictionItem(row_index=0, forecast_step=step, prediction=value) for step, value in enumerate(forecast.tolist(), start=1) 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 e5d308f71..fd45023f0 100644 --- a/packages/structured-data-models-client/src/sdm_client/models.py +++ b/packages/structured-data-models-client/src/sdm_client/models.py @@ -187,14 +187,17 @@ TFM_MODEL_KUMO_FORECAST = 'kumo-forecast' +#: The model that continues a series beyond its history. +#: +#: It holds no session: every call carries the history, the horizon and +#: nothing held over, because the model fits no context and there is none to +#: pin. KUMO_FORECAST = ModelSpec( model_id=TFM_MODEL_KUMO_FORECAST, profile=TIMESERIES, runtime=RuntimeContract( tasks=frozenset({'forecasting'}), outputs=frozenset({'prediction'}), - # Every call carries the history, the horizon and nothing held over: - # the model fits no context, so there is none to pin. sessions=False, inference_options=frozenset({'alpha', 'k', 'temperature'}), ), diff --git a/packages/structured-data-models-client/src/sdm_client/request.py b/packages/structured-data-models-client/src/sdm_client/request.py index e8a10b7b8..8a8fed64f 100644 --- a/packages/structured-data-models-client/src/sdm_client/request.py +++ b/packages/structured-data-models-client/src/sdm_client/request.py @@ -649,7 +649,18 @@ def forecast( There are no rows to score: the question is about steps that have not been measured, so the horizon is a count rather than a frame, and nothing known about the future travels, because the model reads - nothing about it. + nothing about it. The history is what the model is shown, so it is + the context; one row is scored, carrying the series being asked + about and nothing in it, and the horizon travels as + ``task.num_forecasts``, because the contract's own shape is one + answer per scored row per horizon. + + A series whose values happen to be unique is inferred as the table's + key, and a key names a step rather than measuring anything. Naming + the column as the series to forecast settles what it is, and the key + falls to whatever inference would have chosen without it: cleared + outright, a real identifier beside it was left to be read as + history. Args: history: The series so far, one row per step. Must carry @@ -702,12 +713,6 @@ def forecast( ) if schema is None: schema = Schema.from_data({entity_table: history}) - # A series whose values happen to be unique is inferred as the - # table's key, and a key names a step rather than measuring - # anything. The caller named this column as the series to - # forecast, which settles what it is. The key is then whatever - # inference would have chosen without it: clearing it outright - # left a real identifier beside the target to be read as history. table = schema[entity_table] if target in _as_key_tuple(table.primary_key): beside = history.drop(columns=[target]) @@ -735,10 +740,6 @@ def forecast( options={'num_forecasts': horizon}, ) request.horizon = horizon - # The history is what the model is shown, which is the context. One - # row is scored, carrying the series being asked about and nothing in - # it, and the horizon travels as `task.num_forecasts`: the contract's - # own shape is one answer per scored row per horizon. request._context = Split(instance_table=history) request._predict = Split( instance_table=pd.DataFrame({target: [None]}, dtype='object') diff --git a/packages/structured-data-models-client/tests/test_a_series_is_continued_from_its_history.py b/packages/structured-data-models-client/tests/test_a_series_is_continued_from_its_history.py index 8058ba109..12cd0aaaa 100644 --- a/packages/structured-data-models-client/tests/test_a_series_is_continued_from_its_history.py +++ b/packages/structured-data-models-client/tests/test_a_series_is_continued_from_its_history.py @@ -55,11 +55,11 @@ def forecast_of( def test_one_row_per_step_comes_back_in_order(forecast): + """One row is scored, and the step counts from one, which is what the + contract declares `forecast_step` as.""" answer = forecast_of(forecast, history(), horizon=6) assert list(answer.columns) == ['row_index', 'forecast_step', 'prediction'] - # One row is scored, and the step counts from one, which is what the - # contract declares `forecast_step` as. assert answer['row_index'].tolist() == [0] * 6 assert answer['forecast_step'].tolist() == list(range(1, 7)) assert np.isfinite(answer['prediction']).all() diff --git a/scripts/check_wire_payloads.py b/scripts/check_wire_payloads.py index 2693e1f47..a4c0dfefb 100755 --- a/scripts/check_wire_payloads.py +++ b/scripts/check_wire_payloads.py @@ -149,13 +149,14 @@ def recorded_bodies(payloads: Path) -> list[tuple[str, dict[str, Any]]]: #: name, and the fields those enums reject them in. The contract describes #: what a deployment serves, and no deployment serves these: they run in this #: process only. Everything else about such a body is still policed, so an -#: envelope that is wrong in any other way still fails here. +#: envelope that is wrong in any other way still fails here. `forecasting` +#: is absent from this for a reason: it is a kind the contract carries, and +#: only the model id of one is new. NOT_IN_THE_CONTRACT = { 'kumo-anomaly': { 'model': 'kumo-anomaly', 'task.kind': 'anomaly_detection', }, - # `forecasting` is a kind the contract carries; only the id is new. 'kumo-forecast': {'model': 'kumo-forecast'}, } From 17c05c380400cd05c92f1375b7a6ddb42088a928 Mon Sep 17 00:00:00 2001 From: Manush Murali Date: Wed, 4 Nov 2026 08:41:01 -0800 Subject: [PATCH 8/8] Hold a replacement key to what inference allows Forecasting a column that schema inference read as the table's key re-infers a key from the columns beside it. That replacement was assigned through the checked setter, which refuses a key with a null in it, while inference tolerates one and warns. The replacement is inferred too, so the same history was forecastable or refused depending only on which column came first. Every route from an inferred key to an adopted one now goes through one helper, so a guess is never held to the standard of a caller's assertion. Co-Authored-By: Claude Opus 5 Signed-off-by: Manush Murali --- .../src/sdm_client/request.py | 15 +++--- .../src/sdm_client/schema.py | 53 ++++++++++++++----- ..._a_series_is_continued_from_its_history.py | 24 +++++++++ 3 files changed, 71 insertions(+), 21 deletions(-) diff --git a/packages/structured-data-models-client/src/sdm_client/request.py b/packages/structured-data-models-client/src/sdm_client/request.py index 8a8fed64f..02b3097ea 100644 --- a/packages/structured-data-models-client/src/sdm_client/request.py +++ b/packages/structured-data-models-client/src/sdm_client/request.py @@ -43,7 +43,12 @@ from sdm_client.core.warnings import SDMWarning, caller_stacklevel from sdm_client.decompose import Decomposition from sdm_client.errors import StructuredDataError, UnsupportedRequestError -from sdm_client.schema import Schema, supports_dtype +from sdm_client.schema import ( + Schema, + _adopt_inferred_key, + _inferred_key_of, + supports_dtype, +) from sdm_client.wire import UNTYPED, infer_tfm_dtype, is_container from sdm_client.wire.keys import key_dtypes, keys_from_a_frame @@ -716,13 +721,7 @@ def forecast( table = schema[entity_table] if target in _as_key_tuple(table.primary_key): beside = history.drop(columns=[target]) - table.primary_key = ( - Schema.from_data({entity_table: beside})[ - entity_table - ].primary_key - if len(beside.columns) - else None - ) + _adopt_inferred_key(table, _inferred_key_of(beside), beside) table[target].stype = 'numerical' _check_scored_values_mean_what_the_schema_says( history, schema, entity_table diff --git a/packages/structured-data-models-client/src/sdm_client/schema.py b/packages/structured-data-models-client/src/sdm_client/schema.py index 8d26f07b0..94b8753d8 100644 --- a/packages/structured-data-models-client/src/sdm_client/schema.py +++ b/packages/structured-data-models-client/src/sdm_client/schema.py @@ -1949,25 +1949,52 @@ def _infer_table_and_time_column( column: _column(frame[column], column) for column in frame.columns } table = Table(name=name, data=frame, columns=columns) - inferred = _infer_primary_key(frame, columns) + _adopt_inferred_key(table, _infer_primary_key(frame, columns), frame) + return table, _infer_time_column(table, frame) + + +def _inferred_key_of(frame: pd.DataFrame) -> str | None: + r"""The key inference would nominate for ``frame``, and nothing else. + + For a caller that has a frame and wants only the guess, without building a + schema around it and reading back what that schema decided. Building one + would also say everything that building a schema says, including a warning + about a key this caller is only asking after. + """ + return _infer_primary_key( + frame, {column: _column(frame[column], column) for column in frame} + ) + + +def _adopt_inferred_key( + table: Table, inferred: str | None, frame: pd.DataFrame +) -> None: + r"""Give ``table`` a key that inference nominated, not one a caller stated. + + A key with a null in it is tolerated here and refused on assignment, the + same way a nearly unique column is: inference is a guess and a caller's key + is an assertion. Refusing would break `Schema.from_data` on frames that + worked before, including any relationship pointing at this table, but the + engine drops those rows without a word, so the guess is said out loud. + + Every route from a guess to a key comes through here, so that a frame + inference accepts is not refused further on for having been inferred a + second time, with a column order the only thing deciding which it was. + + Otherwise the key is assigned. Assigning it is what marks its column, + counts what the uniqueness threshold tolerated and says so; doing any of it + a second time here would report the same duplicate twice, from inside this + module. + """ if inferred is not None and frame[inferred].isna().any(): - # Tolerated here and refused on assignment, the same way a nearly - # unique column is: inference is a guess and a caller's key is an - # assertion. Refusing would break `Schema.from_data` on frames that - # worked before, including any relationship pointing at this table, - # but the engine drops these rows without a word, so the guess is - # said out loud. _warn_a_key_has_no_value( - name, inferred, int(frame[inferred].isna().sum()) + table.name, inferred, int(frame[inferred].isna().sum()) ) object.__setattr__(table, 'primary_key', inferred) table._adopt_key(inferred) - return table, _infer_time_column(table, frame) - # Assigning the key is what marks its column, counts what the uniqueness - # threshold tolerated and says so; doing any of it a second time here would - # report the same duplicate twice, from inside this module. + table._re_derive_key_columns() + return table.primary_key = inferred - return table, _infer_time_column(table, frame) def _copy_table(table: _T) -> _T: diff --git a/packages/structured-data-models-client/tests/test_a_series_is_continued_from_its_history.py b/packages/structured-data-models-client/tests/test_a_series_is_continued_from_its_history.py index 12cd0aaaa..a490a6cd2 100644 --- a/packages/structured-data-models-client/tests/test_a_series_is_continued_from_its_history.py +++ b/packages/structured-data-models-client/tests/test_a_series_is_continued_from_its_history.py @@ -131,6 +131,30 @@ def test_an_identifier_beside_the_target_is_the_key_instead(forecast, order): assert request.schema['instance']['grid'].stype == 'numerical' +@pytest.mark.parametrize( + 'order', [['grid', 'sensor_id'], ['sensor_id', 'grid']] +) +def test_the_key_that_replaces_the_target_is_held_to_what_inference_allows( + forecast, order +): + """Inference tolerates a key with a null in it, warning instead of + refusing. The replacement key is inferred too, so refusing it made the + same frame forecastable or not depending on which column came first.""" + rows = len(history()) + frame = pd.DataFrame( + { + 'grid': np.arange(rows, dtype=float) * 1.5, + 'sensor_id': [None, *range(101, 100 + rows)], + } + )[order] + + with pytest.warns(SDMWarning, match='have no value'): + request = Request.forecast(frame, target='grid', horizon=3) + + assert request.schema['instance'].primary_key == 'sensor_id' + assert request.schema['instance']['grid'].stype == 'numerical' + + def test_a_series_alone_has_no_key_to_fall_back_to(forecast): """The other end of the rule above: nothing beside it means no key.""" frame = pd.DataFrame({'grid': np.arange(40, dtype=float) * 1.5})