> This page is for Kumo Engine.

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

# XAI in Supply Chain

> Build a planning workflow that connects Kumo forecasts to relational evidence, useful comparisons, and operator decisions.

Explainable AI (XAI) can help supply chain operators understand how demand forecasts inform changes to next week's production plan.
Before making that change, a planner needs to understand why the estimate deserves attention, which records support it, and what to verify next.
A recommendation or prediction alone leaves that investigation to the operator, limiting its usefulness.

Data scientists and ML engineers can build the investigation into the planning workflow with Kumo Engine.
Engine predicts future quantities by learning from an entity's history and its connected records, such as other products sharing a plant or storage location.

Its explainability tools expose model sensitivity, differences between groups of examples, and retained relational context for selected test predictions.
Your application combines those diagnostics and source records into an explanation the planner can inspect, challenge, and share.

Consider an illustrative case: **Product A's next seven days of sales orders are predicted to exceed its recent weekly order volume.**
The application flags it when the difference from its previous seven-day order total exceeds a configured review threshold.
The planner asks whether that increase warrants a production-plan review.

## What Kumo brings to the investigation

Useful supply chain evidence often spans several tables.
Product A's order history may be short, while products sharing its group, plant, or storage location provide additional context.

Kumo Engine builds time-bounded relational neighborhoods and trains a temporal heterogeneous graph neural network on that context.
You define what to predict, for which products, and over what time horizon through a predictive query.
Engine handles the connected model inputs and learning workflow.

| Kumo capability                 | What you build with it                                                                                  |
| ------------------------------- | ------------------------------------------------------------------------------------------------------- |
| Relational context generation   | A forecast that can learn from Product A's history and connected products' histories.                   |
| Predictive Query Language (PQL) | An explicit target, product, and time horizon shared by training and evaluation.                        |
| Retained model diagnostics      | An investigation that connects model sensitivity, group behavior, and selected examples' input records. |

Test whether related-product history improves Product A's forecast beyond its own history.
Explainability then helps you investigate what the model learned from that context.

## Define the forecast before explaining it

This example uses [SupplyGraph](https://arxiv.org/pdf/2401.15299).
It provides an anonymized starting dataset: daily production, sales orders, deliveries, and factory outbound shipments for 41 products during January through August 2023, with product group, plant, and storage relationships.

A shared plant represents a relationship between products, not a material-flow dependency.
The dataset's “factory issues” are outbound shipments, not factory faults.

Reshape the data into a `products` table and timestamped `product_days` rows linked by product ID, retaining the membership relationships.
These are example names for the prepared schema:

```sql
PREDICT SUM(product_days.sales_order_units, 0, 7, days)
FOR EACH products.product_id
```

This predicts **observed sales-order quantity over the next seven days**, in units.
It does not estimate unmet demand or determine whether inventory will cover orders.
Use a fixed-window regression task for this workflow, which supports gradient, cohort, and sampled-graph diagnostics when the relevant artifacts are generated.

Evaluate on later dates than those used for training.
For each reviewed example, preserve the product identity, prediction cutoff, predicted quantity, and eventual observed quantity.
Keep records from the target window out of the model's input context.

## Investigate the higher estimate

Start with a retained test prediction for Product A that has a usable entity mapping.
Build three connected evidence views, each answering a different question.

* **What does the model respond to?** Use retained gradient scores to identify sensitive input columns, such as historical sales-order quantities.
  These scores aggregate absolute sensitivity across examples.
  They help choose what to investigate, but do not say whether a particular record raised Product A's estimate or by how many units.
* **Where does that pattern hold?** Use cohorts to compare mean predictions, observed targets, and representation across product groups or related records.
  For example, inspect whether higher estimates in Product A's group correspond to higher observed orders in the held-out period, or whether the model consistently overestimates that group.
* **What did this example contain?** Open Product A's retained sampled neighborhood and inspect its timestamped records and linked products.
  If local cell scores are available, use them to prioritize inspection within that sample.
  Require an unambiguous mapping from sampled entities to original products and source records before presenting a finding as traceable.

Keep model-wide findings separate from evidence for Product A.
A high gradient for order history motivates investigation; the actual sampled records establish which history was present for this example.

A missing diagnostic should appear as missing evidence.
Reading retained training artifacts does not generate attribution for an arbitrary new prediction.

## Make the explanation contrastive

Planners rarely ask only “why this number?”
They ask “why does Product A need review while a similar product does not?”

Select Product B using an explicit comparison rule: the same cutoff, comparable recent order volumes, a shared product group, and a forecast within the review threshold.
Choose it from information available at that cutoff, before looking at future outcomes.
Show the following comparison:

* **Forecast difference:** Product A and Product B's predicted seven-day orders, each beside its own recent-history baseline.
* **Recorded difference:** their recent order patterns and relevant connected histories, linked to dated source rows.
* **Model evidence:** available findings that support investigating those differences, with their scope visible.
* **Outcome check:** how both estimates compared with observed orders once the seven days passed.

This comparison gives the planner more to discuss with sales or production than a generic importance chart.
Similar records help frame the question; similarity alone does not prove why the model produced different estimates.

## Put a usable answer in the planner's workflow

Lead the review card with the forecast and a short explanation.
Keep the evidence expandable.
Separate the reason for review from the history to investigate.

When the records and diagnostics support these findings, use a summary such as:

> **What needs attention?** Product A's next-week order estimate is above its recent weekly volume.
>
> **Why?** Model-wide sensitivity scores highlight order history.
> Product A's sampled records show rising orders for it and related products; Product B's history is steadier.
>
> **What can we do about it?** Confirm the latest orders with sales, then check stock and capacity before revising production.

Below the summary, provide the forecast quantity and cutoff, the comparison, the supporting records, available model diagnostics, and relevant held-out errors.
A planner can correct a stale input, question the comparison, or forward the evidence to a colleague.
The application assembles this evidence packet; the planner makes the production decision.

## Build, check, and extend the same workflow

Start with a workbench for mapped held-out examples.
Verify that input evidence belongs to the selected example and was available by its cutoff; show subsequent outcomes separately.

Compare predictive error against recent-history and own-history-only baselines to establish whether connected context adds value.
Test whether planners can recognize unsupported conclusions and identify a deliberately wrong forecast.

Implement a replay adapter to test specific explanation claims against the frozen model.
Change plausible historical inputs while holding the cutoff and sampling conditions fixed, and compare the response against matched random or low-influence changes.
This tests model behavior, not the effect of a real-world production intervention.

Extend the evidence packet when more operational data is available:

* **Coverage review:** add dated usable inventory, receipts, reservations, and production requirements; calculate exposure from those records and the forecast.
* **Planning advisory:** let a language-model agent retrieve approved documents and summarize the packet.
  Keep numerical forecasts owned by the predictive model, preserve source references, and surface missing or conflicting evidence.

For diagnostic support and artifact access, see [Model Explainability](/sdgm/kumo-engine/user-code-guide/train-a-model/model-explainability).