From 8e7775ce62851ce7e2673bb7a43f95e3a4e02adc Mon Sep 17 00:00:00 2001 From: devanj08 Date: Mon, 2 Nov 2026 16:43:41 +0000 Subject: [PATCH 1/4] Add graph inspection and visualization to customer skills --- agent-skills/README.md | 1 + agent-skills/scripts/package_skill.py | 1 + .../skills/hosts/databricks-genie/runtime.md | 11 ++ agent-skills/skills/hosts/generic/runtime.md | 11 ++ .../skills/hosts/snowflake-coco/runtime.md | 12 +++ .../skills/kumo-data-science/SKILL.md | 8 +- .../skills/kumo-graph-visualization/SKILL.md | 101 ++++++++++++++++++ .../references/graph_construction.md | 14 ++- .../references/kumo_finetuning_sdk.md | 6 +- agent-skills/tests/test_package_skill.py | 2 + 10 files changed, 159 insertions(+), 8 deletions(-) create mode 100644 agent-skills/skills/kumo-graph-visualization/SKILL.md diff --git a/agent-skills/README.md b/agent-skills/README.md index 24c772e34..265c36ec1 100644 --- a/agent-skills/README.md +++ b/agent-skills/README.md @@ -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/` | Inspect declared graphs through Markdown; display and export relationships | | `kumo-model-explanations/` | Explaining predictions | | `kumo-training-diagnostics/` | Diagnosing training runs | | `kumo-model-persistence/` | Saving and reloading trained models | diff --git a/agent-skills/scripts/package_skill.py b/agent-skills/scripts/package_skill.py index e91f6082e..edcf6ce23 100755 --- a/agent-skills/scripts/package_skill.py +++ b/agent-skills/scripts/package_skill.py @@ -53,6 +53,7 @@ ROUTER = 'kumo-data-science' CAPABILITY = [ + 'kumo-graph-visualization', 'kumo-model-explanations', 'kumo-training-diagnostics', 'kumo-model-persistence', diff --git a/agent-skills/skills/hosts/databricks-genie/runtime.md b/agent-skills/skills/hosts/databricks-genie/runtime.md index 42235c4d0..946466de4 100644 --- a/agent-skills/skills/hosts/databricks-genie/runtime.md +++ b/agent-skills/skills/hosts/databricks-genie/runtime.md @@ -277,3 +277,14 @@ 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 + +Reuse the graph in its existing Kumo notebook runtime for Markdown inspection or requested display; graph inspection alone does not require a GPU or a job. +The modeling notebook's compute requirements still apply when it trains. +Databricks uses the HTML view, whose interactivity requires trusted output and whose fullscreen control depends on host permission. +Saved HTML includes a sample-free static fallback; rerun the visualization cell to reactivate it after a kernel restart. +Exports are files on the notebook runtime's filesystem, not Unity Catalog tables or automatic browser downloads. +Report that path and use the workspace's available file retrieval tools; copying to a volume or other persistent destination requires the user's destination and write scope. + +Source: shipped package (`kumo.engine.graph.Graph.visualize`, `kumo.engine._visualization.SVG`, `kumo.engine._widget`) diff --git a/agent-skills/skills/hosts/generic/runtime.md b/agent-skills/skills/hosts/generic/runtime.md index 8cb5e407d..258b7277e 100644 --- a/agent-skills/skills/hosts/generic/runtime.md +++ b/agent-skills/skills/hosts/generic/runtime.md @@ -276,3 +276,14 @@ 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 + +An available `Graph` can be inspected through the temporary Markdown export in `kumo-graph-visualization/SKILL.md` without running the modeling artifact. +For user-requested display, ordinary notebooks use HTML; interactivity requires trusted output and fullscreen requires host permission. +Saved HTML includes a sample-free static fallback; rerun the visualization cell to restore interactivity after a kernel restart, subject to the host's output restrictions. +`graph.visualize().as_widget()` explicitly requests a widget on compatible hosts, using their existing `anywidget>=0.9,<1` and `ipywidgets` support; report missing support and offer a static export. +Export paths are local to the Python process, which may be remote; use that environment's existing file access to retrieve them. +Graph inspection alone does not require GPU compute or a training run. + +Source: shipped package (`kumo.engine._visualization.SVG`, `kumo.engine._widget`) diff --git a/agent-skills/skills/hosts/snowflake-coco/runtime.md b/agent-skills/skills/hosts/snowflake-coco/runtime.md index c72ff8f9d..4ad919c57 100644 --- a/agent-skills/skills/hosts/snowflake-coco/runtime.md +++ b/agent-skills/skills/hosts/snowflake-coco/runtime.md @@ -197,3 +197,15 @@ 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 + +Reuse the graph in its existing Kumo runtime for Markdown inspection or requested display; graph inspection alone does not require a GPU or an ML Job. +Detected Snowflake Workspace notebooks automatically display through the widget protocol, using the runtime's `anywidget>=0.9,<1` and `ipywidgets` support. +Missing or incompatible widget support yields a static graph and diagnostic; SVG, PDF, and Markdown exports remain available. +Other notebook environments use HTML, regardless of which connector the graph uses. +The optional `graph.visualize().as_widget()` explicitly selects the widget view on a compatible runtime; redisplay after a kernel restart because restoration depends on the host. +Exports write to the notebook filesystem and require a writable parent directory; retrieve the file through the Workspace file browser. +A file export does not create a Snowflake stage object or start a browser download. + +Source: shipped package (`kumo.engine.graph.Graph.visualize`, `kumo.engine._visualization.SVG`, `kumo.engine._widget`) diff --git a/agent-skills/skills/kumo-data-science/SKILL.md b/agent-skills/skills/kumo-data-science/SKILL.md index 300ee290b..157eced17 100644 --- a/agent-skills/skills/kumo-data-science/SKILL.md +++ b/agent-skills/skills/kumo-data-science/SKILL.md @@ -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 @@ -21,7 +21,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 @@ -30,6 +31,7 @@ build and artifact checks: | Request | Skill | |---|---| +| Inspect or iterate a declared graph; display or export its schema and relationships | `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` | @@ -268,6 +270,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 guarded optional-preview notebook cell for the human reader, with samples off; a visualization `ValueError` must not block modeling or change the graph. + Use `kumo-graph-visualization/SKILL.md` for this cell and for the agent's Markdown inspection of the graph definition; do not open or analyze its interactive view yourself. 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 diff --git a/agent-skills/skills/kumo-graph-visualization/SKILL.md b/agent-skills/skills/kumo-graph-visualization/SKILL.md new file mode 100644 index 000000000..c2b922eba --- /dev/null +++ b/agent-skills/skills/kumo-graph-visualization/SKILL.md @@ -0,0 +1,101 @@ +--- +name: kumo-graph-visualization +description: Inspect and iterate declared Kumo graph definitions through Markdown, add a graph view to a modeling notebook, or display and export table relationships on request. Covers schema diagrams, layouts, SVG/PDF/Markdown exports, and optional source previews; not model explanation subgraphs. +--- + +# Graph inspection and visualization + +Reuse the user's `kumo.engine.Graph`, or the graph definition being built for the authorized task. +A standalone diagram or schema inspection does not require a prediction target, horizon, training run, snapshot, or fit. +If the graph is missing or ambiguous, resolve which definition to use; do not invent tables, keys, or relationships. +New or changed graph definitions still follow the source access, graph confirmation, column exclusions, and host constraints in `kumo-data-science/accept/preflight.md` and `kumoai-reference/references/graph_construction.md`. +For a training request, preserve the router's task gates before generating code. + +Check that the active runtime has `Graph.visualize`; older bundles may lack it. +If the runtime is unavailable or the method is absent, report the limitation rather than inventing an API or executing unrelated cells to obtain a graph. +The contracts below come from `kumo.engine.graph.Graph.visualize` and `kumo.engine._visualization.SVG`; they do not imply that every deployed bundle has the feature. + +## Inspect and iterate using Markdown + +Use the Markdown export to reason about a declared graph, including when generating a notebook. +In an available, authorized runtime with the graph already defined, export to a temporary local file and read its text: + +```python +from pathlib import Path +from tempfile import TemporaryDirectory + +with TemporaryDirectory() as inspection_dir: + schema_path = Path(inspection_dir) / 'graph.md' + _ = graph.visualize(schema_path) + graph_markdown = schema_path.read_text(encoding='utf-8') +print(graph_markdown) +``` + +The assignment suppresses automatic notebook display of the returned SVG object; the export still computes SVG internally. +Inspect the text with Python or file-reading tools, not a browser, screenshot, or interactive viewer. +The Markdown contains a Mermaid relationship diagram plus every declared column, data type, PK/FK/TS/TE role, and outgoing connection, including columns hidden in the interactive diagram. +Compare these declarations to the confirmed graph proposal, including column exclusions and FK-to-PK direction. +After an authorized definition change, rebuild the immutable graph and repeat the export; report differences without silently changing the confirmed schema. +This is a schema inspection, not proof of observed key uniqueness, referential integrity, row coverage, or sample distributions. +Do not call `snapshot()`, train, or query source rows just to inspect the declaration. +If the graph is not available for execution, review its definition and state that export inspection could not run; generating a notebook does not authorize running its connector or modeling cells. +Markdown export has the same visualization limits as other formats; if it raises `ValueError`, report the error and inspect the declarations directly without trimming the graph. + +## Generate or display a notebook view + +In a generated modeling notebook, include this separate optional-preview cell immediately after graph construction and `graph.validate()` for the human reader: + +```python +from IPython.display import display + +try: + display(graph.visualize()) +except ValueError as error: + print(f'Graph preview unavailable: {error}') +``` + +Visualization limits must not stop an otherwise valid modeling workflow: the cell reports the actual `ValueError` and continues without changing the graph. +Explicit `display` is needed inside the `try` block; a bare expression there does not display automatically. +Generating the cell does not authorize running the notebook; preserve the router's generate-only and explicit-run rules. +For standalone requests, show the interactive view only when the user asks to see it. +Do not open or analyze the rendered view as part of the agent's graph iteration. +Read the graph visualization section of `hosts//runtime.md` for display and file access on the active host. + +```python +graph.visualize(path=None, show_cols=False, show_samples=False, layout='auto') +``` + +- With no path, the call returns SVG text with notebook display support and writes no export file. +- The default diagram shows PK, relationship FK, time (TS), and end-time (TE) columns. `show_cols=True` adds ordinary columns up to 10 rows per table, or 5 above 10 tables; key/time columns always remain visible even beyond the cap. +- `layout` accepts only `auto`, `standard`, or `compact`. Auto selects from graph structure; the notebook selector can compare arrangements without changing the graph. +- Pan, zoom, Fit, fullscreen when the host permits it, and hover/focus details are notebook controls. Each displayed view has its own camera; changing the view does not edit the graph. +- More than 30 tables, self-relations, missing definitions, invalid edge endpoints, and missing or duplicate declared columns raise `ValueError`. Report the actual error; do not silently drop tables or edges to obtain a picture. + +## Save a requested export + +Pass the user's local destination on the filesystem where Kumo Engine runs; an existing file is overwritten and the parent directory must exist. +Use a fresh path unless replacing that file is intended. +These examples are alternatives; emit only the requested format: + +```python +_ = graph.visualize('relationships.svg', show_cols=True, layout='compact') +_ = graph.visualize('relationships.pdf', show_cols=True, layout='compact') +_ = graph.visualize('relationships.md') +``` + +`.pdf` produces a vector diagram plus a paginated complete schema/connection index; `.md` and `.markdown` produce Mermaid and complete schema tables; other suffixes receive UTF-8 SVG, not HTML or PNG. +SVG and PDF use the initial layout requested in Python, not subsequent notebook interactions, and use a light palette. +Markdown diagrams use the viewer's Mermaid layout; the schema tables remain readable without Mermaid support. +The notebook's Export commands panel shows Python save commands; opening it does not write a file or start a browser download. +Report the actual runtime-side path and how to retrieve it through the active host; do not claim a browser download occurred. + +## Optional source samples + +Keep `show_samples=False` for Markdown inspection and generated notebook defaults. +Use `show_samples=True` only for an explicit request to preview source values, explaining that it can run warehouse queries with costs not bounded by the returned row limit. +It requests up to 30 preview rows per table and shows up to six non-null examples per visible column, independently selected, in notebook tooltips. +Unavailable, empty, and all-null previews are labeled; they are not evidence about the full dataset. +Samples can persist in saved notebook HTML or widget state, but SVG, PDF, and Markdown exports exclude them. +Requesting a sample-free export does not justify enabling previews. + +Source: shipped package (`kumo.engine.graph.Graph.visualize`, `kumo.engine._visualization.SVG`, `kumo.engine._visualization.render`) diff --git a/agent-skills/skills/kumoai-reference/references/graph_construction.md b/agent-skills/skills/kumoai-reference/references/graph_construction.md index 8daf017b9..6d6457e3a 100644 --- a/agent-skills/skills/kumoai-reference/references/graph_construction.md +++ b/agent-skills/skills/kumoai-reference/references/graph_construction.md @@ -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. @@ -219,10 +219,14 @@ 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. + +For inspection and iteration, use the Markdown export workflow in `kumo-graph-visualization/SKILL.md` after constructing the graph; it needs no snapshot. +In generated notebooks, including training and batch-inference notebooks, include its guarded optional-preview cell immediately after graph construction and validation for the human reader; visualization limits must not block modeling or alter the graph. +That skill also covers standalone display requests, exports, and runtime availability. +Inspect the Markdown declaration when reasoning about the graph; do not open the interactive view yourself. --- diff --git a/agent-skills/skills/kumoai-reference/references/kumo_finetuning_sdk.md b/agent-skills/skills/kumoai-reference/references/kumo_finetuning_sdk.md index db067f54c..fc3956e07 100644 --- a/agent-skills/skills/kumoai-reference/references/kumo_finetuning_sdk.md +++ b/agent-skills/skills/kumoai-reference/references/kumo_finetuning_sdk.md @@ -373,10 +373,14 @@ 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`.** +Visualization-capable builds expose `Graph.visualize(path=None, *, show_cols=False, show_samples=False, layout='auto')`. +Check availability in the actual runtime and follow `kumo-graph-visualization/SKILL.md` for Markdown inspection, notebook display, exports, and optional samples. +In generated modeling notebooks, place the capability's guarded optional-preview cell after graph construction and validation for the human reader; visualization limits must not block modeling or alter the graph, and generating the cell does not authorize executing the notebook. + Source: shipped package (`kumo.engine.graph`) --- diff --git a/agent-skills/tests/test_package_skill.py b/agent-skills/tests/test_package_skill.py index b64441694..dc8ebfae0 100644 --- a/agent-skills/tests/test_package_skill.py +++ b/agent-skills/tests/test_package_skill.py @@ -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) == [] From 529c36d2d221a1c2a89255da47a62c29cbcabf85 Mon Sep 17 00:00:00 2001 From: devanj08 Date: Mon, 2 Nov 2026 19:42:50 +0000 Subject: [PATCH 2/4] Focus graph skills on user visuals and model iteration --- agent-skills/README.md | 2 +- .../skills/hosts/databricks-genie/runtime.md | 12 +- agent-skills/skills/hosts/generic/runtime.md | 13 +- .../skills/hosts/snowflake-coco/runtime.md | 13 +- .../skills/kumo-data-science/SKILL.md | 7 +- .../skills/kumo-graph-visualization/SKILL.md | 112 +++++++----------- .../references/graph_construction.md | 7 +- .../references/kumo_finetuning_sdk.md | 5 +- 8 files changed, 64 insertions(+), 107 deletions(-) diff --git a/agent-skills/README.md b/agent-skills/README.md index 265c36ec1..0dbb4a254 100644 --- a/agent-skills/README.md +++ b/agent-skills/README.md @@ -25,7 +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/` | Inspect declared graphs through Markdown; display and export relationships | +| `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 | diff --git a/agent-skills/skills/hosts/databricks-genie/runtime.md b/agent-skills/skills/hosts/databricks-genie/runtime.md index 946466de4..3c3f12fcb 100644 --- a/agent-skills/skills/hosts/databricks-genie/runtime.md +++ b/agent-skills/skills/hosts/databricks-genie/runtime.md @@ -280,11 +280,7 @@ Run only on explicit request (router Step 3). ## Graph visualization -Reuse the graph in its existing Kumo notebook runtime for Markdown inspection or requested display; graph inspection alone does not require a GPU or a job. -The modeling notebook's compute requirements still apply when it trains. -Databricks uses the HTML view, whose interactivity requires trusted output and whose fullscreen control depends on host permission. -Saved HTML includes a sample-free static fallback; rerun the visualization cell to reactivate it after a kernel restart. -Exports are files on the notebook runtime's filesystem, not Unity Catalog tables or automatic browser downloads. -Report that path and use the workspace's available file retrieval tools; copying to a volume or other persistent destination requires the user's destination and write scope. - -Source: shipped package (`kumo.engine.graph.Graph.visualize`, `kumo.engine._visualization.SVG`, `kumo.engine._widget`) +Databricks notebooks display the interactive 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`) diff --git a/agent-skills/skills/hosts/generic/runtime.md b/agent-skills/skills/hosts/generic/runtime.md index 258b7277e..3cddff845 100644 --- a/agent-skills/skills/hosts/generic/runtime.md +++ b/agent-skills/skills/hosts/generic/runtime.md @@ -279,11 +279,8 @@ training takes — tell the user before starting. ## Graph visualization -An available `Graph` can be inspected through the temporary Markdown export in `kumo-graph-visualization/SKILL.md` without running the modeling artifact. -For user-requested display, ordinary notebooks use HTML; interactivity requires trusted output and fullscreen requires host permission. -Saved HTML includes a sample-free static fallback; rerun the visualization cell to restore interactivity after a kernel restart, subject to the host's output restrictions. -`graph.visualize().as_widget()` explicitly requests a widget on compatible hosts, using their existing `anywidget>=0.9,<1` and `ipywidgets` support; report missing support and offer a static export. -Export paths are local to the Python process, which may be remote; use that environment's existing file access to retrieve them. -Graph inspection alone does not require GPU compute or a training run. - -Source: shipped package (`kumo.engine._visualization.SVG`, `kumo.engine._widget`) +Notebook calls display an interactive HTML view; `graph.visualize().as_widget()` selects a widget on compatible hosts. +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`) diff --git a/agent-skills/skills/hosts/snowflake-coco/runtime.md b/agent-skills/skills/hosts/snowflake-coco/runtime.md index 4ad919c57..a02d261e7 100644 --- a/agent-skills/skills/hosts/snowflake-coco/runtime.md +++ b/agent-skills/skills/hosts/snowflake-coco/runtime.md @@ -200,12 +200,7 @@ Two further facts: the target destination must be writable by the identity's pri ## Graph visualization -Reuse the graph in its existing Kumo runtime for Markdown inspection or requested display; graph inspection alone does not require a GPU or an ML Job. -Detected Snowflake Workspace notebooks automatically display through the widget protocol, using the runtime's `anywidget>=0.9,<1` and `ipywidgets` support. -Missing or incompatible widget support yields a static graph and diagnostic; SVG, PDF, and Markdown exports remain available. -Other notebook environments use HTML, regardless of which connector the graph uses. -The optional `graph.visualize().as_widget()` explicitly selects the widget view on a compatible runtime; redisplay after a kernel restart because restoration depends on the host. -Exports write to the notebook filesystem and require a writable parent directory; retrieve the file through the Workspace file browser. -A file export does not create a Snowflake stage object or start a browser download. - -Source: shipped package (`kumo.engine.graph.Graph.visualize`, `kumo.engine._visualization.SVG`, `kumo.engine._widget`) +Snowflake Workspace notebooks automatically use the runtime's widget support; 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`) diff --git a/agent-skills/skills/kumo-data-science/SKILL.md b/agent-skills/skills/kumo-data-science/SKILL.md index 157eced17..8f7f7d36e 100644 --- a/agent-skills/skills/kumo-data-science/SKILL.md +++ b/agent-skills/skills/kumo-data-science/SKILL.md @@ -31,7 +31,7 @@ build and artifact checks: | Request | Skill | |---|---| -| Inspect or iterate a declared graph; display or export its schema and relationships | `kumo-graph-visualization/SKILL.md` | +| 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` | @@ -270,8 +270,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 guarded optional-preview notebook cell for the human reader, with samples off; a visualization `ValueError` must not block modeling or change the graph. - Use `kumo-graph-visualization/SKILL.md` for this cell and for the agent's Markdown inspection of the graph definition; do not open or analyze its interactive view yourself. + 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 @@ -287,6 +287,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` diff --git a/agent-skills/skills/kumo-graph-visualization/SKILL.md b/agent-skills/skills/kumo-graph-visualization/SKILL.md index c2b922eba..aea127009 100644 --- a/agent-skills/skills/kumo-graph-visualization/SKILL.md +++ b/agent-skills/skills/kumo-graph-visualization/SKILL.md @@ -1,101 +1,71 @@ --- name: kumo-graph-visualization -description: Inspect and iterate declared Kumo graph definitions through Markdown, add a graph view to a modeling notebook, or display and export table relationships on request. Covers schema diagrams, layouts, SVG/PDF/Markdown exports, and optional source previews; not model explanation subgraphs. +description: Provide graph visuals in Kumo notebooks and SDK scripts, display or export relationships on request, and inspect Markdown schemas during model iteration. --- -# Graph inspection and visualization +# Graph visualization -Reuse the user's `kumo.engine.Graph`, or the graph definition being built for the authorized task. -A standalone diagram or schema inspection does not require a prediction target, horizon, training run, snapshot, or fit. -If the graph is missing or ambiguous, resolve which definition to use; do not invent tables, keys, or relationships. -New or changed graph definitions still follow the source access, graph confirmation, column exclusions, and host constraints in `kumo-data-science/accept/preflight.md` and `kumoai-reference/references/graph_construction.md`. -For a training request, preserve the router's task gates before generating code. +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. -Check that the active runtime has `Graph.visualize`; older bundles may lack it. -If the runtime is unavailable or the method is absent, report the limitation rather than inventing an API or executing unrelated cells to obtain a graph. -The contracts below come from `kumo.engine.graph.Graph.visualize` and `kumo.engine._visualization.SVG`; they do not imply that every deployed bundle has the feature. +## Generated notebooks -## Inspect and iterate using Markdown - -Use the Markdown export to reason about a declared graph, including when generating a notebook. -In an available, authorized runtime with the graph already defined, export to a temporary local file and read its text: +After graph construction and `graph.validate()`, include a separate cell before snapshot creation or training: ```python -from pathlib import Path -from tempfile import TemporaryDirectory +from IPython.display import display -with TemporaryDirectory() as inspection_dir: - schema_path = Path(inspection_dir) / 'graph.md' - _ = graph.visualize(schema_path) - graph_markdown = schema_path.read_text(encoding='utf-8') -print(graph_markdown) +try: + display(graph.visualize()) +except (AttributeError, ValueError) as error: + print(f'Graph preview unavailable: {error}') ``` -The assignment suppresses automatic notebook display of the returned SVG object; the export still computes SVG internally. -Inspect the text with Python or file-reading tools, not a browser, screenshot, or interactive viewer. -The Markdown contains a Mermaid relationship diagram plus every declared column, data type, PK/FK/TS/TE role, and outgoing connection, including columns hidden in the interactive diagram. -Compare these declarations to the confirmed graph proposal, including column exclusions and FK-to-PK direction. -After an authorized definition change, rebuild the immutable graph and repeat the export; report differences without silently changing the confirmed schema. -This is a schema inspection, not proof of observed key uniqueness, referential integrity, row coverage, or sample distributions. -Do not call `snapshot()`, train, or query source rows just to inspect the declaration. -If the graph is not available for execution, review its definition and state that export inspection could not run; generating a notebook does not authorize running its connector or modeling cells. -Markdown export has the same visualization limits as other formats; if it raises `ValueError`, report the error and inspect the declarations directly without trimming the graph. +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. -## Generate or display a notebook view +## Generated SDK scripts -In a generated modeling notebook, include this separate optional-preview cell immediately after graph construction and `graph.validate()` for the human reader: +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 IPython.display import display +from pathlib import Path +graph_path = Path('graph.svg').resolve() try: - display(graph.visualize()) -except ValueError as error: + _ = graph.visualize(graph_path) + print(f'Graph diagram: {graph_path}') +except (AttributeError, ValueError, OSError) as error: print(f'Graph preview unavailable: {error}') ``` -Visualization limits must not stop an otherwise valid modeling workflow: the cell reports the actual `ValueError` and continues without changing the graph. -Explicit `display` is needed inside the `try` block; a bare expression there does not display automatically. -Generating the cell does not authorize running the notebook; preserve the router's generate-only and explicit-run rules. -For standalone requests, show the interactive view only when the user asks to see it. -Do not open or analyze the rendered view as part of the agent's graph iteration. -Read the graph visualization section of `hosts//runtime.md` for display and file access on the active host. +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. -```python -graph.visualize(path=None, show_cols=False, show_samples=False, layout='auto') -``` +## Requested visuals and exports -- With no path, the call returns SVG text with notebook display support and writes no export file. -- The default diagram shows PK, relationship FK, time (TS), and end-time (TE) columns. `show_cols=True` adds ordinary columns up to 10 rows per table, or 5 above 10 tables; key/time columns always remain visible even beyond the cap. -- `layout` accepts only `auto`, `standard`, or `compact`. Auto selects from graph structure; the notebook selector can compare arrangements without changing the graph. -- Pan, zoom, Fit, fullscreen when the host permits it, and hover/focus details are notebook controls. Each displayed view has its own camera; changing the view does not edit the graph. -- More than 30 tables, self-relations, missing definitions, invalid edge endpoints, and missing or duplicate declared columns raise `ValueError`. Report the actual error; do not silently drop tables or edges to obtain a picture. +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//runtime.md` for display and file retrieval. -## Save a requested export +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. -Pass the user's local destination on the filesystem where Kumo Engine runs; an existing file is overwritten and the parent directory must exist. -Use a fresh path unless replacing that file is intended. -These examples are alternatives; emit only the requested format: +## 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('relationships.svg', show_cols=True, layout='compact') -_ = graph.visualize('relationships.pdf', show_cols=True, layout='compact') -_ = graph.visualize('relationships.md') +_ = graph.visualize('graph.md') ``` -`.pdf` produces a vector diagram plus a paginated complete schema/connection index; `.md` and `.markdown` produce Mermaid and complete schema tables; other suffixes receive UTF-8 SVG, not HTML or PNG. -SVG and PDF use the initial layout requested in Python, not subsequent notebook interactions, and use a light palette. -Markdown diagrams use the viewer's Mermaid layout; the schema tables remain readable without Mermaid support. -The notebook's Export commands panel shows Python save commands; opening it does not write a file or start a browser download. -Report the actual runtime-side path and how to retrieve it through the active host; do not claim a browser download occurred. - -## Optional source samples - -Keep `show_samples=False` for Markdown inspection and generated notebook defaults. -Use `show_samples=True` only for an explicit request to preview source values, explaining that it can run warehouse queries with costs not bounded by the returned row limit. -It requests up to 30 preview rows per table and shows up to six non-null examples per visible column, independently selected, in notebook tooltips. -Unavailable, empty, and all-null previews are labeled; they are not evidence about the full dataset. -Samples can persist in saved notebook HTML or widget state, but SVG, PDF, and Markdown exports exclude them. -Requesting a sample-free export does not justify enabling previews. +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`, `kumo.engine._visualization.render`) +Source: shipped package (`kumo.engine.graph.Graph.visualize`, `kumo.engine._visualization.SVG`) diff --git a/agent-skills/skills/kumoai-reference/references/graph_construction.md b/agent-skills/skills/kumoai-reference/references/graph_construction.md index 6d6457e3a..5995891ff 100644 --- a/agent-skills/skills/kumoai-reference/references/graph_construction.md +++ b/agent-skills/skills/kumoai-reference/references/graph_construction.md @@ -223,10 +223,9 @@ themselves belong to `kumoai-reference/references/kumo_finetuning_sdk.md`. 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. -For inspection and iteration, use the Markdown export workflow in `kumo-graph-visualization/SKILL.md` after constructing the graph; it needs no snapshot. -In generated notebooks, including training and batch-inference notebooks, include its guarded optional-preview cell immediately after graph construction and validation for the human reader; visualization limits must not block modeling or alter the graph. -That skill also covers standalone display requests, exports, and runtime availability. -Inspect the Markdown declaration when reasoning about the graph; do not open the interactive view yourself. +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. --- diff --git a/agent-skills/skills/kumoai-reference/references/kumo_finetuning_sdk.md b/agent-skills/skills/kumoai-reference/references/kumo_finetuning_sdk.md index fc3956e07..542296d81 100644 --- a/agent-skills/skills/kumoai-reference/references/kumo_finetuning_sdk.md +++ b/agent-skills/skills/kumoai-reference/references/kumo_finetuning_sdk.md @@ -377,9 +377,8 @@ Surface includes `.tables`, `.edges`, `.id`, `.native_graph`, `.validate()`, `.v **There is no `add_table`, `remove_table`, `link`, `unlink`, `infer_links`, `get_edge_stats`, or `get_table_stats`.** -Visualization-capable builds expose `Graph.visualize(path=None, *, show_cols=False, show_samples=False, layout='auto')`. -Check availability in the actual runtime and follow `kumo-graph-visualization/SKILL.md` for Markdown inspection, notebook display, exports, and optional samples. -In generated modeling notebooks, place the capability's guarded optional-preview cell after graph construction and validation for the human reader; visualization limits must not block modeling or alter the graph, and generating the cell does not authorize executing the notebook. +`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`) From 86eccb190b53453b0bc3a20a5394f89a431c9501 Mon Sep 17 00:00:00 2001 From: devanj08 Date: Mon, 2 Nov 2026 19:58:27 +0000 Subject: [PATCH 3/4] Use automatic graph display in customer skill guidance --- agent-skills/skills/hosts/generic/runtime.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/agent-skills/skills/hosts/generic/runtime.md b/agent-skills/skills/hosts/generic/runtime.md index 3cddff845..42bb5547e 100644 --- a/agent-skills/skills/hosts/generic/runtime.md +++ b/agent-skills/skills/hosts/generic/runtime.md @@ -279,7 +279,7 @@ training takes — tell the user before starting. ## Graph visualization -Notebook calls display an interactive HTML view; `graph.visualize().as_widget()` selects a widget on compatible hosts. +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. From 65a0711d8527731a14f36ee93b4751d32a8bdf6f Mon Sep 17 00:00:00 2001 From: devanj08 Date: Tue, 3 Nov 2026 18:50:17 +0000 Subject: [PATCH 4/4] Clarify graph preview requirements and fallback guidance --- .../skills/hosts/databricks-genie/runtime.md | 3 ++- .../skills/hosts/snowflake-coco/runtime.md | 4 +++- .../skills/kumo-data-science/SKILL.md | 3 ++- .../skills/kumo-graph-visualization/SKILL.md | 24 ++++++++++++------- .../references/kumo_finetuning_sdk.md | 5 ++-- 5 files changed, 25 insertions(+), 14 deletions(-) diff --git a/agent-skills/skills/hosts/databricks-genie/runtime.md b/agent-skills/skills/hosts/databricks-genie/runtime.md index 3c3f12fcb..e43ee8017 100644 --- a/agent-skills/skills/hosts/databricks-genie/runtime.md +++ b/agent-skills/skills/hosts/databricks-genie/runtime.md @@ -280,7 +280,8 @@ Run only on explicit request (router Step 3). ## Graph visualization -Databricks notebooks display the interactive HTML view; rerun the cell if saved output is static. +> **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`) diff --git a/agent-skills/skills/hosts/snowflake-coco/runtime.md b/agent-skills/skills/hosts/snowflake-coco/runtime.md index a02d261e7..97a1d09d9 100644 --- a/agent-skills/skills/hosts/snowflake-coco/runtime.md +++ b/agent-skills/skills/hosts/snowflake-coco/runtime.md @@ -200,7 +200,9 @@ Two further facts: the target destination must be writable by the identity's pri ## Graph visualization -Snowflake Workspace notebooks automatically use the runtime's widget support; other notebook hosts use HTML. +> **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`) diff --git a/agent-skills/skills/kumo-data-science/SKILL.md b/agent-skills/skills/kumo-data-science/SKILL.md index 8f7f7d36e..5cda826aa 100644 --- a/agent-skills/skills/kumo-data-science/SKILL.md +++ b/agent-skills/skills/kumo-data-science/SKILL.md @@ -12,7 +12,8 @@ description: "Use for KumoAI graphs and predictive models on relational data in 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 diff --git a/agent-skills/skills/kumo-graph-visualization/SKILL.md b/agent-skills/skills/kumo-graph-visualization/SKILL.md index aea127009..df9dd588a 100644 --- a/agent-skills/skills/kumo-graph-visualization/SKILL.md +++ b/agent-skills/skills/kumo-graph-visualization/SKILL.md @@ -16,10 +16,13 @@ After graph construction and `graph.validate()`, include a separate cell before ```python from IPython.display import display -try: - display(graph.visualize()) -except (AttributeError, ValueError) as error: - print(f'Graph preview unavailable: {error}') +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. @@ -35,11 +38,14 @@ Use the run's output directory; this example uses the current directory: from pathlib import Path graph_path = Path('graph.svg').resolve() -try: - _ = graph.visualize(graph_path) - print(f'Graph diagram: {graph_path}') -except (AttributeError, ValueError, OSError) as error: - print(f'Graph preview unavailable: {error}') +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. diff --git a/agent-skills/skills/kumoai-reference/references/kumo_finetuning_sdk.md b/agent-skills/skills/kumoai-reference/references/kumo_finetuning_sdk.md index 542296d81..5cd894167 100644 --- a/agent-skills/skills/kumoai-reference/references/kumo_finetuning_sdk.md +++ b/agent-skills/skills/kumoai-reference/references/kumo_finetuning_sdk.md @@ -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` |