> 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 SDK API > Public Python interfaces for connecting to a Kumo Relational NIM Install the SDK and any data-source extras by following [Deploy, Install, and Connect](/rfm/sdk-getting-started). This reference documents the public Python interfaces supported for Kumo Relational. 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 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: ```python databricks_client = RelationalClient.for_databricks_serving( endpoint="", workspace_client=workspace_client, ) snowflake_client = RelationalClient.for_snowflake_serving( service="", 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`: ```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()` ```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", ) ``` | 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](/rfm/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: ```python 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`: ```python 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.