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

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
16 changes: 15 additions & 1 deletion .github/workflows/ci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -166,9 +166,23 @@ jobs:
# index, since the default one resolves to a far larger CUDA build.
- run: |
pip install torch --index-url https://download.pytorch.org/whl/cpu
pip install -e './packages/structured-data-models-client[test,in-process]'
pip install -e './packages/structured-data-models-client[test]'
pip install "structured-data-models @ git+https://github.com/NVIDIA/structured-data-models.git@${SDM_REF}"
python -m pytest packages/structured-data-models-client/tests -q \
-m 'not live_nim and not live_warehouse'
env:
# The time-series models are on structured-data-models' main and in
# no release of it, so the `in-process` extra cannot reach them: its
# range names published versions, and main's own version string is
# below the floor of that range. This commit is installed instead,
# which is why the extra is not asked for here.
#
# It is pinned here rather than in the package's metadata on
# purpose. A direct URL in `optional-dependencies` is rejected at
# upload, so declaring it there would trade a test that runs for a
# release that cannot be published. Move the extra's range forward
# and delete this once a release carries the models.
SDM_REF: b5c36413dd30bcb93b39bfed2afdccf3e509781d
# And the root suite, which holds the relational wire snapshots. They
# only exercise anything with an engine installed, so running them in
# the test job would prove nothing.
Expand Down
6 changes: 5 additions & 1 deletion packages/structured-data-models-client/pyproject.toml
Original file line number Diff line number Diff line change
Expand Up @@ -78,7 +78,11 @@ s3 = ["structured-data-models-connectors[s3]==1.0.0"]
# model rather than a backend to read, so `all` does not carry it; ask for it by
# name.
databricks-serving = ["databricks-sdk>=0.68.0,<1.0"]
# Running the models in this process rather than reaching a NIM. Like
# Running the models in this process rather than reaching a NIM. The range
# below names published releases, and none of them carries the time-series
# models, so `KumoAnomaly` needs that package installed from its own main
# until a release does. Widen this and drop the pin in `ci.yml` then.
# Like
# `databricks-serving` it is a way to reach a model, and it brings PyTorch, so
# `all` does not carry it. structured-data-models needs Python 3.11; on 3.10
# the extra installs nothing, and `SDMClient.in_process()` says why. The marker
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -35,7 +35,12 @@
Explanations,
GradientExplanations,
)
from sdm_client.models import KumoRelational, KumoTabular, Model
from sdm_client.models import (
KumoAnomaly,
KumoRelational,
KumoTabular,
Model,
)
from sdm_client.query import PredictiveQuery
from sdm_client.request import Request, Split, Target, Task
from sdm_client.result import PredictionResult
Expand All @@ -54,6 +59,7 @@
'Explanations',
'FittedModel',
'GradientExplanations',
'KumoAnomaly',
'KumoRelational',
'KumoTabular',
'MissingExtraError',
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,7 @@

"""Per-model adapters. One module per model."""

from sdm_client.adapters.anomaly import AnomalyAdapter
from sdm_client.adapters.tabular import TabularAdapter

__all__ = ['TabularAdapter']
__all__ = ['AnomalyAdapter', 'TabularAdapter']
Original file line number Diff line number Diff line change
@@ -0,0 +1,224 @@
# SPDX-FileCopyrightText: Copyright (c) 2026, NVIDIA CORPORATION & AFFILIATES.
# All rights reserved.
# SPDX-License-Identifier: Apache-2.0

r"""Shaping a request for ``kumo-anomaly``.

Short, because this model is asked the least of any here. There is no target
column to type, no context to agree with the rows being scored, and no session
to pin, so what is left is the schema the readings are written against.

The envelope still carries an empty ``context``. The contract requires that
section, and a model with nothing to learn from has a context with no rows
rather than no context, which is a thing the envelope can say.
"""

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_OF,
coherent_stype,
named_entities,
)
from sdm_client.base import ModelSpec
from sdm_client.errors import StructuredDataError, UnsupportedRequestError
from sdm_client.models import KUMO_ANOMALY
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', 'probabilities')


def _request_id() -> str:
return f'sdm-{uuid.uuid4().hex[:12]}'


class AnomalyAdapter:
r"""Shapes and reads ``kumo-anomaly`` requests."""

spec: ModelSpec = KUMO_ANOMALY

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. The score for a row depends on the rows around it,
so splitting a series into batches would change the answer."""
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 is shown no labelled '
f'rows, so there is no fitted context to pin and score against. '
f'Call predict(), which sends the readings 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:
return PredictionResult(
model=model,
request_id=request_id,
items=named_entities(items, payload),
metadata=dict(metadata or {}),
outputs=outputs,
)

def explain_error(
self, error: Exception, payload: dict[str, Any]
) -> Exception:
r"""Nothing to add: a refusal here is about the readings, 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.anomaly(...)'
)
request.schema.check_consistent()

table = request.schema[request.entity_table]
readings = request.predict.instance_table

dtypes = {
name: (UNTYPED if column.untyped else column.dtype)
for name, column in table.columns.items()
}
for name in readings.columns:
if name in dtypes:
dtypes[name] = widen_tfm_dtype(
(dtypes[name], infer_tfm_dtype(readings[name]))
)
dtypes = {name: dtype or 'string' for name, dtype in dtypes.items()}

missing = [name for name in readings.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(table[name], dtypes[name]),
}
for name in readings.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': request.task.target.column_name,
'dtype': request.task.target.dtype,
},
},
'schema': {'instance_table': instance_schema},
'context': {
'instance_table': encode_table(readings.iloc[:0], dtypes)
},
'predict': {'instance_table': encode_table(readings, dtypes)},
'output': {'fields': list(outputs)},
'metadata': {'request_id': _request_id()},
}
if request.inference:
envelope['inference'] = typed_inference(
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)
Loading
Loading