Prediction Results | NVIDIA Kumo

client.relational(graph).predict() returns Kumo Relational prediction results as a pandas DataFrame. The DataFrame columns and number of rows depend on the prediction task. Every result includes ENTITY, the identifier of the target entity from the prediction input. Predictions tied to a specific point in time can also include ANCHOR_TIMESTAMP, the time from which the prediction is made. Use these identifier fields to join predictions to downstream data instead of relying on row position.

The following example assumes that graph describes the connected input tables and query contains the prediction request. run_mode="fast" explicitly selects the default inference mode.

from kumo_relational_client import RelationalClient
with RelationalClient(url="http://localhost:8000") as client:
    result = client.relational(graph).predict(query, run_mode="fast")
print(result.columns)
print(result.head())

Result fields

The fields that are present depend on the prediction task and the requested outputs.

Field	When present	Description
`ENTITY`	All Kumo Relational results	Identifier of the target entity from the prediction input.
`ANCHOR_TIMESTAMP`	When an anchor time is available	Time from which the prediction is made; together with `ENTITY`, it identifies a time-specific prediction input.
`PREDICTION`	Binary classification and regression results	Predicted Boolean or numeric value.
`<CLASS>_PROB`	Binary-classification probabilities	Probability for the named Boolean class, such as `TRUE_PROB`.
`CLASS`	Multiclass and link-prediction results	Class value or identifier of an entity ranked as a possible link, with the target or identifier dtype preserved by the SDK.
`SCORE`	Multiclass and link-prediction results	Score for the class or candidate in the same row.
`PREDICTED`	Multiclass results	`True` for the winning class and `False` for the other candidate classes.
`FORECAST_STEP`	Forecast results	One-based sequence number of the forecast period.
`SCORES`	Other score outputs	Ordered score values returned by the model.
`Q_<Level>`	Quantile outputs	Predicted value at the specified quantile level; available levels depend on the requested outputs.
`EMBEDDINGS`	When embeddings are requested	Model embedding values.

Do not assume that every task returns every field or one row per input entity. The result shape varies by task:

Binary classification and regression: One row per entity.
Multiclass classification: One row per entity per class.
Temporal link prediction: One row per ranked candidate.
Forecasting: One row per entity per forecast period.

Inspect the returned DataFrame columns before processing optional outputs. For REST integrations, also check the capabilities of the deployed NVIDIA NIM model.

The Python SDK DataFrame uses uppercase PREDICTION. The NVIDIA NIM REST response uses lowercase prediction in each prediction item. Refer to NIM REST API when working with the REST response directly.

Illustrative shapes

Compare these examples to find the columns and row pattern for your task. They show only the column structure; the values depend on the query and the deployed release.

Scalar regression

   ENTITY      ANCHOR_TIMESTAMP  PREDICTION
0      42  2025-01-01T00:00:00Z      128.40

Boolean classification

   ENTITY  PREDICTION  FALSE_PROB  TRUE_PROB
0      42        True        0.21       0.79

Multiclass classification

   ENTITY      ANCHOR_TIMESTAMP       CLASS  SCORE  PREDICTED
0      42  2025-01-01T00:00:00Z  enterprise   0.73       True
1      42  2025-01-01T00:00:00Z      public   0.15      False
2      42  2025-01-01T00:00:00Z       small   0.12      False

Filter the winning row for each entity with result[result["PREDICTED"]]. Do not coerce CLASS to a string because it preserves the target column’s dtype.

Forecasting

   ENTITY      ANCHOR_TIMESTAMP  PREDICTION  FORECAST_STEP
0      42  2025-01-01T00:00:00Z      128.40              1
1      42  2025-01-01T00:00:00Z      134.75              2
2      42  2025-01-01T00:00:00Z      141.20              3

A forecasting result contains one row per entity per forecast step. FORECAST_STEP is one-based.

Temporal link prediction with three ranked candidates

   ENTITY      ANCHOR_TIMESTAMP  CLASS  SCORE
0      42  2025-01-01T00:00:00Z  sku-7   0.91
1      42  2025-01-01T00:00:00Z  sku-3   0.84
2      42  2025-01-01T00:00:00Z  sku-9   0.72

A prediction query with RANK TOP 3 returns three possible linked entities for each input entity, ordered from the highest-scoring candidate to the lowest.

Preserve the returned row order when presenting ranked candidates for the same entity.

Explanations

When explain=True, predict() returns an Explanation object instead of a bare DataFrame. Its prediction attribute contains the prediction DataFrame, details contains the complete machine-readable explanation data, and summary contains natural-language text when the backend provides it. See Prediction Explainability.