Python SDK API | NVIDIA Structured Data and Graph Models

Install the SDK and any data-source extras by following Deploy, Install, and Connect. This reference documents the public Python interfaces supported for Kumo Relational.

Import the supported public interfaces from kumo_relational_client:

from kumo_relational_client import RelationalClient, relational

`RelationalClient`

RelationalClient(
    url: str,
    api_key: str | None = None,
    *,
    verify_ssl: bool = True,
    timeout: float = 60.0,
    max_retries: int = 3,
)

A RelationalClient manages a connection to a single NIM endpoint. Use it as a context manager for a scoped sequence of requests. For an application or notebook that makes multiple requests, create one client, reuse it, and call close() when finished. Calling close() retires the client permanently; construct a new client instead of attempting to reuse a closed one.

The SDK supports one model, kumo-relational. It does not expose a public adapter registry or model-registration extension point.

Method	Description
`health_ready()`	Checks whether the NIM is ready to serve requests.
`models()`	Returns `['kumo-relational']`. It does not call the remote `/v1/models` endpoint.
`capabilities(model)`	Returns the tasks, outputs, and request types supported by the named model. It reads client-side metadata and does not call the NIM.
`relational(graph)`	Returns a Kumo Relational model handle bound to the `graph`.
`close()`	Releases pooled connections and permanently retires the client.

For managed serving endpoints, use the supported constructors instead of assembling authentication headers manually:

databricks_client = RelationalClient.for_databricks_serving(
    endpoint="<endpoint-name>",
    workspace_client=workspace_client,
)
snowflake_client = RelationalClient.for_snowflake_serving(
    service="<service-name>",
    session=session,
)

Install the corresponding databricks-serving or snowflake-serving extra first.

Several clients can target different endpoints or tenants concurrently, including from multiple threads. Each prediction remains bound to the endpoint and credential of the client that started it. The underlying relational engine also maintains process-wide configuration, so do not mix direct kumo_relational_engine.init() calls with RelationalClient usage in the same process.

`read()`

Use the root-level read() function to load one flat table into a pandas DataFrame without creating a RelationalClient:

from kumo_relational_client import read
local_frame = read("local", path="customers.parquet")
s3_frame = read("s3", path="s3://my-bucket/customers.parquet")
sqlite_frame = read("sqlite", database="data.db", table="customers")

read(source: str, **kwargs) -> pandas.DataFrame

source can be local, s3, sqlite, duckdb, snowflake, or databricks. Local and S3 reads accept CSV and Parquet data. SQL sources require exactly one of table= or query= plus the connection arguments for that backend. Install the corresponding connector extra, such as kumo-relational-client[s3] or kumo-relational-client[duckdb], before using an optional backend.

`client.relational(graph).predict()`

client.relational(graph).predict(
    query: str,
    indices: Sequence | None = None,
    *,
    run_mode: str = "fast",
    explain: bool | ExplainConfig | dict = False,
    batch_size: int | "max" | None = None,
    num_retries: int = 1,
    anchor_time = ...,
    context_anchor_time = ...,
    use_prediction_time = ...,
    lag_timesteps = ...,
    num_neighbors = ...,
    num_hops = ...,
    inference_config = ...,
    return_embeddings = ...,
    random_seed = ...,
    max_pq_iterations = ...,
    verbose = ...,
)

client.relational(graph) returns a lightweight handle bound to the graph. Call its predict() method with a PQL query and any prediction settings:

with RelationalClient(url="http://localhost:8000") as client:
    result = client.relational(graph).predict(
        query,
        indices=[42, 57, 81],
        run_mode="fast",
    )

Argument	Description
`query`	A Predictive Query Language (PQL) statement.
`indices`	Optional entity primary-key values for which to generate predictions.
`run_mode`	Kumo Relational inference run mode. The default is `fast`.
`explain`	Requests an explanation for one entity. Returns an `Explanation` object instead of a bare DataFrame.
`batch_size`	Splits entities into batches when set to a positive integer or `"max"`.
`num_retries`	Sets application-level retries for a failed relational prediction request or batch, including a request that resolves to one batch. This differs from the client’s transport-level `max_retries`.
`anchor_time`	Sets the prediction reference time.
`context_anchor_time`	Sets the maximum context reference time separately from the prediction anchor time.
`use_prediction_time`	Includes the prediction timestamp as an input feature.
`lag_timesteps`	Includes previous target windows as lagged features.
`num_neighbors`	Sets the maximum neighbor fan-out for each graph hop.
`num_hops`	Sets graph depth from 1 through 6. `num_neighbors` takes precedence when both are provided.
`inference_config`	Configures inference-time ensembling and output behavior.
`return_embeddings`	Includes model embeddings in the result.
`random_seed`	Sets the seed used for sampling and request materialization.
`max_pq_iterations`	Sets the maximum iterations used to collect valid context labels.
`verbose`	Controls prediction progress output. Set to `False` to suppress it.

Refer to Configuration for defaults, accepted values, and examples. The client uses the X-API-Key header when api_key is set. It refuses to send the key to a non-local endpoint that uses plaintext HTTP.

By default, predict() returns a pandas DataFrame. When explain is enabled, it returns an Explanation object with prediction, details, and summary attributes.

The model handle caches the most recently materialized graph per thread. In-place edits to a table’s data after its first prediction are not included in later predictions; rebuild the graph to use the new values. Schema changes, including added or removed tables, columns, or links, are detected.

Graph and table interfaces

The relational module imported from kumo_relational_client provides the supported graph interface. Create a graph with relational.Graph.from_data() or a connector-backed Graph.from_*() factory. Then, bind the graph by calling client.relational(graph).

You do not need to construct table objects directly. Access graph["table_name"] only when you need to inspect or correct inferred keys, timestamps, or semantic types.

Run inference through client.relational(graph).predict(...). Standard applications do not construct internal request objects or directly initialize and authenticate the underlying Kumo Relational driver.

Use relational.Graph to construct graphs.

Direct engine initialization and direct inference through an internal model object are not supported. Create RelationalClient, then bind the graph with client.relational(graph).

Errors

Import the three public error families from their owning packages:

from kumo_relational_client.errors import RelationalError
from kumo_relational_engine import KumoRelationalError
from kumo_connectors import ConnectorError

Catch RelationalError at the RelationalClient boundary and inspect its code attribute. Supported codes include INVALID_REQUEST, INVALID_CONFIGURATION, TRANSPORT_ERROR, INVALID_RESPONSE, UNSUPPORTED_FEATURE, UNKNOWN_MODEL, MISSING_EXTRA, INTERNAL_ERROR, SERVING_INIT_FAILED, DRIVER_LOAD_FAILED, and AUTHENTICATION_FAILED.

Typed relational connection and graph-construction failures are exported by kumo_relational_engine:

from kumo_relational_engine import (
    AuthenticationError,
    GraphConstructionError,
    NimTimeoutError,
    NimUnreachableError,
)

Relational validation failures crossing the RelationalClient boundary use RelationalError(code="INVALID_REQUEST"). This includes caller lookup failures such as a misspelled exclude_cols_dict entry. Malformed transport and create-session responses use INVALID_RESPONSE, while request transport failures use TRANSPORT_ERROR.

The root-level read() function translates connector failures into RelationalError with the codes UNKNOWN_CONNECTOR, INVALID_CONNECTOR_ARGS, CONNECT_FAILED, QUERY_FAILED, READ_FAILED, NOT_FOUND, or DRIVER_LOAD_FAILED. A missing optional driver raises MissingExtraError with MISSING_EXTRA. Calls made directly through kumo_connectors raise ConnectorError instead.

Internal request classes are not part of the supported root-level API. Run inference through client.relational(graph).predict(...) or predict_task(...); do not call direct engine initialization for standard inference.

Importing kumo_relational_engine does not configure the application’s root logger or open a connection. The package attaches logging behavior only to its own logger; create a RelationalClient explicitly when a connection is required.