> This page is for Structured Data Models Client.

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.nvidia.com/sdgm/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.nvidia.com/sdgm/_mcp/server.

# Deploy, Install, and Connect

> Deploy a Kumo Relational NIM, install structured-data-models-client, and verify the connection

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](/sdgm/kumo-relational/reference/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`.

> **Warning**
>
> `SDMClient` always sends `api_key` as an `X-API-Key` header. NVIDIA API Catalog endpoints require `Authorization: Bearer` instead, so `SDMClient` cannot authenticate to a catalog endpoint directly.

**Amazon SageMaker.** Follow [Deploy on Amazon SageMaker](/sdgm/kumo-relational/deployment/aws/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](#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](#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

> **Info**
>
> The installation commands below install the required Python runtime dependencies automatically. You do not need to install the dependencies individually.

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:

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

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

| Workflow                                           | Installation                                                                 |
| -------------------------------------------------- | ---------------------------------------------------------------------------- |
| Client only                                        | `pip install structured-data-models-client`                                  |
| Kumo Relational                                    | `pip install "structured-data-models-client[relational]"`                    |
| SQLite                                             | `pip install "structured-data-models-client[relational,sqlite]"`             |
| DuckDB                                             | `pip install "structured-data-models-client[relational,duckdb]"`             |
| PostgreSQL                                         | `pip install "structured-data-models-client[relational,postgres]"`           |
| Databricks Lakebase                                | `pip install "structured-data-models-client[relational,lakebase]"`           |
| Snowflake                                          | `pip install "structured-data-models-client[relational,snowflake]"`          |
| Databricks                                         | `pip install "structured-data-models-client[relational,databricks]"`         |
| Amazon S3                                          | `pip install "structured-data-models-client[relational,s3]"`                 |
| Kumo Relational served on Databricks Model Serving | `pip install "structured-data-models-client[relational,databricks-serving]"` |

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.

> **Warning**
>
> **What you install is not what you import.** The five distributions are `structured-data-models-client`, `-api`, `-pql`, `-connectors`, and `-relational-engine`; the modules they install are `sdm_client`, `sdm_api`, `predictive_query`, `sdm_connectors`, and `sdm_relational_engine`. Only the first of each pair is ever typed at a prompt.

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.

> **Note**
>
> Installing on Databricks has its own pitfalls around NumPy pinning, shell-quoted version bounds, and which Postgres driver to use for Lakebase. See the [installation notes](https://github.com/NVIDIA/structured-data-models-client/blob/main/docs/get-started/installation.md#on-databricks) in the client's own repository if you install into a Databricks notebook.

## 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.

> **Choose a client lifecycle**
>
> The examples in this documentation use `with SDMClient(...)` so that each snippet is self-contained and closes its connection automatically. In an application or notebook that makes multiple requests, create one client, reuse it, and call `client.close()` when the workflow is complete.

```python
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:

```python
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:

```python
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:

```python
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.

> **Warning**
>
> The SDK refuses to send an API key to a non-local endpoint that uses plaintext HTTP. Use HTTPS for authenticated remote deployments.

## 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.

```python
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

```python
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
```

> **Note**
>
> `models()` is the endpoint's own answer, read from `/v1/models`.
> `capabilities(model)` describes what this client can build and send; it needs no live connection and is not the endpoint's answer.
> A deployment can serve fewer task kinds or output fields than the client declares; see [Prediction Types](/sdgm/kumo-relational/user-guide/make-predictions/prediction-types) and [Prediction Explainability](/sdgm/kumo-relational/user-guide/explain-predictions/prediction-explainability).

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](/sdgm/kumo-relational/get-started/rfm)
* [Prepare your data](/sdgm/kumo-relational/user-guide/prepare-data/data-requirements)
* [Build a graph](/sdgm/kumo-relational/user-guide/build-a-relational-graph/graph-creation)
* [Make predictions](/sdgm/kumo-relational/user-guide/make-predictions/make-predictions)
* [Review the Python SDK API](/sdgm/kumo-relational/reference/python-api-reference)