structured-data-models-client 1.0.0__py3-none-any.whl

sdm_client/core/warnings.py

@@ -0,0 +1,51 @@
+# SPDX-FileCopyrightText: Copyright (c) 2026, NVIDIA CORPORATION & AFFILIATES.
+# All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+
+r"""Where a warning should say it came from, and what kind it is."""
+
+from __future__ import annotations
+
+import sys
+
+
+class SDMWarning(UserWarning):
+    r"""What this package says when it will answer, but not as asked.
+
+    Every warning raised from here carries it. A caller who wants none of
+    them, or wants all of them to stop the run, can say so once:
+
+    .. code-block:: python
+
+        warnings.filterwarnings('ignore', category=SDMWarning)
+        warnings.filterwarnings('error', category=SDMWarning)
+
+    It derives from `UserWarning`, which is what these were before it existed,
+    so a filter written against that keeps catching them.
+    """
+
+
+_PACKAGE = __name__.split('.')[0]
+
+
+def caller_stacklevel() -> int:
+    r"""How far up to point a warning so it lands on the caller's line.
+
+    A fixed number is right for one route into a warning and blames this
+    package on every other. Inference reaches the same setter through
+    `Schema.from_data`, and `PredictiveQuery` reaches `Schema.from_data`
+    through itself, so the same message is two, three or four frames from the
+    line the reader wants to see.
+
+    Counting every frame that belongs to this package answers for all of them,
+    and keeps answering when a route gains a layer.
+    """
+    depth = 1
+    frame = sys._getframe(1)
+    while frame is not None:
+        module = frame.f_globals.get('__name__', '')
+        if module != _PACKAGE and not module.startswith(f'{_PACKAGE}.'):
+            break
+        depth += 1
+        frame = frame.f_back
+    return depth

sdm_client/decompose.py

@@ -0,0 +1,421 @@
+# SPDX-FileCopyrightText: Copyright (c) 2026, NVIDIA CORPORATION & AFFILIATES.
+# All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+
+r"""Asking a question the model does not take, in questions it does.
+
+Two kinds of question have no task on the endpoint. A ranking asks which rows
+of one table an entity will reach in a window; a forecast asks what a window
+holds at each of several steps ahead. The models serve classification and
+regression, and nothing else, so a request for either comes back refused.
+
+Both are the same question asked repeatedly, though, and the repetition is
+what the endpoint does serve:
+
+* a ranking over candidates is, per candidate, *will this entity reach this
+  one?* This is a binary question whose probability orders the candidates.
+* a forecast over steps is, per step, *what does this window hold?* This is the
+  question already being asked, with its window moved along.
+
+Each part needs its own context, because the labels differ: what was true in
+the second window is not what was true in the first, and whether an entity
+reached *this* candidate is not whether it reached any. So the decomposition
+happens where contexts are gathered rather than where envelopes are built,
+and what comes back is merged into the one answer that was asked for.
+
+The cost is a call per part, which for a ranking is a call per candidate.
+That is the whole reason candidates must be named rather than assumed.
+"""
+
+from __future__ import annotations
+
+import contextlib
+import math
+from collections.abc import Mapping
+from dataclasses import dataclass
+from decimal import Decimal
+from typing import TYPE_CHECKING, Any
+
+import pandas as pd
+
+from sdm_client.errors import StructuredDataError
+from sdm_client.wire.dtypes import _decimal_dtype, _is_missing
+
+if TYPE_CHECKING:
+    from predictive_query import ValidatedPredictiveQuery
+
+    from sdm_client.schema import Schema
+
+#: More parts than this and the fan-out is the cost of the call, not a detail
+#: of it. A caller who means it can raise it; nobody discovers it by accident.
+MOST_PARTS = 200
+
+RANKING = 'ranking'
+FORECAST = 'forecast'
+
+
+@dataclass(frozen=True)
+class Decomposition:
+    r"""The questions one question was rewritten as, and what each is about.
+
+    Carried on the request rather than re-derived from its text: a query
+    naming a table ``rank_events`` is not a ranking, and a candidate read back
+    out of the text it was written into is a string where a key was given.
+    """
+
+    kind: str
+    parts: tuple[tuple[str, Any], ...]
+    top: int | None = None
+
+
+def parts_of(
+    query: ValidatedPredictiveQuery,
+    text: str,
+    candidates: list[Any] | None,
+    options: Mapping[str, Any],
+    schema: Schema | None = None,
+) -> Decomposition | None:
+    r"""The queries this one is asked as, or nothing if it is asked as itself.
+
+    Returns query text paired with what the part is about: the candidate it
+    asks after, or the step it covers. The pair matters: reading the candidate
+    back out of the text it was written into loses its type and trusts a
+    string the caller chose.
+
+    Each part is gathered like any other query, which is what gives it the
+    context its own labels need.
+    """
+    # Imported here because how many candidates to rank is settled by the
+    # relational materializer, which is built on the request this returns.
+    from sdm_client.materializers.relational import _candidates_to_rank
+
+    kind = str(getattr(query, 'problem_type', ''))
+    if kind.endswith('RANK'):
+        if 'prediction_statistic' in options:
+            # Said here: each part is a classification, and refusing there
+            # would name a binary_classification the caller never wrote.
+            raise StructuredDataError(
+                'prediction_statistic applies only to a regression, and this '
+                'question is a ranking, ordered by how likely each candidate '
+                'is; ask it without prediction_statistic',
+                code='INVALID_REQUEST',
+            )
+        return Decomposition(
+            RANKING,
+            tuple(_per_candidate(query, candidates, schema)),
+            _candidates_to_rank(query, options),
+        )
+    if candidates is not None:
+        raise StructuredDataError(
+            f'candidates are the rows a ranking is over, and {text!r} does '
+            f'not rank anything. Ask it without candidates, or rank with '
+            f'"RANK TOP k", which is the question they are for',
+            code='INVALID_REQUEST',
+        )
+    if kind.endswith('FORECAST'):
+        if 'top_k' in options:
+            raise StructuredDataError(
+                'top_k is how many candidates a ranking keeps, and a forecast '
+                'ranks nothing; it gives back one value per step',
+                code='INVALID_REQUEST',
+            )
+        return Decomposition(FORECAST, tuple(_per_step(query)))
+    return None
+
+
+def _ended(message: Any) -> str:
+    """``message`` with a full stop, so what is appended reads as a sentence.
+
+    Not every message this wraps ends in one, and two of them run together
+    without it.
+    """
+    text = str(message).rstrip()
+    return text if not text or text[-1] in '.!?' else f'{text}.'
+
+
+def refuse_a_part_that_would_take_several_calls(
+    rewritten: Decomposition, asked: int, per_call: int
+) -> None:
+    r"""Refuse a question asked in parts over more rows than one call scores.
+
+    A part is one call. The guard above counts parts on that basis, so a
+    batched part would make the parts times the batches: a ranking over 200
+    candidates and 50,000 entities passes as 200 calls and sends 1,000.
+
+    A ranking could not be batched in any case. Each batch samples its own
+    context, and a batch whose context holds one class leaves the candidate
+    out of every row rather than out of its own, because a candidate is
+    reported unscored for the whole ranking.
+
+    Checked before anything is gathered, from the count the caller gave, so a
+    refusal costs nothing and arrives before the ceilings that are about what
+    gathering holds.
+    """
+    if per_call <= 0 or asked <= per_call:
+        return
+    each = 'candidate' if rewritten.kind == RANKING else 'step'
+    why = (
+        'and a candidate is reported unscored for the whole ranking, so one '
+        'cold batch would drop it from every row rather than from its own'
+        if rewritten.kind == RANKING
+        else 'and the calls would be the batches times the steps rather than '
+        'the steps that were counted'
+    )
+    raise StructuredDataError(
+        f'{asked:,} entities are more than the {per_call:,} one call scores, '
+        f'and this question is asked as {len(rewritten.parts):,} of them, one '
+        f'per {each}. A part is not batched, {why}. Ask about fewer entities '
+        f'at a time',
+        code='UNSUPPORTED_REQUEST',
+        details={'entities': asked, 'rows_per_call': per_call},
+    )
+
+
+def about_the_part(
+    error: StructuredDataError, rewritten: Decomposition, about: Any
+) -> StructuredDataError:
+    r"""``error``, said of the part it happened in, and still its own type.
+
+    A ranking's part is about one candidate, which can be dropped; a forecast's
+    covers a window further out than the one written, which is asked for by
+    asking for fewer steps. One wording served both and was false of the first.
+
+    The step named is the one that failed: anything at or above it fails alike.
+    The type is kept, because it is what `predict` documents.
+
+    Which part failed is always said, because it is always true. A remedy is
+    added only where the failure is one it addresses. An unknown model is not
+    answered by asking for fewer steps, and at step 1 there are no fewer to ask
+    for.
+    """
+    how_many = len(rewritten.parts)
+    first = _ended(error.args[0])
+    if rewritten.kind == RANKING:
+        said = (
+            f'This is the question asked for candidate {about!r}, one of '
+            f'{how_many} this ranking is asked as.'
+        )
+    else:
+        said = f'This is forecast step {about} of {how_many}.'
+        if (getattr(error, 'details', None) or {}).get(
+            'window_outran_the_data'
+        ):
+            said += (
+                f" The window named above is that step's rather than the one "
+                f'written; ask for fewer than {about} steps if the data does '
+                f'not reach that far.'
+            )
+    said = f'{first} {said}'
+    carried = error.__class__.__new__(error.__class__)
+    carried.__dict__.update(error.__dict__)
+    carried.args = (said, *error.args[1:])
+    carried.message = said
+    return carried
+
+
+def _for_each(query: ValidatedPredictiveQuery) -> str:
+    r"""The entity clause as it was written, filter and all.
+
+    An entity filter chooses which rows become labelled examples rather than
+    which rows are scored, so a part that drops it is answered from a
+    different population than the one asked about.
+    """
+    return f'{query.for_each} {query.entity_ast}'
+
+
+def _window(query: ValidatedPredictiveQuery) -> tuple[int, int, str]:
+    span = query.get_final_target_aggregation().date_offset_range
+    return int(span.start), int(span.end), str(span.unit)
+
+
+def _per_candidate(
+    query: ValidatedPredictiveQuery,
+    candidates: list[Any] | None,
+    schema: Schema | None = None,
+) -> list[tuple[str, Any]]:
+    r"""One binary question per candidate, ordered by how sure the answer is.
+
+    The endpoint has no ranking task, and a ranking it could serve would still
+    be over whatever the sampler reached. Asking per candidate makes the set
+    the caller's, which is the only version of this question with a knowable
+    answer.
+    """
+    aggregation = query.get_final_target_aggregation()
+    if aggregation is None:
+        raise StructuredDataError(
+            'a ranking is asked one candidate at a time, about what an '
+            'entity reaches in a window, and this one ranks a column '
+            'instead. Rank a LIST_DISTINCT over a foreign key.',
+            code='INVALID_REQUEST',
+        )
+    ranked = str(aggregation.target)
+    if ' WHERE ' in ranked:
+        raise StructuredDataError(
+            f'the rows to rank are chosen by a filter ({ranked!r}), and each '
+            f'candidate is asked about with a filter of its own, so the two '
+            f'would have to be combined into one question this cannot write. '
+            f'Rank without the filter, or narrow the rows before building the '
+            f'schema.',
+            code='INVALID_REQUEST',
+        )
+    table, _, column = ranked.partition('.')
+    if candidates is None:
+        raise StructuredDataError(
+            f'a ranking is over a set of candidates, and this model has no '
+            f'ranking task to choose them with, so they have to be named: '
+            f'materialize(..., candidates=frame[{column!r}]). '
+            f'One call is made per candidate.',
+            code='INVALID_REQUEST',
+        )
+    unique = list(dict.fromkeys(candidates))
+    if not unique:
+        raise StructuredDataError(
+            'candidates is empty, so there is nothing to rank',
+            code='INVALID_REQUEST',
+        )
+    _refuse_too_many(len(unique), 'candidates')
+    dtype = _how_the_column_travels(schema, table, column)
+    start, end, unit = _window(query)
+    return [
+        (
+            f'PREDICT COUNT({table}.* WHERE {ranked}='
+            f'{_as_literal(value, dtype)}, '
+            f'{start}, {end}, {unit}) > 0 {_for_each(query)}',
+            value,
+        )
+        for value in unique
+    ]
+
+
+def _per_step(query: ValidatedPredictiveQuery) -> list[tuple[str, Any]]:
+    r"""One question per step, each about the window that step covers.
+
+    The aggregation is rebuilt from what it aggregates, which carries any
+    filter it had: `COUNT(buys.* WHERE channel="web", ...)` keeps its channel.
+    Only the window moves.
+    """
+    steps = int(getattr(query, 'num_forecasts', 1) or 1)
+    _refuse_too_many(steps, 'forecast steps')
+    aggregation = query.get_final_target_aggregation()
+    start, end, unit = _window(query)
+    span = end - start
+    return [
+        (
+            f'PREDICT {aggregation.aggr}({aggregation.target}, '
+            f'{start + step * span}, {end + step * span}, {unit}) '
+            f'{_for_each(query)}',
+            # The contract numbers steps from one.
+            step + 1,
+        )
+        for step in range(steps)
+    ]
+
+
+def _refuse_too_many(many: int, what: str) -> None:
+    if many <= MOST_PARTS:
+        return
+    raise StructuredDataError(
+        f'{many} {what} means {many} calls, one for each, because the model '
+        f'has no task that answers them together. That is past the {MOST_PARTS} '
+        f'this will do without being told to; ask about fewer, or raise '
+        f'sdm_client.decompose.MOST_PARTS if the wait is what you want.',
+        code='INVALID_REQUEST',
+    )
+
+
+def _how_the_column_travels(
+    schema: Schema | None, table: str, column: str
+) -> str | None:
+    r"""The dtype the schema computed for the column being ranked.
+
+    How a candidate is written is the column's question, not the value's: a key
+    column straddling int64 travels as text, and so must a small key from it.
+    """
+    if schema is None or table not in schema:
+        return None
+    described = schema[table]
+    if column not in described:
+        return None
+    return str(described[column].dtype)
+
+
+def _as_literal(value: Any, dtype: str | None = None) -> str:
+    r"""``value`` as the query language writes it.
+
+    A candidate is a key, and a key that cannot be written as one is refused
+    rather than escaped into something that parses as a different question.
+    """
+    # Candidates usually come out of a frame, where a whole number is a numpy
+    # integer and not an ``int``, and the two have to be written alike.
+    if hasattr(value, 'item'):
+        with contextlib.suppress(AttributeError, ValueError):
+            value = value.item()
+    if _is_missing(value):
+        raise StructuredDataError(
+            'a candidate names a row, and a missing value names none',
+            code='INVALID_REQUEST',
+        )
+    if isinstance(value, bool):
+        raise StructuredDataError(
+            'a candidate names a row, and True and False do not',
+            code='INVALID_REQUEST',
+        )
+    if isinstance(value, Decimal):
+        written = _decimal_as_typed(value, dtype)
+        if isinstance(written, (int, float)) and Decimal(written) != value:
+            raise StructuredDataError(
+                f'the candidate {value} names no row of a column of '
+                f'{dtype or "numbers"}: written as one it becomes {written}, '
+                f'which is a different row',
+                code='INVALID_REQUEST',
+            )
+        value = written
+    if dtype == 'string' and isinstance(value, (int, float)):
+        if isinstance(value, float) and not math.isfinite(value):
+            raise StructuredDataError(
+                f'{value!r} cannot name a row to rank',
+                code='INVALID_REQUEST',
+            )
+        value = format(Decimal(str(value)), 'f')
+    if isinstance(value, int):
+        return str(value)
+    if isinstance(value, float):
+        if not math.isfinite(value) or value != int(value):
+            raise StructuredDataError(
+                f'{value!r} cannot name a row to rank',
+                code='INVALID_REQUEST',
+            )
+        return str(int(value))
+    text = str(value)
+    if any(character in text for character in '"\'\\,()') or not text.strip():
+        raise StructuredDataError(
+            f'the candidate {value!r} cannot be written into a query: a key '
+            f'holding a quote, a comma, a bracket or nothing at all would '
+            f'read as part of the question rather than as the row it names',
+            code='INVALID_REQUEST',
+        )
+    return f'"{text}"'
+
+
+def _decimal_as_typed(value: Decimal, dtype: str | None = None) -> Any:
+    r"""``value`` as the Python type its column is typed as on the wire.
+
+    A warehouse ``DECIMAL`` reaches a caller as a :class:`~decimal.Decimal`,
+    and written as a string it asks after the row named ``"1"`` on a column of
+    integers, a question the validator refuses and nobody wrote. Which type
+    that is does not follow from the Python type: :func:`_decimal_dtype` is
+    what decides whether such a column travels as an integer, a float, or its
+    digits. ``dtype`` carries the column's; the value alone is used only where
+    the column is not known.
+
+    The digits are formatted rather than ``str``-ed, since ``str`` turns to
+    scientific notation past int64's width, which is the width that makes such
+    a column text in the first place.
+    """
+    if dtype is None:
+        dtype = _decimal_dtype(pd.Series([value], dtype=object))
+    if dtype == 'int64':
+        return int(value)
+    if dtype == 'float64':
+        return float(value)
+    return format(value, 'f')

sdm_client/errors.py

@@ -0,0 +1,177 @@
+# SPDX-FileCopyrightText: Copyright (c) 2026, NVIDIA CORPORATION & AFFILIATES.
+# All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+
+r"""The exceptions this client raises.
+
+Every call on :class:`~sdm_client.SDMClient` raises
+:class:`StructuredDataError` or one of its subclasses, so ``except
+StructuredDataError`` is enough to catch anything the client reports.
+
+Every error carries a ``code``: a short stable string meant to be branched on.
+Messages are written for people and will change; codes will not.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+from typing import Any
+
+#: What to do about a context that teaches nothing.
+WIDEN_THE_CONTEXT = (
+    'Gather a wider context with num_context_samples, or ask about entities '
+    'whose answers differ'
+)
+
+#: Entries rendered from an RFC-9457 ``invalid_params`` list before the rest
+#: are summarised as a count. A rejected batch can name thousands of rows.
+MAX_INVALID_PARAMS = 5
+
+
+def format_invalid_params(params: Sequence[Any] | None) -> str:
+    r"""Render an endpoint's per-field validation diagnosis into a suffix.
+
+    A validation failure answers with RFC-9457 ``invalid_params``, naming the
+    exact table, row and column it rejected, while the top-level ``detail`` is
+    often only "Request validation failed." Dropping the list leaves the caller
+    with nothing to act on.
+
+    Returns the empty string when there is nothing to render, so callers can
+    concatenate unconditionally.
+    """
+    if not isinstance(params, (list, tuple)):
+        return ''
+    entries = []
+    for param in params[:MAX_INVALID_PARAMS]:
+        if not isinstance(param, dict):
+            continue
+        name, reason = param.get('name'), param.get('reason')
+        if name and reason:
+            entries.append(f'{name}: {reason}')
+        elif name or reason:
+            entries.append(str(name or reason))
+    if not entries:
+        return ''
+    omitted = len(params) - len(entries)
+    more = f' (and {omitted} more)' if omitted > 0 else ''
+    return ' ' + '; '.join(entries) + more
+
+
+class StructuredDataError(Exception):
+    r"""Base class for every error this client raises.
+
+    Attributes:
+        message: The human-readable description, without the code prefix.
+        code: A short stable identifier, e.g. ``'TRANSPORT_ERROR'`` or
+            ``'INVALID_REQUEST'``. Branch on this rather than on the message.
+        details: Whatever structured context the failure carried, such as the
+            ``invalid_params`` entries from a NIM validation error. Empty when
+            there is none.
+    """
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        code: str | None = None,
+        details: dict[str, Any] | None = None,
+    ) -> None:
+        super().__init__(message)
+        self.message = message
+        self.code = code
+        self.details = details or {}
+
+    def __str__(self) -> str:
+        if self.code:
+            return f'[{self.code}] {self.message}'
+        return self.message
+
+
+class UnknownModelError(StructuredDataError):
+    r"""A request named a model this client cannot send.
+
+    The contract's ``model`` field is a closed enum, so an id it does not carry
+    cannot be sent at all. The message names the change that would allow it
+    rather than letting the request fail at the endpoint. Code:
+    ``UNKNOWN_MODEL``.
+    """
+
+    def __init__(self, model: str, known: list[str]) -> None:
+        super().__init__(
+            f'Unknown model {model!r}; this client can send: {sorted(known)}. '
+            f'The Universal TFM contract declares these as a closed set, so a '
+            f'new model id has to be added to the contract and the bindings '
+            f'regenerated before it can be sent.',
+            code='UNKNOWN_MODEL',
+            details={'model': model, 'known_models': sorted(known)},
+        )
+        self.model = model
+
+
+class UnsupportedRequestError(StructuredDataError):
+    r"""The model cannot answer this request, and says so before sending it.
+
+    Raised when a request asks for something the model's profile rejects, such
+    as
+    related tables for a single-table model, an output field it does not
+    produce, or exceeds a limit the endpoint enforces. Code:
+    ``UNSUPPORTED_REQUEST``.
+    """
+
+    def __init__(
+        self, message: str, *, details: dict[str, Any] | None = None
+    ) -> None:
+        super().__init__(message, code='UNSUPPORTED_REQUEST', details=details)
+
+
+class MissingExtraError(StructuredDataError):
+    r"""An optional dependency this call needs is not installed.
+
+    The relational engine and the connector drivers ship as extras, so the
+    client can be installed without them. The message names the ``pip install``
+    that fixes it. Code: ``MISSING_EXTRA``.
+    """
+
+    def __init__(self, extra: str, package: str) -> None:
+        super().__init__(
+            f'{package!r} is required for this call; install it with '
+            f'`pip install structured-data-models-client[{extra}]`',
+            code='MISSING_EXTRA',
+            details={'extra': extra, 'package': package},
+        )
+
+
+class NimRequestError(StructuredDataError):
+    r"""The NIM answered, and the answer was an error.
+
+    Distinguished from :class:`StructuredDataError` by carrying the HTTP
+    :attr:`status_code`, which is the endpoint's own answer, kept as it was.
+
+    Branch on :attr:`code`, not on the status. ``INVALID_REQUEST`` means the
+    request has to change and sending it again cannot help; ``429``, ``502``,
+    ``503`` and ``504`` are worth retrying, and this client retries them. The
+    two can disagree: the
+    endpoint reports some caller mistakes with a ``500`` and an internal code,
+    in a sentence that names exactly what the caller got wrong, and this client
+    reports those as the caller's. Where it does, the endpoint's own
+    classification is kept in :attr:`details` under ``endpoint_code``.
+
+    Attributes:
+        status_code: The HTTP status the NIM returned.
+    """
+
+    def __init__(
+        self,
+        status_code: int,
+        *,
+        code: str | None,
+        message: str,
+        details: dict[str, Any] | None = None,
+    ) -> None:
+        super().__init__(message, code=code, details=details)
+        self.status_code = status_code
+
+    def __str__(self) -> str:
+        if self.code:
+            return f'[{self.status_code} {self.code}] {self.message}'
+        return f'[{self.status_code}] {self.message}'

sdm_client/materializers/__init__.py

@@ -0,0 +1,10 @@
+# SPDX-FileCopyrightText: Copyright (c) 2026, NVIDIA CORPORATION & AFFILIATES.
+# All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+
+r"""Model-specific implementations behind query materialization."""
+
+from sdm_client.materializers.relational import RelationalMaterializer
+from sdm_client.materializers.tabular import TabularMaterializer
+
+__all__ = ['RelationalMaterializer', 'TabularMaterializer']