Prediction Explainability | NVIDIA Structured Data and Graph Models

Use prediction explanations to inspect the data patterns and related records associated with a result. Set explain=True to return the prediction and its machine-readable attribution data in an Explanation object. Each explanation request supports one prediction entity, such as one customer, and can optionally include a natural-language summary.

Set up explainability

This page assumes that you have a validated graph and the URL of a running Kumo Relational NVIDIA Inference Microservice (NIM), the service that runs predictions. Refer to Deploy, Install, and Connect and Graph Validation to complete those prerequisites.

The NIM returns the structured explanation, including cohort analysis of context examples and attribution data for related records in a local subgraph. If the NIM does not include a natural-language summary, the SDK can request one from a separately configured model endpoint.

Install the NVIDIA Kumo Relational Client with the relational and explanation dependencies:

python -m pip install "kumo-relational-client[relational,explain]"

If you install the packages from a running notebook, restart the kernel.

If you only need structured attribution, you do not need to configure a summary model. No summary request is made when the dedicated API key is absent, the explain extra is not installed, or explain={"skip_summary": True} is used. Refer to Skip summary generation.

Configure optional summaries

To generate a natural-language summary, configure a model served through an OpenAI-compatible chat-completions endpoint.

Set the endpoint, API key, and model wherever you manage environment variables for the SDK process:

export KUMO_RELATIONAL_EXPLAIN_LLM_API_KEY="<api-key>"
export KUMO_RELATIONAL_EXPLAIN_LLM_BASE_URL="https://<openai-compatible-endpoint>/v1"
export KUMO_RELATIONAL_EXPLAIN_LLM_MODEL="<model-name-served-by-the-endpoint>"

The following environment variables control summary generation:

Environment variable	Description	Required
`KUMO_RELATIONAL_EXPLAIN_LLM_API_KEY`	API key accepted by the summary endpoint; setting this variable enables summary generation.	Yes, to generate summaries
`KUMO_RELATIONAL_EXPLAIN_LLM_BASE_URL`	Base URL of an OpenAI-compatible chat-completions endpoint; defaults to the OpenAI endpoint.	For a custom endpoint
`KUMO_RELATIONAL_EXPLAIN_LLM_MODEL`	Model identifier accepted by the configured endpoint; defaults to `gpt-4.1-mini-2025-04-14` when no custom endpoint is configured.	For a custom endpoint
`KUMO_RELATIONAL_EXPLAIN_LLM_TIMEOUT`	Summary request timeout in seconds; defaults to `20`.	No

Summary generation is separate from Kumo Relational NIM prediction. It sends the predictive query, prediction, cohort analysis, and first subgraph returned to the configured model endpoint. Select an endpoint that meets your organization’s security, privacy, and data governance requirements.

Request an explanation

The following Predictive Query Language (PQL) request predicts the total order amount for customer 42 over the next 30 days. The indices list contains one ID because explanation requests support only one prediction entity at a time.

from kumo_relational_client import RelationalClient
query = (
    "PREDICT SUM(orders.amount, 0, 30, days) "
    "FOR EACH customers.customer_id"
)
with RelationalClient(url="http://localhost:8000") as client:
    explanation = client.relational(graph).predict(
        query,
        indices=[42],
        run_mode="fast",
        explain=True,
    )
predictions = explanation.prediction
cohorts = explanation.cohorts
subgraphs = explanation.subgraphs
summary = explanation.summary

Use run_mode="fast" for explanation requests. If you specify normal or best, the SDK resets the request to fast and issues a warning.

Work with the result

An Explanation object contains the following attributes:

prediction: The original prediction DataFrame.
details: The complete machine-readable explanation payload.
cohorts: Aggregated patterns for column values in the context examples, when present.
subgraphs: Related rows, cells, and relationships with their attribution values, when present.
summary: A natural-language explanation or an actionable setup or connection message.
warning: A warning returned with the explanation, when present.

The structured explanation remains available if summary generation is not configured, times out, or fails.

Skip summary generation

To return structured attribution without requesting a natural-language summary, set skip_summary to True in the explain dictionary:

with RelationalClient(url="http://localhost:8000") as client:
    explanation = client.relational(graph).predict(
        query,
        indices=[42],
        explain={"skip_summary": True},
    )

Troubleshoot explainability

The explain extra is missing: Install kumo-relational-client[relational,explain] and restart the notebook kernel.
An API key is missing: Set KUMO_RELATIONAL_EXPLAIN_LLM_API_KEY. Ambient provider-specific API keys are intentionally ignored.
A custom endpoint has no model: Set KUMO_RELATIONAL_EXPLAIN_LLM_MODEL to a model identifier served by that endpoint.
Summary generation times out: Increase KUMO_RELATIONAL_EXPLAIN_LLM_TIMEOUT or select a faster model.
The endpoint rejects the request: Verify the base URL, API key, and model identifier. The structured cohorts and subgraphs remain available.
The Kumo Relational NIM is temporarily unavailable: Wait and retry. Explanation requests are GPU intensive, so send them one at a time.

See Understand Explanations for interpretation guidance.