Python SDK API

Install the SDK by following Install and Connect. This reference documents the sdm-client interfaces used by the Kumo Tabular workflow.

Import the supported public interfaces from sdm_client:

from sdm_client import (
    SDMClient, Schema, Request, PredictiveQuery, KumoTabular, PredictionResult,
)

SDMClient

SDMClient(
    url: str,
    api_key: str | None = None,
    *,
    verify_ssl: bool = True,
    timeout: float = 60.0,
    max_retries: int = 3,
)

A connection to one NIM, serving every model it can reach. No request is made by the constructor; the endpoint is first contacted by health_ready(), models(), or a prediction. Use it as a context manager, or call close() explicitly.

Each client owns its own transport, so several can target different endpoints or tenants at once, including from several threads — a prediction always goes to the endpoint and credential of the client that started it.

KumoTabular

from sdm_client import KumoTabular
client.predict(request, model=KumoTabular())

A thin, stateless handle naming the tabular model. One table in, a prediction per row out.

Schema

Schema.from_data(
    tables: Mapping[str, pandas.DataFrame],
    *,
    primary_keys: Mapping[str, str | Sequence[str]] | None = None,
    time_columns: Mapping[str, str | None] | None = None,
    relationships: Sequence[Relationship] | None = None,
) -> Schema

Infers dtype, semantic type, primary key, and time column for every column of every table. Index it by table name, and index a table by column name:

schema = Schema.from_data({"users": users_df})
schema["users"].primary_key = "user_id"
schema["users"]["churn"].stype = "categorical"

Schema.from_source(), which samples a warehouse or database in place without loading it into memory, exists but is refused for a tabular question — it is for the relational model. See Prepare Your Data.

Request

Request(
    context: pandas.DataFrame,
    predict: pandas.DataFrame,
    *,
    target: str,
    task: str,
    related_tables: Mapping[str, pandas.DataFrame] | None = None,
    schema: Schema | None = None,
    entity_table: str = "instance",
    inference: Mapping[str, Any] | None = None,
    task_options: Mapping[str, Any] | None = None,
)

The wire envelope minus the two things that are predict() arguments: which model answers it, and which output fields you want back. A Kumo Tabular request is sent in one call; this adapter does not automatically split it into batches. Refer to Limits for the context-row cap.

Read-only properties: is_relational, context_rows, predict_rows, nothing_to_score. request.task is a Task(kind, target, entity_table, options); request.task.target is a Target(column_name, dtype, table_name); request.context/request.predict are each a Split(instance_table, related_tables). These are read-only descriptions of a request, not something you construct by hand.

ModelCapabilities

What client.capabilities(model) returns: model, tasks, outputs, single_table, multiple_tables, relationships, explanation_formats, and sessions. Describes this client, not the endpoint.

PredictiveQuery

PredictiveQuery(query: str, data: Schema | Mapping[str, pandas.DataFrame])
.materialize(
    *,
    indices: Sequence[Any] | None = None,
    predict: pandas.DataFrame | None = None,
    num_context_samples: int | None = None,
    model: str | Model | None = None,
    task: str | None = None,
) -> Request

Resolves and validates the query when materialize() builds a request. Pass exactly one of indices (existing rows, looked up by key) or predict (rows supplied directly). See Make Predictions.

PredictionResult

result = client.predict(request, model=KumoTabular())

FittedModel

Returned by SDMClient.fit(). predict(request) scores rows against the pinned context; close() releases it. Use as a context manager or call close() explicitly.

Errors

from sdm_client import (
    StructuredDataError, UnknownModelError, UnsupportedRequestError,
    MissingExtraError, NimRequestError,
)

Every call on SDMClient raises StructuredDataError or a subclass, so except StructuredDataError catches anything the client reports. Every error carries a stable code to branch on; messages are written for people and will change.

sdm_connectors

from sdm_connectors import read
df = read("snowflake", table="orders", account="...", user="...", password="...")

See Connect Data Sources for read() and per-backend arguments.