Skip to content
Merged
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
1 change: 1 addition & 0 deletions agent-skills/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -25,6 +25,7 @@ are sub-skills and references it loads:
| `kumo-data-science/` | Router: intake, validation, preflight, notebook generation |
| `kumoai-reference/` | SDK reference the generated code is checked against |
| `hosts/` | Host-specific behavior: access, source and destination forms, preflight, connect step |
| `kumo-graph-visualization/` | Provide graph visuals for users; inspect schemas during model iteration |
| `kumo-model-explanations/` | Explaining predictions |
| `kumo-training-diagnostics/` | Diagnosing training runs |
| `kumo-model-persistence/` | Saving and reloading trained models |
Expand Down
1 change: 1 addition & 0 deletions agent-skills/scripts/package_skill.py
Original file line number Diff line number Diff line change
Expand Up @@ -53,6 +53,7 @@
ROUTER = 'kumo-data-science'

CAPABILITY = [
'kumo-graph-visualization',
'kumo-model-explanations',
'kumo-training-diagnostics',
'kumo-model-persistence',
Expand Down
8 changes: 8 additions & 0 deletions agent-skills/skills/hosts/databricks-genie/runtime.md
Original file line number Diff line number Diff line change
Expand Up @@ -277,3 +277,11 @@ Run only on explicit request (router Step 3).
the notebook's own check.

> **Not verified:** how long a Genie Code session stays attached through a long training run.

## Graph visualization

> **Not verified:** interactive HTML rendering and saved-output behavior have not been tested in Databricks notebooks.
The SDK supplies an HTML view; rerun the cell if saved output is static.
Exports are saved on the notebook runtime; use the workspace's file tools to retrieve them.

Source: shipped package (`kumo.engine.graph.Graph.visualize`, `kumo.engine._visualization.SVG`)
8 changes: 8 additions & 0 deletions agent-skills/skills/hosts/generic/runtime.md
Original file line number Diff line number Diff line change
Expand Up @@ -276,3 +276,11 @@ Run only on explicit request (router Step 3), in this session's own Python, and
`import kumo.engine` works here and the connect step resolves credentials. If either fails, report
it and stop: making this session able to run Kumo is not your job. `fit` blocks for as long as
training takes — tell the user before starting.

## Graph visualization

Notebook calls display an interactive HTML view.
For scripts, save an SVG and report its path on the Python runtime, which may be remote.
Retrieve exports through that environment's file tools.

Source: shipped package (`kumo.engine.graph.Graph.visualize`, `kumo.engine._visualization.SVG`)
9 changes: 9 additions & 0 deletions agent-skills/skills/hosts/snowflake-coco/runtime.md
Original file line number Diff line number Diff line change
Expand Up @@ -197,3 +197,12 @@ Two further facts: the target destination must be writable by the identity's pri
6. Write results to a durable Snowflake destination before the session ends (§3.1, §7).

---

## Graph visualization

> **Not verified:** interactive rendering has not been tested in Snowflake Workspace notebooks.
The SDK selects a widget in Workspace, requiring `anywidget>=0.9,<1` and `ipywidgets`; if these dependencies cannot be imported, it displays a static SVG instead.
Other notebook hosts use HTML.
Retrieve exported diagrams from the notebook filesystem through the Workspace file browser.

Source: shipped package (`kumo.engine.graph.Graph.visualize`, `kumo.engine._visualization.SVG`)
12 changes: 9 additions & 3 deletions agent-skills/skills/kumo-data-science/SKILL.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
---
name: kumo-data-science
description: "Use for any work with KumoAI predictive models on relational data in a warehouse, an object store or local files: train a model, score data with a trained one, or answer questions about an existing model or run — explain its predictions, diagnose its training, publish, reload or retain it, train or score on custom labels or rows, or tune it. Covers churn, propensity, fraud, recommendation, forecasting and link prediction. For a new model it checks that the request names the data (a schema, dataset, folder of files, connector, semantic view or metric view), the outcome and the time window, confirms the inferred tables and the task, then generates one notebook or script; it runs it only when asked, in the notebook or as a host job (a Snowflake ML Job, a Databricks job)."
description: "Use for KumoAI graphs and predictive models on relational data in a warehouse, an object store or local files: inspect, visualize or export a graph's schema and relationships; train a model, score data with a trained one, explain its predictions, diagnose its training, publish, reload or retain it, train or score on custom labels or rows, or tune it. Covers churn, propensity, fraud, recommendation, forecasting and link prediction. For a new model it checks that the request names the data, outcome and time window, confirms the inferred tables and task, then generates one notebook or script; it runs it only when asked, in the notebook or as a host job."
---

# Data Science Agent — Router Skill
Expand All @@ -12,7 +12,8 @@ description: "Use for any work with KumoAI predictive models on relational data
Quote this string verbatim whenever asked which build of the skill is loaded. If you cannot read
it from this file, you have not loaded the skill — say so rather than guessing.

Targets Kumo bundle `20261007+2e1eb12` (import `kumo.engine`; kumo-ai/kumo#31382).
Targets the local `kumo.engine` API; the baseline bundle is `20261007+2e1eb12`.
Graph visualization requires a source build including [NVIDIA/kumo-engine#134](https://github.com/NVIDIA/kumo-engine/pull/134); it is absent from that bundle and the `1.0.0` release.
One SDK, no variants.

## When to use
Expand All @@ -21,7 +22,8 @@ Requests that mention any of: kumo, predict, churn, recommend, forecast, fraud,
inference, explain a prediction, feature importance, feature attribution, column cohorts, model
metrics, trials, learning curves, publish or load a model, registry publishing, artifact retention,
caller-supplied labels, weights or splits, encoders, run mode, experiments, tune a model, semantic
view, metric view, ML Job, compute pool, Databricks job.
view, metric view, ML Job, compute pool, Databricks job, graph diagram, visualize a graph,
inspect graph schema, export graph relationships.

## Routing

Expand All @@ -30,6 +32,7 @@ build and artifact checks:

| Request | Skill |
|---|---|
| Show or export a graph; inspect its schema during model iteration | `kumo-graph-visualization/SKILL.md` |
| Attribution or column cohorts for an existing run | `kumo-model-explanations/SKILL.md` |
| Metrics, trial comparisons, learning curves, recorded progress | `kumo-training-diagnostics/SKILL.md` |
| Publish, reload, retain or retrieve a model or its artifacts | `kumo-model-persistence/SKILL.md` |
Expand Down Expand Up @@ -268,6 +271,8 @@ After ACCEPT, load `kumoai-reference/SKILL.md` and hand off the confirmed payloa

1. Connector from environment credentials; confirmed tables, metadata, links; graph and PQL
validation; SDK-default training table and model plan, no tuning.
After graph construction and validation, include the interactive graph cell from `kumo-graph-visualization/SKILL.md` for the user, before snapshot creation and training.
Visualization adds no approval gate; continue unless the user requests a pause for review.
2. **Exactly one** training call — `trainer.fit(...)`. It blocks until training finishes and
returns a `TrainingResult`; print its `metrics`.
3. **Predict in the same notebook** — same `Trainer`, same process, immediately after
Expand All @@ -283,6 +288,7 @@ After ACCEPT, load `kumoai-reference/SKILL.md` and hand off the confirmed payloa
still executes nothing (Step 3 is opt-in).

The user may ask for a script instead of a notebook.
Include the SVG export from `kumo-graph-visualization/SKILL.md` before training, saving it alongside run outputs and reporting its path.

### `batch_inference`

Expand Down
77 changes: 77 additions & 0 deletions agent-skills/skills/kumo-graph-visualization/SKILL.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,77 @@
---
name: kumo-graph-visualization
description: Provide graph visuals in Kumo notebooks and SDK scripts, display or export relationships on request, and inspect Markdown schemas during model iteration.
---

# Graph visualization

Use `Graph.visualize()` to give users a view of the tables and relationships their model uses.
Reuse the graph for the current task; graph changes follow `kumoai-reference/references/graph_construction.md`.
A request to view or export an existing graph needs no model-training intake.

## Generated notebooks

After graph construction and `graph.validate()`, include a separate cell before snapshot creation or training:

```python
from IPython.display import display

if not hasattr(graph, 'visualize'):
print('Graph preview needs a kumo-engine build including #134; upgrade when available. Continuing.')
else:
try:
display(graph.visualize())
except Exception as error:
print(f'Graph preview unavailable: {type(error).__name__}: {error}')
```

Introduce the cell as an interactive view where the user can explore tables, columns, and relationships.
It requires no snapshot and reads no source rows by default.
Continue the workflow normally; pause for visual review only if the user asks.

## Generated SDK scripts

Save `graph.svg` alongside the run's outputs before training and report its path.
Use the run's output directory; this example uses the current directory:

```python
from pathlib import Path

graph_path = Path('graph.svg').resolve()
if not hasattr(graph, 'visualize'):
print('Graph preview needs a kumo-engine build including #134; upgrade when available. Continuing.')
else:
try:
_ = graph.visualize(graph_path)
print(f'Graph diagram: {graph_path}')
except Exception as error:
print(f'Graph preview unavailable: {type(error).__name__}: {error}')
```

A missing visualization API, unsupported graph, or export failure should report the error and let modeling continue with the original graph.
The viewer supports up to 30 tables and does not support self-relations.

## Requested visuals and exports

Display the graph in a notebook or save the format the user requests: `.svg` for a diagram, `.pdf` for a diagram and complete schema index, or `.md` for a Mermaid diagram and schema tables.
`graph.visualize('graph.pdf', show_cols=True)` also shows ordinary columns in the diagram.
Use `layout='standard'` or `layout='compact'` to select an arrangement; the default is `'auto'`.
Export paths belong to the Python runtime; use `hosts/<host>/runtime.md` for display and file retrieval.

Keep samples off unless the user requests source values.
`show_samples=True` queries source data and includes sample values in saved notebook output; file exports omit them.

## Model iteration with Markdown

When considering which tables or relationships to change for a use case, export the graph for text inspection:

```python
_ = graph.visualize('graph.md')
```

Read the file to inspect all declared columns, key and time roles, and relationships, including columns hidden in the diagram.
The assignment suppresses automatic notebook display.
Use this schema alongside model evaluation results to plan graph experiments; it does not measure predictive usefulness.
Markdown inspection is optional during iteration, not a prerequisite for generating or running a model.

Source: shipped package (`kumo.engine.graph.Graph.visualize`, `kumo.engine._visualization.SVG`)
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# KumoAI Graph Construction

Reference for translating a validated relational schema into Kumo Predict SDK objects.
Reference for translating a confirmed relational schema into Kumo Predict SDK objects.

Grounded **only** in the shipped Kumo package source. The published Kumo documentation is
stale for this version of the local SDK — do not cite it, fetch it, or reconcile against it.
Expand Down Expand Up @@ -219,10 +219,13 @@ optional bookkeeping: the snapshot object is the argument passed to
`pquery.generate_prediction_table(snapshot, prediction_time=...)`. Training and prediction
themselves belong to `kumoai-reference/references/kumo_finetuning_sdk.md`.

**`Graph` has no editing surface.** Its complete API is `.tables`, `.edges`, `.id`,
`.native_graph`, `.validate()`, `.snapshot()`. There is no `add_table`, `remove_table`, `link`,
`unlink`, `infer_links`, `get_edge_stats`, `get_table_stats`, `visualize`, or `save`/`load`. To
change a graph, rebuild it.
**`Graph` has no editing surface.** Its API includes `.tables`, `.edges`, `.id`, `.native_graph`, `.validate()`, `.visualize()`, and `.snapshot()`.
There is no `add_table`, `remove_table`, `link`, `unlink`, `infer_links`, `get_edge_stats`, `get_table_stats`, or `save`/`load`.
To change a graph, rebuild it.

Use `kumo-graph-visualization/SKILL.md` to include an interactive graph in generated notebooks or an SVG export in scripts after graph validation.
It also covers requested visuals and Markdown inspection during model iteration.
Visualization adds no required review or pause.

---

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -7,11 +7,12 @@ process. There is no hosted service, no project, no job registry, no API key, no

## 0. Ground truth

Everything in this file is verified against **one** build:
The baseline API was verified against the bundle below; graph visualization was checked against source including [NVIDIA/kumo-engine#134](https://github.com/NVIDIA/kumo-engine/pull/134).

| | |
|---|---|
| Bundle | `kumo_fat_bundle` `20261007+2e1eb12` (after the `kumo-engine` rename, kumo-ai/kumo#31382) |
| Baseline bundle | `kumo_fat_bundle` `20261007+2e1eb12` (after the `kumo-engine` rename, kumo-ai/kumo#31382) |
| Graph visualization | Source build including #134 (merged at `fa46bed23fb01921955cb77bfec21e80ab7e0fc6`); unavailable in the baseline bundle and `kumo-engine` `1.0.0`, with no released build verified |
| Import name | `kumo.engine` (the `kumo-engine` package; `kumoai` / `kumoai-local` before the rename) |
| Python / torch | 3.12 / `2.9.1+cu129` |

Expand Down Expand Up @@ -373,10 +374,13 @@ graph.validate()
- Emit `validate()` explicitly. It is a structural check needing only schemas — no snapshot yet,
so it is cheap and catches edge typos before any data moves.

Surface, complete: `.tables`, `.edges`, `.id`, `.native_graph`, `.validate()`, `.snapshot()`.
Surface includes `.tables`, `.edges`, `.id`, `.native_graph`, `.validate()`, `.visualize()`, `.snapshot()`.
**There is no `add_table`, `remove_table`, `link`, `unlink`, `infer_links`, `get_edge_stats`, or
`get_table_stats`.**

`Graph.visualize(path=None, *, show_cols=False, show_samples=False, layout='auto')` displays or exports the graph.
Follow `kumo-graph-visualization/SKILL.md` for generated notebook visuals, script exports, and schema inspection during model iteration.

Source: shipped package (`kumo.engine.graph`)

---
Expand Down
2 changes: 2 additions & 0 deletions agent-skills/tests/test_package_skill.py
Original file line number Diff line number Diff line change
Expand Up @@ -21,6 +21,8 @@
def test_every_reference_resolves(tmp_path: Path, host: str) -> None:
pkg = package_skill.build(host, tmp_path)
assert (pkg / 'SKILL.md').is_file()
for name in package_skill.CAPABILITY:
assert (pkg / name / 'SKILL.md').is_file()
assert package_skill.unresolved(pkg) == []


Expand Down
Loading