Deploy, Install, and Connect

The NVIDIA Kumo Relational Client is a Python SDK for sending relational prediction requests to the Kumo Relational NVIDIA Inference Microservice (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 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 1.0 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. 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

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. Its published wheels target Linux x86-64, use the manylinux_2_28 platform tag, and support CPython 3.10 through 3.13. Because no engine source distribution is published, you cannot install the [relational] extra directly on macOS.

For a standard Kumo Relational workflow on supported Linux x86-64, install the SDK with the relational engine:

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

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.

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:

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())

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:

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"),
)

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()

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:

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

Next steps

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