Migrate to Kumo Relational Client 1.0

Use this guide if your application depends on the earlier nemotron-* packages or on client APIs removed in Kumo Relational Client 1.0. Version 1.0 renames the client, engine, connectors, and model identifier, and it removes the tabular model surface and public adapter registry. Complete each section before running your existing prediction workflows against the new client.

Update package names

Install the client and its supported dependencies for relational prediction:

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

The client, connectors, and engine are released together and share version 1.0.0. Keep their versions aligned when pinning the distributions separately.

Update imports and the client class

Replace imports from the earlier packages with imports from kumo_relational_client. The following example assumes that your application already defines tables, query, and entity_ids:

from kumo_relational_client import RelationalClient, relational
graph = relational.Graph.from_data(tables)
with RelationalClient(url="http://localhost:8000") as client:
    result = client.relational(graph).predict(query, indices=entity_ids)

Use kumo_relational_client.relational to build the graph that describes your tables and their relationships. Standard applications should not import or initialize kumo_relational_engine directly.

Update the model identifier

The only accepted model identifier is kumo-relational:

client.capabilities("kumo-relational")

The identifiers tabicl, kumo-rfm, nemotron-relational, and nemotron-relational-v1 are not aliases and are rejected. Calls through client.relational(graph) select the correct identifier automatically.

Remove registry-based integration code

If your application registers custom model adapters, remove that integration code. Version 1.0 removes ModelAdapter, AdapterRegistry, the registry= constructor argument, and client registration methods. Construct RelationalClient without a registry and run predictions through the object returned by client.relational(graph).

The tabular client surface and client.tabular() are also removed. Version 1.0 supports Kumo Relational only, and client.models() returns:

['kumo-relational']

Update error handling

Catch errors returned through RelationalClient with RelationalError, then branch on the error’s stable code:

from kumo_relational_client import RelationalError
try:
    result = client.relational(graph).predict(query)
except RelationalError as error:
    print(error.code)

Package-specific error roots are kumo_relational_engine.KumoRelationalError and kumo_connectors.ConnectorError. Connection failures such as authentication, timeout, and unreachable-endpoint failures are translated to the RelationalError hierarchy when returned through the client.

Review behavior changes

Before upgrading production workflows, check your code and tests for each of these changes:

• Multiclass CLASS values preserve the target column’s data type instead of always becoming strings.
• Unknown inference_config keys are rejected instead of silently dropped.
• edges=[] means no relationships and suppresses relationship inference; use edges=None to allow declared or inferred relationships.
• RelationalClient(max_retries=...) also controls transient retries on the relational transport.
• Authenticated non-local endpoints must use HTTPS.
• A closed RelationalClient cannot be reused.

After updating, run a representative prediction for each task type and verify the task-dependent result shapes described in Prediction Results.