> 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. # Python API Reference > Public Python interfaces for connecting to and running predictions with Kumo Relational This reference documents the public Python interfaces for connecting to Kumo Relational, loading data, creating a graph handle, running predictions, and handling errors. Before using these interfaces, install the SDK and any data-source extras by following [Deploy, Install, and Connect](/kumo-relational/get-started/sdk-getting-started). Import the supported public interfaces from `kumo_relational_client`: ```python from kumo_relational_client import RelationalClient, relational ``` ## `RelationalClient` ```text 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 one NIM endpoint. Use it as a context manager when the client is needed only for a specific block of code. 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, so construct a new client instead of attempting to reuse a closed one. The SDK supports only the `kumo-relational` model and 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']` without calling the remote `/v1/models` endpoint. | | `capabilities(model)` | Returns the tasks, outputs, and request types from client-side metadata without calling 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. Install the corresponding `databricks-serving` or `snowflake-serving` extra first. ```python databricks_client = RelationalClient.for_databricks_serving( endpoint="", workspace_client=workspace_client, ) snowflake_client = RelationalClient.for_snowflake_serving( service="", session=session, ) ``` 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. Do not mix direct `kumo_relational_engine.init()` calls with `RelationalClient` usage in the same process. ## `read()` Use the root-level `read()` function when you need to load one flat table into a pandas DataFrame without connecting a `RelationalClient`: ```python 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") ``` ```text 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()` The `predict()` method runs a prediction defined by a Predictive Query Language (PQL) statement against a graph. PQL is Kumo's query language for specifying what to predict. ```text 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: ```python with RelationalClient(url="http://localhost:8000") as client: result = client.relational(graph).predict( query, indices=[42, 57, 81], run_mode="fast", ) ``` The `query` is required. Use the remaining arguments only when you need to select particular entities or change prediction behavior. ### Core prediction arguments | Argument | Description | | ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `query` | A Predictive Query Language (PQL) statement. | | `indices` | Optional entity primary-key values for which to generate predictions. | | `run_mode` | Sets the Kumo Relational inference run mode, which defaults to `fast`. | | `explain` | Requests an explanation for one entity and 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, and differs from the client's transport-level `max_retries`. | ### Time and context arguments These arguments control which data the model can use and how far it traverses the graph. | Argument | Description | | --------------------- | ------------------------------------------------------------------------------------------------- | | `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, with `num_neighbors` taking precedence when both are provided. | ### Output and inference arguments These arguments control inference execution and the returned result. | Argument | Description | | ------------------- | ----------------------------------------------------------------- | | `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, with `False` suppressing it. | Refer to [Configuration](/kumo-relational/user-guide/configure-and-scale/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. A graph describes the tables and relationships that Kumo Relational uses for prediction. Create one 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. > **Warning** > > 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: ```python from kumo_relational_client.errors import RelationalError from kumo_relational_engine import KumoRelationalError from kumo_connectors import ConnectorError ``` Catch `RelationalError` around calls made through `RelationalClient`, then inspect its `code` attribute to determine the failure type. 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`: ```python from kumo_relational_engine import ( AuthenticationError, GraphConstructionError, NimTimeoutError, NimUnreachableError, ) ``` Relational validation failures returned through `RelationalClient` 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`. 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.