Skip to navigation
Get Started

Quickstart: Kumo Relational Client

View as Markdown

Use the Kumo Relational Client to prepare a prediction request and send it to a Kumo Relational NIM. In this quickstart, you build a relational graph from local pandas DataFrames, bind it to RelationalClient, and receive predictions from the deployed model. Model inference runs in the NIM.

The small tables are for API verification only. They do not contain enough historical examples to assess prediction quality.

Before you begin

You need:

  • A Python environment that meets the client requirements.
  • The URL of a running Kumo Relational NIM that your environment can reach.
  • An API key if a gateway in front of the NIM requires authentication.

If you do not have a reachable NIM endpoint, follow Deploy, Install, and Connect first.

1. Install the SDK

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

2. Prepare relational data

import pandas as pd
users = pd.DataFrame({
    "user_id": [1, 2, 3],
    "signup_date": pd.to_datetime(["2024-01-01", "2024-02-15", "2024-03-20"]),
})
orders = pd.DataFrame({
    "order_id": [101, 102, 103, 104],
    "user_id": [1, 1, 2, 3],
    "price": [50.0, 30.0, 100.0, 75.0],
    "timestamp": pd.to_datetime([
        "2025-01-10", "2025-02-15", "2025-01-20", "2025-03-05"
    ]),
})

3. Build a graph

Import the relational module, the SDK interface that constructs a Kumo Relational graph, and then infer the graph from the tables:

from kumo_relational_client import relational
graph = relational.Graph.from_data({
    "users": users,
    "orders": orders,
})
graph.validate()

For production data, review the inferred table metadata and relationships before running predictions. Refer to Build a Graph.

4. Run a prediction

The sample query asks whether user 1 will place at least one order during the next 30 days. Bind the graph to the client so the prediction can use the tables and their relationships, then send the query to your NIM endpoint:

This standalone example uses a context manager to create and close the client. For an application or notebook that makes multiple requests, follow the reusable client pattern.

from kumo_relational_client import RelationalClient
query = "PREDICT COUNT(orders.*, 0, 30, days) > 0 FOR users.user_id=1"
with RelationalClient(url="http://localhost:8000") as client:
    result = client.relational(graph).predict(query, run_mode="fast")
print(result)

Replace http://localhost:8000 with your NIM endpoint URL if it runs elsewhere.

A successful request returns a pandas DataFrame with an ENTITY column and, for this single-value prediction, a PREDICTION column. A temporal request also includes ANCHOR_TIMESTAMP. The prediction value depends on the deployed model and the supplied context.

Pass api_key to RelationalClient if a gateway in front of your deployment requires authentication.

Next steps