> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.nvidia.com/sdgm/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.nvidia.com/sdgm/_mcp/server.

# Prediction Explainability

> Configure and request Kumo Relational prediction explanations

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

The example requires a validated `graph` and a reachable Kumo Relational NIM endpoint.
Refer to [Deploy, Install, and Connect](/kumo-relational/get-started/sdk-getting-started) and [Graph Validation](/kumo-relational/user-guide/build-a-relational-graph/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:

```bash
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](#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:

```bash
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                         |

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

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

```python
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](/kumo-relational/user-guide/explain-predictions/understand-explanations) for interpretation guidance.