> 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 the NVIDIA Kumo Relational Client, and verify the connection

The NVIDIA Kumo Relational Client is a Python SDK for sending relational prediction requests to the Kumo Relational NVIDIA NIM, a containerized service that runs the predictions.
Before you install the SDK, obtain a Kumo Relational NIM endpoint that your application or notebook can reach.
The SDK connects to an existing deployment; it does not deploy or run the NIM itself.

## 1. Choose a NIM endpoint

### Self-hosted container

Find the Kumo Relational NIM in the [NVIDIA NGC Catalog](https://catalog.ngc.nvidia.com) and follow its deployment instructions on a supported NVIDIA GPU host.
Use this option when the prediction context that the engine constructs from your data must remain in your environment.

After deployment, record the NIM base URL, such as `http://localhost:8000` for a local container.
For a remote deployment, use a hostname that the client application or notebook can reach.
If an authenticating gateway fronts the NIM, obtain the gateway API key.

### NVIDIA API Catalog

NVIDIA API Catalog endpoints use `Authorization: Bearer` authentication.
`RelationalClient` sends its `api_key` through the `X-API-Key` header, so it cannot authenticate directly to those endpoints.
To call the hosted Kumo Relational endpoint, follow the bearer-authenticated examples in [NIM REST API](/kumo-relational/reference/nim-rest-api).
Use `RelationalClient` with a self-hosted NIM or a compatible gateway instead.

## 2. Install the SDK

### Client requirements

* CPython 3.10, 3.11, 3.12, or 3.13
* The endpoint URL of a running Kumo Relational NIM
* 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 `kumo-relational-client` package and its data connectors are pure Python.
The `[relational]` extra adds the Kumo Relational engine, which constructs graphs, parses Predictive Query Language (PQL) queries, and samples the related records needed for prediction.
The published `kumo-relational-engine` wheels support CPython 3.10 through 3.13 on the following platforms:

| Platform                            | Supported |
| ----------------------------------- | --------- |
| Linux x86-64 or ARM64               | Yes       |
| macOS 11+ on Intel or Apple silicon | Yes       |
| Windows x64                         | Yes       |
| Windows ARM64                       | No        |

No engine source distribution is published. Choose a supported platform and Python version rather than relying on a source-build fallback. See the [client platform requirements](https://github.com/kumo-ai/kumo-relational-client#requirements) for the Linux runtime requirements and current compatibility details.

For a standard Kumo Relational workflow on a supported host, install the SDK with the relational engine:

```bash
pip install "kumo-relational-client[relational]"
```

#### Choose connectors and optional extras

If your workflow reads directly from a database or object store, add the connector for that data source.
If you only need the HTTP client or local DataFrame and file reads, install the client without the relational engine.

| Workflow                 | Installation                                                  |
| ------------------------ | ------------------------------------------------------------- |
| Client only              | `pip install "kumo-relational-client"`                        |
| Base Kumo Relational SDK | `pip install "kumo-relational-client[relational]"`            |
| SQLite                   | `pip install "kumo-relational-client[relational,sqlite]"`     |
| DuckDB                   | `pip install "kumo-relational-client[relational,duckdb]"`     |
| Snowflake                | `pip install "kumo-relational-client[relational,snowflake]"`  |
| Databricks               | `pip install "kumo-relational-client[relational,databricks]"` |
| Amazon S3                | `pip install "kumo-relational-client[relational,s3]"`         |

The base-only installation provides the HTTP client and local DataFrame or file reads without installing the native relational engine.
Install the `[relational]` extra before constructing graphs, parsing PQL, 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`, `sqlite`, `duckdb`, `snowflake`, `databricks`, `databricks-serving`, and `s3`.
It does not include `explain`, `relbench`, or `snowflake-serving`; install those extras explicitly when needed.
Data-source extras configure access to stored data, while `databricks-serving` and `snowflake-serving` configure managed model-serving clients.

`kumo-relational-client`, `kumo-connectors`, and `kumo-relational-engine` are versioned and released together.
Keep their versions aligned when managing packages explicitly.

## 3. Connect to the NIM

Create one `RelationalClient` 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 RelationalClient(...)` 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 kumo_relational_client import RelationalClient

with RelationalClient(url="http://localhost:8000") as client:
    print(client.health_ready())
    print(client.models())
```

The readiness call should complete without a connection or authentication error.
`models()` returns `['kumo-relational']`.
If the readiness check fails, verify the endpoint URL, network route, TLS certificate, and gateway credentials before building a graph.

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

```python
from kumo_relational_client import RelationalClient

with RelationalClient(
    url="https://your-relational-endpoint.example.com",
    api_key="YOUR_API_KEY",
) as client:
    print(client.health_ready())
```

> **Warning**
>
> The SDK refuses to send an API key to a non-local endpoint that uses plaintext HTTP.
> Use HTTPS for authenticated remote deployments.
> API keys are removed when a redirect crosses origins.

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

`RelationalClient` does not read its URL or API key from the environment.
Pass both values explicitly, or have your application read its environment configuration before constructing the client:

```python
import os
from kumo_relational_client import RelationalClient

client = RelationalClient(
    url=os.environ["KUMO_RELATIONAL_API_ENDPOINT"],
    api_key=os.environ.get("KUMO_RELATIONAL_API_KEY"),
)
```

#### Configure the engine and explanation summaries

The following environment variables configure the underlying engine and optional explanation summary.
They do not configure `RelationalClient` itself.

| Environment variable                   | Purpose                                                                                                    |
| -------------------------------------- | ---------------------------------------------------------------------------------------------------------- |
| `KUMO_RELATIONAL_API_ENDPOINT`         | Endpoint fallback for direct `kumo_relational_engine` initialization. `RelationalClient` does not read it. |
| `KUMO_RELATIONAL_API_KEY`              | API-key fallback for direct `kumo_relational_engine` initialization. `RelationalClient` does not read it.  |
| `KUMO_RELATIONAL_DISABLE_SESSIONS`     | Disables relational session reuse when set to `1`, `true`, `yes`, or `on`, case-insensitively.             |
| `KUMO_RELATIONAL_EXPLAIN_LLM_API_KEY`  | Dedicated key that enables explanation-summary generation.                                                 |
| `KUMO_RELATIONAL_EXPLAIN_LLM_BASE_URL` | OpenAI-compatible explanation-summary endpoint.                                                            |
| `KUMO_RELATIONAL_EXPLAIN_LLM_MODEL`    | Model used to generate explanation summaries.                                                              |
| `KUMO_RELATIONAL_EXPLAIN_LLM_TIMEOUT`  | Explanation-summary request timeout.                                                                       |
| `KUMO_RELATIONAL_LOG`                  | SDK log level.                                                                                             |

#### Reuse a client across multiple requests

To avoid opening a new HTTP connection for every request, create one client and close it after the final request:

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

result = client.relational(graph).predict(query, run_mode="fast")

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

Construct a new client instead of reusing a closed one.

`RelationalClient(timeout=..., max_retries=...)` applies the timeout and transport-level retry policy to both the main `RelationalClient` transport and Kumo Relational transport.
A response body larger than 64 MiB is rejected.

## 4. Inspect client capabilities

Inspect the capability metadata exposed by the client-side Kumo Relational adapter, the part of the SDK that provides model-specific operations:

```python
from kumo_relational_client import RelationalClient

with RelationalClient(url="http://localhost:8000") as client:
    print(client.capabilities("kumo-relational"))
```

> **Note**
>
> The client supports one model.
> `models()` returns `['kumo-relational']`, and `capabilities('kumo-relational')` describes the client-side adapter.
> Neither method queries the NIM's `/v1/models` endpoint.

## Next steps

* [Run the Kumo Relational quickstart](/kumo-relational/get-started/rfm)
* [Prepare your data](/kumo-relational/user-guide/prepare-data/data-requirements)
* [Build a graph](/kumo-relational/user-guide/build-a-relational-graph/graph-creation)
* [Make predictions](/kumo-relational/user-guide/make-predictions/make-predictions)
* [Review the Python API Reference](/kumo-relational/reference/python-api-reference)