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
22 changes: 21 additions & 1 deletion packages/kumo-engine/explainability.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,6 +5,26 @@ It does not retrain a model. Batch prediction can separately generate diagnostic
for its current inputs with `Trainer.predict(..., explanations=True)`, described
below. Explanation generation can fail without invalidating training or prediction.

## Notebook widgets

Display `training_result.visualize()` to inspect training Evaluation and Explanation views.
Under **Evaluation**, choose **Metrics → Epoch history** to compare training and validation scores across the experiments that preceded model selection.
The tuning metric opens first when recorded. Select another metric or toggle individual experiments to compare their curves on the same scale.
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.

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.
If the notebook blocks pop-ups, open the downloaded print page to save it as PDF.
**Export HTML** downloads the complete interactive widget with its current chart and customer selections, including the saved data needed to explore other records offline.
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.”
Individual subgraphs are omitted from that static snapshot.
Opening the widget only reads retained artifacts; it never starts training or prediction.

## Access the selected training run

Capture the result returned by your existing training call:
Expand Down Expand Up @@ -126,7 +146,7 @@ aggregated nodes. A reference can exist for a missing graph; check `available`.
identifiers organized by sampling category; they are not interchangeable with
collector IDs. Without those mappings, arbitrary original-key lookup is not
available. These bounded samples are training context, not explanations for
every entity. The API does not render interactive graphs.
every entity. The notebook widget renders these saved graphs interactively.

## Availability and validation

Expand Down
100 changes: 100 additions & 0 deletions packages/kumo-engine/kumo/engine/_explainability/__init__.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,100 @@
# SPDX-FileCopyrightText: Copyright (c) 2026, NVIDIA CORPORATION & AFFILIATES.
# All rights reserved.
# SPDX-License-Identifier: Apache-2.0
"""Post-training explainability widget for one trained model.

The data side reads the Kumo files a training run leaves on disk and computes
every number; the front end in ``static/`` only draws them. Open it with
``TrainingResult.visualize()``.
"""

from dataclasses import replace
from functools import cached_property
from typing import TYPE_CHECKING, Any

from kumo.engine import _widget
from kumo.engine._explainability import _cards, _files, _render, _run
from kumo.engine._explainability._snapshot import Snapshot

if TYPE_CHECKING:
from kumo.engine.trainer.trainer import TrainingResult


class ExplainabilityView:
"""The explainability widget of one trained model.

Displaying it in a notebook cell renders the widget; ``html()`` returns
the same self-contained HTML for saving to a file.
"""
def __init__(self, files: _files.RunFiles) -> None:
self._files = files
self._widget: Any = None

@cached_property
def data(self) -> dict[str, Any]:
"""Every number and text the widget draws."""
return _cards.build(_run.load(self._files))

@property
def model_type(self) -> str:
return self.data['model_type']

@cached_property
def _snapshot(self) -> Snapshot:
return Snapshot(self.data)

def html(self) -> str:
"""The widget as one self-contained HTML fragment."""
return _widget.render_widget(
**_render.specification(self.data, self._snapshot.html()))

def as_widget(self) -> Any:
"""Return a cached anywidget view, for hosts that need one."""
if self._widget is None or getattr(self._widget, 'comm', 1) is None:
self._widget = _widget.render_anywidget(
fallback_mime=self._snapshot.mime,
**_render.specification(self.data, self._snapshot.html()))
return self._widget

def _repr_html_(self) -> str:
return self.html()

def _repr_svg_(self) -> str:
return self._snapshot.svg()

def _repr_pretty_(self, printer: Any, cycle: bool) -> None:
printer.text(self._snapshot.plain())

def _ipython_display_(self) -> None:
if not _widget.is_snowflake_workspace():
raise NotImplementedError
from IPython.display import display

try:
widget = self.as_widget()
except ImportError:
bundle = self._snapshot.mime()
hint = ('Interactive display requires ipywidgets and anywidget '
'version 0.9 or later in the 0.x series.')
bundle['text/html'] += f'<p>{hint}</p>'
bundle['text/plain'] += '\n' + hint
display(bundle, raw=True)
else:
display(widget)

def __repr__(self) -> str:
return f'<ExplainabilityView {self._files.bundle}>'


def for_result(result: 'TrainingResult') -> ExplainabilityView:
files = _files.locate(str(result.bundle_dir), result.explanations.run_root,
result.explanations.trial_root)
return ExplainabilityView(
replace(
files, holdout_path=str(result.holdout_path) if result.holdout_path
else None, holdout_truncated=result.holdout_truncated))


def open_run(run_root: str) -> ExplainabilityView:
"""The widget for a retained run whose bundle is in the run directory."""
return ExplainabilityView(_files.open_run(run_root))
81 changes: 81 additions & 0 deletions packages/kumo-engine/kumo/engine/_explainability/_cards.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,81 @@
# SPDX-FileCopyrightText: Copyright (c) 2026, NVIDIA CORPORATION & AFFILIATES.
# All rights reserved.
# SPDX-License-Identifier: Apache-2.0
"""The cards each model type shows, in order, on its two tabs.

A card whose inputs are missing is left out; a tab with no card is left out.
"""

from collections.abc import Callable
from typing import Any, Optional

from kumo.engine._explainability import (
_classification,
_columns,
_metrics,
_subgraphs,
)
from kumo.engine._explainability._forecasting import forecast_card
from kumo.engine._explainability._header import header
from kumo.engine._explainability._regression import predicted_card
from kumo.engine._explainability._run import (
CLASS_LABELED,
CLASSIFICATION,
FORECASTING,
LINK_PREDICTION,
REGRESSION,
Run,
)

Card = Callable[[Run], Optional[dict[str, Any]]]

EVALUATION: dict[str, list[tuple[str, Card]]] = {
CLASSIFICATION: [
('metrics', _metrics.card),
('cutoff', _classification.cutoff_card),
('scores', _classification.scores_card),
],
REGRESSION: [('metrics', _metrics.card), ('predicted', predicted_card)],
FORECASTING: [('metrics', _metrics.card), ('forecast', forecast_card)],
LINK_PREDICTION: [('metrics', _metrics.card)],
}

EXPLANATION: dict[str, list[tuple[str, Card]]] = {
CLASSIFICATION: [('subgraphs', _subgraphs.card),
('importance', _columns.importance),
('groups', _columns.groups)],
REGRESSION: [('subgraphs', _subgraphs.card),
('importance', _columns.importance),
('groups', _columns.groups)],
FORECASTING: [('importance', _columns.importance)],
LINK_PREDICTION: [('subgraphs', _subgraphs.card),
('importance', _columns.importance)],
}


def _cards(run: Run, spec: list[tuple[str, Card]]) -> list[dict[str, Any]]:
out = []
for card_id, build in spec:
if run.task_type in CLASS_LABELED and card_id in ('cutoff', 'scores'):
continue
card = build(run)
if card is not None:
out.append({'id': card_id, **card})
return out


def build(run: Run) -> dict[str, Any]:
"""Every number and text the widget draws for one run."""
tabs = []
for tab_id, label, spec in (('evaluation', 'Evaluation', EVALUATION),
('explanation', 'Explanation', EXPLANATION)):
cards = _cards(run, spec[run.model_type])
if cards:
tabs.append({'id': tab_id, 'label': label, 'cards': cards})
return {
'model_type': run.model_type,
'task_type': run.task_type,
'entities': run.entities,
'header': header(run),
'tabs': tabs
}
Loading
Loading