> 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

Set `explain=True` to return a prediction and its structured attribution in an `Explanation` object. Explainability supports a single prediction entity per request. Natural-language summaries are optional.

## Set up explainability

The Kumo Relational NIM returns the structured explanation. If the NIM does not include a natural-language summary, the SDK can generate one by using 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.

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. This is the only environment variable that enables summary generation.                     | Yes, to generate summaries |
| `KUMO_RELATIONAL_EXPLAIN_LLM_BASE_URL` | Base URL of an OpenAI-compatible chat-completions endpoint. If omitted, the OpenAI endpoint is used.                                 | For a custom endpoint      |
| `KUMO_RELATIONAL_EXPLAIN_LLM_MODEL`    | Model identifier accepted by the configured endpoint. If no custom endpoint is configured, the default is `gpt-4.1-mini-2025-04-14`. | For a custom endpoint      |
| `KUMO_RELATIONAL_EXPLAIN_LLM_TIMEOUT`  | Summary request timeout in seconds. The default is `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.

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).

## Request an explanation

```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 structured explanation payload;
* `cohorts`: column-level cohort analysis, when present;
* `subgraphs`: subgraph attribution, when present;
* `summary`: a natural-language explanation or an actionable setup or connection message; and
* `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](/rfm/understand-explanations) for interpretation guidance.