Python API Reference

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.

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 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.

For managed serving endpoints, use the supported constructors instead of assembling authentication headers manually. Install the corresponding databricks-serving or snowflake-serving extra first.

databricks_client = RelationalClient.for_databricks_serving(
    endpoint="<endpoint-name>",
    workspace_client=workspace_client,
)
snowflake_client = RelationalClient.for_snowflake_serving(
    service="<service-name>",
    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:

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

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.

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

The query is required. Use the remaining arguments only when you need to select particular entities or change prediction behavior.

Core prediction arguments

Time and context arguments

These arguments control which data the model can use and how far it traverses the graph.

Output and inference arguments

These arguments control inference execution and the returned result.

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. 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.

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 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:

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.