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..985b7c969 --- /dev/null +++ b/packages/structured-data-models-client/src/sdm_client/adapters/forecast.py @@ -0,0 +1,238 @@ +# 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]: + 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 ' + 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: + 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] + 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], + }, + 'num_forecasts': horizon, + }, + '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..524d34560 --- /dev/null +++ b/packages/structured-data-models-client/src/sdm_client/in_process/forecast.py @@ -0,0 +1,274 @@ +# 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. + +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 + +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, +) +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. +_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. + + 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') + 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) - {target} + 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') + if measured + else history[..., :0] + ) + 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. + + 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'] + history, alongside = self.series(payload, target) + horizon = int(payload['task'].get('num_forecasts') or 0) + if not 1 <= horizon <= MAX_FORECAST_STEPS: + raise StructuredDataError( + 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 {} + alpha = float(options.get('alpha', _ALPHA)) + self._warn_where_retrieval_does_nothing( + model, + alpha, + len(payload['context']['instance_table']['rows']), + horizon, + ) + device = history.device + if generator is not None: + device = generator.device + history = history.to(device) + alongside = alongside.to(device) + steps = torch.empty(horizon, 0, device=device) + out = model( + alongside, + history, + steps, + 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=0, forecast_step=step, prediction=value) + for step, value in enumerate(forecast.tolist(), start=1) + ] + + @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..fd45023f0 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,25 @@ ) +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'}), + sessions=False, + inference_options=frozenset({'alpha', 'k', 'temperature'}), + ), +) + + class Model: r"""Base for the model handles. Not useful on its own.""" @@ -254,11 +273,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..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 @@ -66,6 +71,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 @@ -627,6 +637,117 @@ 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. 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 + ``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 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', + 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}) + table = schema[entity_table] + if target in _as_key_tuple(table.primary_key): + beside = history.drop(columns=[target]) + _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 + ) + + 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, + ), + options={'num_forecasts': horizon}, + ) + request.horizon = horizon + request._context = Split(instance_table=history) + request._predict = Split( + instance_table=pd.DataFrame({target: [None]}, 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/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/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/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..a490a6cd2 --- /dev/null +++ b/packages/structured-data-models-client/tests/test_a_series_is_continued_from_its_history.py @@ -0,0 +1,357 @@ +# 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.adapters.forecast import ForecastAdapter +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, + target: str = 'flow', + **inference, +): + with SDMClient.in_process(model) as client: + request = Request.forecast( + frame, + target=target, + 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): + """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'] + assert answer['row_index'].tolist() == [0] * 6 + assert answer['forecast_step'].tolist() == list(range(1, 7)) + 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_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_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()) + ) + + +@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' + + +@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}) + + request = Request.forecast(frame, target='grid', horizon=3) + + 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 + 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 +): + """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, 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) + 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/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: diff --git a/scripts/check_wire_payloads.py b/scripts/check_wire_payloads.py index 95358f350..a4c0dfefb 100755 --- a/scripts/check_wire_payloads.py +++ b/scripts/check_wire_payloads.py @@ -149,9 +149,15 @@ 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'} + 'kumo-anomaly': { + 'model': 'kumo-anomaly', + 'task.kind': 'anomaly_detection', + }, + '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..7bab12794 100644 --- a/tests/golden/wire_payloads.json +++ b/tests/golden/wire_payloads.json @@ -248,6 +248,133 @@ } } ], + "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 + ] + ] + } + }, + "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", + "num_forecasts": 3, + "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'