Deploy, Install, and Connect

Before you use the SDK, obtain a reachable NIM endpoint serving kumo-relational. The SDK sends prediction requests to that deployment; it does not deploy or run Kumo Relational itself.

1. Choose a NIM endpoint

Direct NVIDIA API Catalog access. Find the model in the NVIDIA API catalog and call it over NIM REST API with an Authorization: Bearer key.

SDK access. Point SDMClient at a NIM that accepts X-API-Key: either the container you run yourself on your own GPU host (use this option when the materialized prediction context must remain in your environment), or a gateway in front of the catalog that translates X-API-Key to Authorization: Bearer.

Amazon SageMaker. Follow Deploy on Amazon SageMaker to deploy this model and invoke it with boto3. The SDK HTTP connection instructions below do not apply to SageMaker endpoints.

A model served on Databricks Model Serving. Reached by endpoint name through the Databricks SDK; see Connect from Databricks below.

A direct HTTP connection to a self-hosted NIM or compatible gateway uses its URL and, when authenticating, an API key. Databricks Model Serving uses the endpoint name and a WorkspaceClient; see Connect from Databricks. SageMaker connection and AWS authentication are covered in its deployment guide.

2. Install the SDK

Client requirements

• CPython 3.10 to 3.14 for the client, the language, the wire types, and the connectors. CPython 3.10 to 3.13 only for the relational engine: pip install "structured-data-models-client[relational]" does not resolve on 3.14.
• The endpoint URL of a running NIM serving kumo-relational
• Network access to the NIM endpoint
• An API key for an authenticating gateway, when required

The base structured-data-models-client package, the language, and the connectors are pure Python. structured-data-models-relational-engine performs graph building, native sampling, and query resolution for Kumo Relational. Only the relational engine is native; its published wheels target manylinux_2_28 for x86-64 and aarch64, so kumo-tabular runs anywhere and kumo-relational needs that Linux.

Install the SDK with the Kumo Relational driver:

pip install "structured-data-models-client[relational]"

If your workflow reads directly from a database or object store, add the appropriate connector:

The base-only installation provides the HTTP client, the Predictive Query Language, and the tabular model, without the native relational engine. Install the [relational] extra before building a multi-table schema, resolving PQL against one, or running Kumo Relational predictions. Connector extras can be installed independently when a workflow only needs to read source data.

The all extra includes relational and every connector (sqlite, duckdb, postgres, lakebase, snowflake, databricks, s3), but not databricks-serving, which reaches a model rather than a data backend.

structured-data-models-client, -api, -pql, -connectors, and -relational-engine are five distributions released together on one version. Keep them aligned when managing packages explicitly.

3. Connect to the NIM

Create one SDMClient for each NIM endpoint. The client owns its HTTP connection and should be closed after use. A closed client cannot be reused; construct a new client for later requests.

from sdm_client import SDMClient
with SDMClient(url="http://localhost:8000") as client:
    print(client.health_ready())
    print(client.models())

If an authenticating gateway fronts the NIM and accepts X-API-Key, pass its key with the api_key parameter:

from sdm_client import SDMClient
with SDMClient(
    url="https://your-relational-endpoint.example.com",
    api_key="YOUR_API_KEY",
) as client:
    print(client.health_ready())

You can also configure connection behavior with the verify_ssl, timeout, and max_retries parameters.

SDMClient does not read its URL or API key from the environment. Pass both values explicitly. Application code can read its own environment configuration before constructing the client:

import os
from sdm_client import SDMClient
client = SDMClient(
    url=os.environ["KUMO_RELATIONAL_API_ENDPOINT"],
    api_key=os.environ.get("KUMO_RELATIONAL_API_KEY"),
)

To create a reusable client:

client = SDMClient(url=NIM_URL, api_key=NIM_API_KEY)
result = client.predict(request, model=KumoRelational())
# Close the client after the final request.
client.close()

Construct a new client instead of reusing a closed one.

Connect from Databricks

A model deployed to Databricks Model Serving is reached by its endpoint name, not a URL. In a notebook, the call authenticates as the notebook, with no URL or key to supply.

from sdm_client import SDMClient, KumoRelational
with SDMClient.for_databricks_serving("kumo-relational") as client:
    result = client.predict(request, model=KumoRelational())

This needs pip install "structured-data-models-client[relational,databricks-serving]". A serving endpoint answers one request at a time: predict() works and sends the context with every call, but fit() is refused there since there is no session to pin a context in. Pass workspace_client= to authenticate as a specific identity outside a notebook.

4. Verify what the client and the endpoint support

from sdm_client import SDMClient, KumoRelational
with SDMClient(url="http://localhost:8000") as client:
    print(client.models())                       # read from the endpoint's /v1/models
    print(client.capabilities(KumoRelational()))  # read from this client, not the endpoint

If the readiness check fails, verify the endpoint URL, network route, TLS certificate, and gateway credentials before building a schema.

Next steps

• Run the Kumo Relational quickstart
• Prepare your data
• Build a graph
• Make predictions
• Review the Python SDK API