diff --git a/agent-skills/README.md b/agent-skills/README.md index 24c772e34..0dbb4a254 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/` | 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/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..e43ee8017 100644 --- a/agent-skills/skills/hosts/databricks-genie/runtime.md +++ b/agent-skills/skills/hosts/databricks-genie/runtime.md @@ -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`) diff --git a/agent-skills/skills/hosts/generic/runtime.md b/agent-skills/skills/hosts/generic/runtime.md index 8cb5e407d..42bb5547e 100644 --- a/agent-skills/skills/hosts/generic/runtime.md +++ b/agent-skills/skills/hosts/generic/runtime.md @@ -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`) diff --git a/agent-skills/skills/hosts/snowflake-coco/runtime.md b/agent-skills/skills/hosts/snowflake-coco/runtime.md index c72ff8f9d..97a1d09d9 100644 --- a/agent-skills/skills/hosts/snowflake-coco/runtime.md +++ b/agent-skills/skills/hosts/snowflake-coco/runtime.md @@ -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`) diff --git a/agent-skills/skills/kumo-data-science/SKILL.md b/agent-skills/skills/kumo-data-science/SKILL.md index 300ee290b..5cda826aa 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 @@ -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 @@ -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 @@ -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` | @@ -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 @@ -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` 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..df9dd588a --- /dev/null +++ b/agent-skills/skills/kumo-graph-visualization/SKILL.md @@ -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//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`) diff --git a/agent-skills/skills/kumoai-reference/references/graph_construction.md b/agent-skills/skills/kumoai-reference/references/graph_construction.md index 8daf017b9..5995891ff 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,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. --- 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..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` | @@ -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`) --- 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) == []