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

# Install and Connect

> Install structured-data-models-client and connect to a NIM serving kumo-tabular

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

## 1. Choose a NIM endpoint

**Direct NVIDIA API Catalog access.** Find the model in the NVIDIA API catalog and call it over REST with an `Authorization: Bearer` key. See the [Kumo Tabular API reference](https://docs.api.nvidia.com/nim/reference/nvidia-kumo-tabular) for the request contract.

**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 when the data cannot leave 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-tabular/deployment/aws/sagemaker) to deploy this model and invoke it with `boto3`.
The SDK HTTP connection instructions below do not apply to SageMaker endpoints.

For the direct HTTP options, the client needs the URL and, for an authenticating deployment, an API key.
Pass these values explicitly to `SDMClient`.
SageMaker connection and AWS authentication are covered in its deployment guide.

## 2. Install the SDK

### Client requirements

* CPython 3.10 to 3.14
* The endpoint URL of a running NIM serving `kumo-tabular`
* Network access to the NIM endpoint
* No GPU is needed: the client runs no model and downloads no weights

> **Info**
>
> Kumo Tabular is pure Python and installs anywhere. Only the relational model's native engine requires Linux (x86-64 or aarch64) and is capped at Python 3.13; you do not need it for Kumo Tabular.

```bash
pip install structured-data-models-client
```

The base install gives you the client, the Predictive Query Language, and the tabular model. What ships in the base wheel is decided by dependency weight, not preference: a model that does heavy client-side work is an opt-in extra.

| Command                                                   | You get                                                                                                         |
| --------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- |
| `pip install structured-data-models-client`               | The client, the language, and the tabular model. Runs anywhere.                                                 |
| `pip install "structured-data-models-client[relational]"` | Adds the relational model, pulling in its native engine. Not needed for Kumo Tabular.                           |
| `pip install "structured-data-models-client[snowflake]"`  | Reads tables from a warehouse. Also `[sqlite]`, `[duckdb]`, `[postgres]`, `[lakebase]`, `[databricks]`, `[s3]`. |
| `pip install "structured-data-models-client[all]"`        | The relational model and every warehouse backend.                                                               |

See [Connect Data Sources](/sdgm/kumo-tabular/user-guide/prepare-data/connect-data-sources) for the connector extras.

> **Warning**
>
> **What you install is not what you import.** The distribution is `structured-data-models-client`; the module is `sdm_client`.

## 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-tabular-endpoint.example.com",
    api_key="YOUR_API_KEY",
) as client:
    print(client.health_ready())
```

`SDMClient` does not read its URL or API key from the environment. Pass both values explicitly.

```python
import os
from sdm_client import SDMClient

client = SDMClient(
    url=os.environ["SDM_TABULAR_URL"],
    api_key=os.environ.get("SDM_TABULAR_API_KEY"),
)
```

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

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

To create a reusable client:

```python
client = SDMClient(url=NIM_URL, api_key=NIM_API_KEY)

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

# Close the client after the final request.
client.close()
```

Construct a new client instead of reusing a closed one.

## 4. Verify what the client and the endpoint support

```python
from sdm_client import SDMClient, KumoTabular

with SDMClient(url="http://localhost:8000") as client:
    print(client.models())               # read from the endpoint's /v1/models
    print(client.capabilities(KumoTabular()))  # 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.

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

## Next steps

* [Run the Kumo Tabular quickstart](/sdgm/kumo-tabular/get-started/quickstart)
* [Prepare your data](/sdgm/kumo-tabular/user-guide/prepare-data/data-requirements)
* [Make predictions](/sdgm/kumo-tabular/user-guide/make-predictions/make-predictions)
* [Review the Python SDK API](/sdgm/kumo-tabular/reference/python-api-reference)