Skip to content
Draft
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Original file line number Diff line number Diff line change
Expand Up @@ -199,7 +199,7 @@ def explain_prediction(
fit_mode_to_use=FitMode.fit,
root_dir=output_dir,
top_k=top_k,
collector_formats=['nested_json'],
collector_formats=['nested_json', 'output'],
cohort_rows=options.cohort_rows,
sample_rows=options.sample_rows,
)
Expand Down
3 changes: 3 additions & 0 deletions packages/kumo-core/tests/test_prediction_explanations.py
Original file line number Diff line number Diff line change
Expand Up @@ -97,6 +97,9 @@ def test_prediction_requires_producer_completion(replay):
result = run()
assert result.cohorts.status == result.samples.status == 'failed'
assert 'did not complete' in result.failure
# Each sampled graph keeps its recorded prediction beside it.
assert trainer.explain.call_args.kwargs['collector_formats'] == [
'nested_json', 'output']


@pytest.mark.parametrize('failed', ['cohorts', 'samples'])
Expand Down
19 changes: 17 additions & 2 deletions packages/kumo-engine/explainability.md
Original file line number Diff line number Diff line change
Expand Up @@ -13,6 +13,20 @@ The tuning metric opens first when recorded. Select another metric or toggle ind
Each point represents a recorded epoch. Missing scores leave gaps, and epochs from the later refit are excluded.
The widget reads `metric-history.json` from the published bundle or `auto_train_progress.json` from the retained run. The view appears when either source contains training or validation series.

Display `prediction.visualize()` for a batch prediction result to open the batch widget, with the same styling and graph controls on a single page.
It shows the batch, model and snapshot identities, a Cohorts chart with class selection and sampled subgraphs with their recorded predictions.
Cohort charts show average predictions and sampled population shares; a batch has no observed outcomes or evaluation metrics.
An unavailable, disabled, unsupported or failed producer is listed under **Explanation availability**, and the other producer's card still appears.

```python
prediction = trainer.predict(snapshot, explanations=True)
prediction.visualize()

# Reopen a retained prediction run, including its xai/manifest.json:
from kumo.engine import PredictionExplanations
PredictionExplanations.load("/path/to/prediction/run").visualize()
```

Use **Export PDF** to print every chart view on the currently open page, including All metrics, Epoch history and Against baselines where available, then choose **Save as PDF** in the browser dialog.
The export preserves the selected explanation and chart controls.
The other tab is excluded.
Expand All @@ -21,9 +35,10 @@ If the notebook blocks pop-ups, open the downloaded print page to save it as PDF
Neither export requires a running kernel after saving.

Call `.html()` on the returned view for self-contained HTML, or `.as_widget()` to request the optional anywidget transport explicitly.
The saved notebook snapshot includes the model summary, metrics and default Evaluation charts, followed by “To activate the widget, rerun this cell.”
The saved notebook snapshot includes the model summary, metrics and default Evaluation charts, or for a batch its identities, availability, default cohort chart and subgraph coverage, followed by “To activate the widget, rerun this cell.”
Individual subgraphs are omitted from that static snapshot.
Opening the widget only reads retained artifacts; it never starts training or prediction.
Opening either widget only reads retained artifacts; it never starts training, prediction or explanation generation.
Retain the prediction run separately from exported predictions; a bare export cannot supply its explanations.

## Access the selected training run

Expand Down
11 changes: 8 additions & 3 deletions packages/kumo-engine/kumo/engine/_explainability/__init__.py
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,8 @@
The data side reads the Kumo files a training run leaves on disk and computes
the chart values; the front end in ``static/`` draws them and derives the
cutoff statistics from the transported counts. Open it with
``TrainingResult.visualize()``, or ``open_run`` for a retained run.
``TrainingResult.visualize()`` or ``open_run`` for a retained run;
``PredictionResult.visualize()`` shows a batch's cohorts and subgraphs.
"""

import json
Expand All @@ -26,8 +27,9 @@
from kumo.engine._explainability._forecasting import forecast_card
from kumo.engine._explainability._regression import predicted_card
from kumo.engine._explainability._run import (
CLASSIFICATION,
FORECASTING,
LINK_PREDICTION,
REGRESSION,
Run,
load,
mapping,
Expand Down Expand Up @@ -72,7 +74,7 @@ def _static(name: str) -> str:
def script(model_type: str) -> str:
"""The shared front end, the model type's own cards, then the mount."""
names = ['charts.js', 'shell.js', 'epoch-history.js', 'exports.js']
if model_type != LINK_PREDICTION:
if model_type in (CLASSIFICATION, REGRESSION, FORECASTING):
names.append(f'{model_type}.js')
if model_type != FORECASTING:
names.append('subgraphs.js')
Expand Down Expand Up @@ -110,6 +112,9 @@ def __init__(self, result: 'TrainingResult') -> None:
@cached_property
def data(self) -> dict[str, Any]:
"""The payload the front end draws."""
return self._build()

def _build(self) -> dict[str, Any]:
return build(load(self._result))

@property
Expand Down
74 changes: 48 additions & 26 deletions packages/kumo-engine/kumo/engine/_explainability/_columns.py
Original file line number Diff line number Diff line change
Expand Up @@ -36,6 +36,8 @@ def cohorts(run: Run) -> Optional[list[ColumnCohorts]]:
if (run.model_type not in (CLASSIFICATION, REGRESSION) or analysis is None
or analysis.task_type.value != run.task_type):
return None
if run.batch:
return analysis.cohorts or None
entries = [c for c in analysis.cohorts if c.targets is not None]
return entries if any(e.prediction_score > 0 for e in entries) else None

Expand Down Expand Up @@ -112,44 +114,63 @@ def importance(run: Run) -> Optional[dict[str, Any]]:
def group_view(run: Run, entry: ColumnCohorts, total_score: float,
class_name: Optional[str] = None) -> dict[str, Any]:
pops = np.asarray(entry.populations, dtype=float)
predictions, targets = entry.predictions, entry.targets
if isinstance(predictions, dict) and isinstance(targets, dict):
predictions, targets = predictions[class_name], targets[class_name]
pred = np.asarray(predictions, dtype=float)
actual = np.asarray(targets, dtype=float)
avg_actual = float((pops * actual).sum() / pops.sum())
avg_pred = float((pops * pred).sum() / pops.sum())
# A batch shows predictions only.
predictions, targets = entry.predictions, None if run.batch else entry.targets
if isinstance(predictions, dict):
predictions = predictions[class_name]
targets = targets and targets[class_name]
series = {
name: np.asarray(values, dtype=float)
for name, values in (('actual', targets), ('predicted', predictions))
if values is not None
}
averages = {
name: float((pops * values).sum() / pops.sum())
for name, values in series.items()
}
eligible = np.where(pops >= GAP_MIN_SHARE)[0]
gap = None
if len(eligible):
if len(eligible) and 'actual' in series:
pred, actual = series['predicted'], series['actual']
j = int(eligible[np.argmax(np.abs(pred - actual)[eligible])])
gap = dict(
index=j, text=f'predicted {fmt.number(pred[j])} · actual '
f'{fmt.number(actual[j])}')
stype = entry.stype or ('count' if entry.col_name == COUNT_COLUMN else '')
unit = (f'of {run.entities}' if entry.hop == 0 or entry.col_name
== COUNT_COLUMN else f'of sampled {entry.table_name} rows')
values = fmt.numbers([*pred, *actual, avg_actual, avg_pred])
n = len(pred)
if class_name is not None:
unit = ('of sampled rows' if run.batch else f'of {run.entities}'
if entry.hop == 0 or entry.col_name == COUNT_COLUMN else
f'of sampled {entry.table_name} rows')
texts = fmt.numbers([v for values in series.values()
for v in values] + list(averages.values()))
n = len(pops)
if run.batch:
axis = ('average predicted value' if run.model_type == REGRESSION else
f'average predicted probability of {class_name or True}')
elif class_name is not None:
axis = f'share {class_name}'
elif run.model_type == CLASSIFICATION:
axis = 'share True'
else:
axis = 'average ' + (run.target() or 'value')
groups = []
for i in range(n):
group = dict(label=str(entry.cohorts[i]),
share_text=f'{fmt.percent(pops[i])} {unit}')
for k, (name, values) in enumerate(series.items()):
group.update({
name: float(values[i]),
name + '_text': texts[k * n + i]
})
groups.append(group)
share = entry.prediction_score / total_score if total_score else 0
return dict(
header=(f'{entry.table_name}.{entry.col_name} · hop {entry.hop} · '
f'{stype} · variation '
f'{fmt.percent(entry.prediction_score / total_score)}'),
groups=[
dict(label=str(entry.cohorts[i]),
share_text=f'{fmt.percent(pops[i])} {unit}',
predicted=float(pred[i]), predicted_text=values[i],
actual=float(actual[i]), actual_text=values[n + i])
for i in range(n)
], axis=axis, average_actual=avg_actual, average_predicted=avg_pred,
average_callout=(f'average actual {fmt.number(avg_actual)} · '
f'average predicted {fmt.number(avg_pred)}'),
f'{stype} · variation {fmt.percent(share)}'), groups=groups,
axis=axis, **{
'average_' + name: v
for name, v in averages.items()
}, average_callout=' · '.join(f'average {name} {fmt.number(v)}'
for name, v in averages.items()),
gap_callout=gap)


Expand All @@ -172,6 +193,7 @@ def groups(run: Run) -> Optional[dict[str, Any]]:
filter(None, (_link(entries, table, column)
for table, column, _ in scores or [])), None)
return dict(
title='Column groups', selectable=not scores, columns=views,
default=default or _key(max(entries, key=lambda e: e.prediction_score)),
title='Cohorts' if run.batch else 'Column groups',
selectable=not scores, columns=views, default=default
or _key(max(entries, key=lambda e: e.prediction_score)),
coverage=run.explanation_coverage())
155 changes: 155 additions & 0 deletions packages/kumo-engine/kumo/engine/_explainability/_prediction.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,155 @@
# SPDX-FileCopyrightText: Copyright (c) 2026, NVIDIA CORPORATION & AFFILIATES.
# All rights reserved.
# SPDX-License-Identifier: Apache-2.0
"""The batch prediction widget: the training widget's cohort and subgraph
cards over one batch's retained PRED-stage explanations."""

from dataclasses import asdict
from typing import Any, Optional

from pydantic import TypeAdapter

from kumo.engine._explainability import (
ExplainabilityView,
_columns,
_subgraphs,
)
from kumo.engine._explainability._run import _TASKS, Run
from kumo.engine._manifest import PredictionManifest
from kumo.engine.explain._prediction_manifest import read_record
from kumo.engine.explain.results import PredictionExplanations

_REASONS: dict[Optional[str], str] = dict(
disabled='Generation was disabled for this batch.',
unsupported='Not supported for this prediction model.',
failed='Generation did not complete.')

# Batch cards in order: card id, producer, its label, the card maker and the
# notice when available artifacts yield no card.
_CARDS = (('groups', 'cohorts', 'Cohorts', _columns.groups,
'no readable column groups were recorded.'),
('subgraphs', 'samples', 'Subgraphs', _subgraphs.card,
'no readable saved examples are available.'))


def _task(source: PredictionExplanations, kind: str) -> Optional[str]:
"""The task type in one producer's first readable artifact."""
try:
if kind == 'cohorts':
return source.column_analysis().task_type.value
references = source.samples()
except (OSError, ValueError):
return None
for reference in references:
try:
store = reference.available and source.sample(
reference.artifact_id).subgraph_store
except (OSError, ValueError):
continue # an unreadable graph leaves the others usable
if store:
return store.task_type.value
return None


def build(explanations: PredictionExplanations,
prediction: Optional[PredictionManifest],
run_id: Optional[str]) -> dict[str, Any]:
"""The batch widget's payload."""
# Live metadata may hold nulls in typed fields: every identity it still
# carries must match the retained record, and only a valid manifest of
# this batch is displayed.
parents = getattr(prediction, 'parents', None)
live = tuple(
getattr(item, 'id', None)
for item in (prediction, getattr(parents, 'model', None),
getattr(parents, 'snapshot', None)))
if run_id not in (None, live[0]):
live, prediction = (None, None, None), None
expected = (run_id or live[0], *live[1:])
try:
prediction = TypeAdapter(PredictionManifest).validate_python(
asdict(prediction)) if prediction else None
except (TypeError, ValueError):
prediction = None
notices, root = [], explanations.run_root
try:
record = read_record(root) if root else None
except (OSError, ValueError):
record = None
if record and any(
known not in (None, value)
for known, value in zip(expected, (record.run_id, record.model_id,
record.snapshot_id))):
notices.append(
'Retained explanations do not match this prediction batch.')
record = None
source = (PredictionExplanations.load(root)
if record and root else PredictionExplanations.unavailable())
availability = source.availability
# A producer status attached to the result outranks retained files.
for kind, state in explanations.availability.items():
if state.reason in _REASONS:
availability[kind] = state
task = next(
filter(None, (_task(source, kind) for kind in ('cohorts', 'samples')
if availability[kind].available)), None)
provenance = record.result.provenance if record and record.result else None
run = Run(task or '', _TASKS.get(task, 'prediction'), None, {}, {}, {},
None, False, False, None, source, batch=True,
cohort_rows=provenance and provenance.processed_cohort_rows)
cards = []
for card_id, kind, label, make, empty in _CARDS:
state = availability[kind]
card = make(run) if state.available else None
if card is not None:
cards.append(dict(id=card_id, **card))
else:
reason = (empty if state.available else _REASONS.get(
state.reason, 'Retained artifacts are unavailable.'))
notices.append(f'{label}: {reason}')
header: dict[str, Any] = dict(query='Batch prediction explanations')
prediction = prediction or (record.prediction if record else None)
identity = [('Batch', expected[0])]
if prediction is not None:
table, model = prediction.prediction_table, prediction.parents.model
rows = table.scored_rows if table.scored_rows is not None else table.rows
header['summary'] = (f'{rows:,} prediction rows' if rows is not None
else 'Prediction row count was not recorded.')
training = model.parents.training_table if model.parents else None
task = task or (training.task_type if training else None)
identity = [
('Batch', prediction.id), ('Model ID', model.id),
('Snapshot ID', prediction.parents.snapshot.id),
('Prediction type',
task.replace('_', ' ').capitalize() if task else 'Not recorded'),
('Architecture', 'Not recorded in batch artifacts'),
('Fit mode', model.fit_mode),
('Batch started', prediction.timings
and prediction.timings.started_at)
]
header['identity'] = [[k, str(v)] for k, v in identity if v]
return _subgraphs._json_value(
dict(
kind='prediction', model_type=run.model_type, entities=run.entities,
header=header, tabs=[
dict(
id='explanation', label='Explanation', cards=[
dict(id='status', title='Explanation availability',
messages=notices)
] * bool(notices) + cards)
]))


class PredictionExplainabilityView(ExplainabilityView):
"""Read-only display of one batch's retained PRED-stage explanations."""
def __init__(self, explanations: PredictionExplanations,
prediction: Optional[PredictionManifest] = None,
run_id: Optional[str] = None) -> None:
self._source = (explanations, prediction, run_id)
self._widget = None

def _build(self) -> dict[str, Any]:
return build(*self._source)

def __repr__(self) -> str:
return f'<PredictionExplainabilityView {self._source[0].run_root}>'
Loading
Loading