Skip to content
Open
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
40 changes: 40 additions & 0 deletions .github/workflows/request-nvskills-ci.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,40 @@
# SPDX-FileCopyrightText: Copyright (c) 2026, NVIDIA CORPORATION & AFFILIATES.
# All rights reserved.
# SPDX-License-Identifier: Apache-2.0

# NVSkills CI evaluates and signs changes under skills/. The NVIDIA skills
# catalog (github.com/NVIDIA/skills) syncs these skills from main every hour,
# and accepts only files that match the signature (skill.oms.sig) NVSkills CI
# writes into the PR. This is the catalog's request workflow, unchanged except
# that it is pinned to a SHA like every other action here. When the catalog
# changes the template, re-pin to its current main.
#
# A maintainer or admin comments `/nvskills-ci` on a PR to start a run. It needs
# the NVSKILLS_CI_DISPATCH_TOKEN secret. A PR that does not touch skills/ skips
# it.
name: Request NVSkills CI

on:
issue_comment:
types: [created]
pull_request:
types: [opened, reopened, synchronize, ready_for_review]
push:

jobs:
request:
if: >
github.event_name == 'pull_request' ||
(github.event_name == 'issue_comment' &&
github.event.issue.pull_request &&
startsWith(github.event.comment.body, '/nvskills-ci')) ||
(github.event_name == 'push' &&
github.actor == (vars.NVSKILLS_SIGNATURE_PUSH_ACTOR || 'nv-skills-ci[bot]') &&
startsWith(github.event.head_commit.message, vars.NVSKILLS_SIGNATURE_COMMIT_TITLE || 'Attach NVSkills validation signatures'))
permissions:
contents: read
pull-requests: read
statuses: read
uses: NVIDIA/skills/.github/workflows/team-request.yml@b707bbe61ff1026dd59a44140610f92c8eae1151 # main, 2026-11-06
secrets:
NVSKILLS_CI_DISPATCH_TOKEN: ${{ secrets.NVSKILLS_CI_DISPATCH_TOKEN }}
4 changes: 2 additions & 2 deletions scripts/check_repo_hygiene.py
Original file line number Diff line number Diff line change
Expand Up @@ -369,8 +369,8 @@ def check_repository_url() -> int:


IN_PROCESS_REFERENCES = (
'skills/tabular/references/in-process.md',
'skills/relational/references/in-process.md',
'skills/sdm-tabular/references/in-process.md',
'skills/sdm-relational/references/in-process.md',
)

# The release that first carries `in_process()`. Until the index has it the
Expand Down
16 changes: 8 additions & 8 deletions skills/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,8 +7,8 @@ Start at one of these two. Each is enough on its own to ask a first question.

| Skill | Model | Load it when |
|---|---|---|
| [`tabular/SKILL.md`](tabular/SKILL.md) | `kumo-tabular` | The question is about rows of one table |
| [`relational/SKILL.md`](relational/SKILL.md) | `kumo-relational` | The question is about an entity and what it is linked to |
| [`sdm-tabular/SKILL.md`](sdm-tabular/SKILL.md) | `kumo-tabular` | The question is about rows of one table |
| [`sdm-relational/SKILL.md`](sdm-relational/SKILL.md) | `kumo-relational` | The question is about an entity and what it is linked to |

An agent answering a question about a single table does not need the
relational material. What makes the relational model what it is, the two
Expand All @@ -20,12 +20,12 @@ be loaded without the skill it belongs to:

| Reference | |
|---|---|
| [`relational/pql.md`](relational/pql.md) | Writing the predictive query |
| [`tabular/references/pql.md`](tabular/references/pql.md) | The same language on one table, and what it refuses |
| [`relational/references/warehouses.md`](relational/references/warehouses.md) | Tables that stay in a warehouse, and metric views |
| [`relational/references/beyond-one-answer.md`](relational/references/beyond-one-answer.md) | Rankings, forecasts and explanations |
| [`tabular/references/in-process.md`](tabular/references/in-process.md) | Running kumo-tabular in this process, with no NIM |
| [`relational/references/in-process.md`](relational/references/in-process.md) | Running kumo-relational in this process, with no NIM |
| [`sdm-relational/pql.md`](sdm-relational/pql.md) | Writing the predictive query |
| [`sdm-tabular/references/pql.md`](sdm-tabular/references/pql.md) | The same language on one table, and what it refuses |
| [`sdm-relational/references/warehouses.md`](sdm-relational/references/warehouses.md) | Tables that stay in a warehouse, and metric views |
| [`sdm-relational/references/beyond-one-answer.md`](sdm-relational/references/beyond-one-answer.md) | Rankings, forecasts and explanations |
| [`sdm-tabular/references/in-process.md`](sdm-tabular/references/in-process.md) | Running kumo-tabular in this process, with no NIM |
| [`sdm-relational/references/in-process.md`](sdm-relational/references/in-process.md) | Running kumo-relational in this process, with no NIM |

## What these models are

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,7 @@ An entity, and the records linked to it. The question is written as a
predictive query, the client gathers each entity's neighbourhood, and the model
reads that neighbourhood in one pass.

Load [`../tabular/SKILL.md`](../tabular/SKILL.md) instead when the question is
Load [`../sdm-tabular/SKILL.md`](../sdm-tabular/SKILL.md) instead when the question is
about rows of one table with no links.

Writing the query itself is in [`pql.md`](pql.md).
Expand Down
88 changes: 88 additions & 0 deletions skills/sdm-relational/evals/evals.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,88 @@
{
"skill_name": "sdm-relational",
"evals": [
{
"id": "r01",
"prompt": "I have three pandas DataFrames: users(user_id, segment), orders(order_id, user_id, item, price, ordered_at) and items(item, kind). Using sdm_client and kumo-relational at http://localhost:8000, predict how many orders users 1, 2 and 3 will place in the next 30 days. Include anything I need to install.",
"expected_output": "Installs structured-data-models-client; KumoRelational needs no extra. Builds Schema.from_data with primary_keys for all three tables, time_columns={'orders': 'ordered_at'}, and relationships from the many side to the one side: Relationship('orders', 'user_id', 'users', 'user_id') and Relationship('orders', 'item', 'items', 'item'). Asks PredictiveQuery('PREDICT COUNT(orders.*, 0, 30, days) FOR EACH users.user_id', schema).materialize(indices=[1, 2, 3], model=KumoRelational()) and calls client.predict(request, model=KumoRelational()) with a generous timeout. Joins on id (the entity), else row_index, never row order.",
"assertions": [
"Installs structured-data-models-client without requiring a relational extra",
"Uses Schema.from_data with primary keys and time_columns={'orders': 'ordered_at'}",
"Declares relationships from orders to users and orders to items (many side first)",
"Writes the target as COUNT(orders.*, 0, 30, days) FOR EACH users.user_id",
"Calls materialize(indices=[1, 2, 3], model=KumoRelational()) and client.predict(..., model=KumoRelational())",
"Says to join results on id (or row_index), not on row order",
"Does not pass a task= argument; the task follows from the query"
]
},
{
"id": "r02",
"prompt": "My kumo-relational schema has `Relationship('users', 'user_id', 'orders', 'user_id')` because each user has many orders. Predictions look wrong. Is that relationship right?",
"expected_output": "No. Relationship(from_table, from_column, to_table, to_column) points from the many side to the one side: an order names a user, so it should be Relationship('orders', 'user_id', 'users', 'user_id').",
"assertions": [
"Says the relationship is reversed",
"Explains a Relationship points from the many side to the one side",
"Gives the corrected Relationship('orders', 'user_id', 'users', 'user_id')"
]
},
{
"id": "r03",
"prompt": "I want per-entity explanations from kumo-relational for a regression. I added outputs=['prediction', 'explanation'] and our deployment returned `422 UNSUPPORTED_OUTPUT`. Is my code wrong? How should I write this so it works on our deployment and on others?",
"expected_output": "The code is not wrong: the client will send explanation, but outputs narrow at the endpoint by task, and the shipping deployment serves only prediction and quantiles on a regression. Another relational deployment, and SDMClient.in_process(), do serve explanation. So ask for it, catch the refusal (a StructuredDataError), and fall back to prediction only, without assuming an explanation always or never arrives. When one does arrive it is on result.explanations.gradients, not in to_pandas().",
"assertions": [
"Explains the refusal comes from the deployment, not from a bug in the request",
"Says the shipping deployment serves prediction and quantiles on a regression",
"Recommends requesting explanation, catching the refusal, and falling back",
"Does not claim explanations are never available from kumo-relational (another deployment or SDMClient.in_process() serves them)",
"Says explanations, when returned, are on result.explanations rather than in to_pandas()"
]
},
{
"id": "r04",
"prompt": "I'm predicting next-quarter revenue per customer with kumo-relational and then summing the predictions to get a company-wide forecast. Anything wrong with that?",
"expected_output": "A regression's prediction is the median of the predicted distribution, not the mean, and medians do not add up. Ask for the mean with materialize(..., prediction_statistic='mean') when predictions will be summed across entities.",
"assertions": [
"States that a regression prediction is the median by default",
"Explains that medians cannot be summed to a meaningful total",
"Recommends prediction_statistic='mean' in materialize()"
]
},
{
"id": "r05",
"prompt": "I need kumo-relational scores for 50,000 users, and I'd like to pin the context in a session so later calls are cheaper. How does sdm_client handle that many rows, and how do I combine it with fit()?",
"expected_output": "materialize() does not refuse 50,000 entities: it gathers them in batches of 10,000 rows by default (rows_per_call= asks for another size), and predict() sends one call per batch and returns one result numbered across the whole request, so to_pandas() gives the indices back in the order asked. The client holds a request to no size of its own; a batch larger than the endpoint takes is the endpoint's refusal. Every batch is built before the first is sent, so the whole population is held in memory at once. fit() takes a request of one call, so fit a one-call request and pass the batched request to the handle's predict(). Pass holdout= with every id the session will score, because the context is fixed once pinned and a later-scored row would otherwise sit in it with its answer.",
"assertions": [
"Says the client batches automatically rather than refusing 50,000 entities",
"Says the default batch is 10,000 rows and rows_per_call= sets another size",
"Says the client imposes no size limit of its own; a limit is the endpoint's",
"Says fit() refuses a request gathered in several batches, and to fit a one-call request and send the batched request to the handle's predict()",
"Recommends holdout= with the ids to be scored later, because the pinned context cannot be changed"
]
},
{
"id": "r06",
"prompt": "Our users and orders tables are in a warehouse and are far too big to pull into pandas. How do I point kumo-relational at them with sdm_client without exporting the tables?",
"expected_output": "Uses a connector source from sdm_connectors (e.g. SnowflakeSource, DatabricksSource, PostgresSource, DuckDBSource) wrapping the driver's own connection, then Schema.from_source(source, {name: table}, primary_keys=..., time_columns=..., relationships=...). materialize() then samples with SQL so only a bounded sample leaves: up to a thousand rows of each table to read its columns, then only the rows a prediction needs. Everything after the schema is the same as with from_data. Installs the connector's extra, e.g. structured-data-models-client[snowflake].",
"assertions": [
"Uses Schema.from_source rather than Schema.from_data",
"Builds a source from sdm_connectors around a warehouse connection",
"Explains that only a bounded sample leaves the warehouse, not the whole table",
"Keeps the PredictiveQuery / materialize / predict flow the same as with in-memory data",
"Does not export the full tables to pandas as the recommended approach"
]
},
{
"id": "r07",
"prompt": "We have no kumo-relational NIM, and our users and orders tables must not leave this machine. Can sdm_client still answer 'how many orders will each user place in the next 30 days'? What changes in my code and install?",
"expected_output": "Yes: open the client with SDMClient.in_process() in place of a URL; the schema, the query and materialize() are unchanged, and gathering still happens in this client. It needs the in-process extra and the connectors package (gathering imports it even for in-memory frames), and Python 3.11 or later; until a published release carries in_process(), both are installed from a checkout of v2-candidate as the reference describes. The first prediction fetches the published weights (nvidia/Kumo-Relational) into the Hugging Face cache with no account or token. On a CPU its numbers can differ from a GPU-hosted NIM's. Join the answer back on id or row_index, never row order.",
"assertions": [
"Uses SDMClient.in_process() in place of SDMClient(url=...)",
"Keeps Schema.from_data, PredictiveQuery and materialize() unchanged",
"Names the in-process extra and the structured-data-models-connectors package",
"Says the weights are fetched once from Hugging Face, with no token required",
"Says CPU results can differ from a GPU-hosted NIM's",
"Does not send the tables to any remote endpoint"
]
}
]
}
Original file line number Diff line number Diff line change
Expand Up @@ -345,7 +345,7 @@ ASSUMING users.segment = 'a'

The same language, cut down to a column of one table as the target. Every
clause above is refused there. It has its own reference:
[`../tabular/references/pql.md`](../tabular/references/pql.md).
[`../sdm-tabular/references/pql.md`](../sdm-tabular/references/pql.md).

## When it will not parse

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -167,4 +167,4 @@ if analysis is not None:
cohorts[cohorts['table'] == 'orders'] # the cohorts of each column of orders
```

See [the result contract](../../../docs/reference/prediction-output.md).
See [the result contract](https://github.com/NVIDIA/structured-data-models-client/blob/main/docs/reference/prediction-output.md).
Original file line number Diff line number Diff line change
Expand Up @@ -192,7 +192,7 @@ model already loaded with structured-data-models is used as it is:
`sdm.models.KumoRelational`, shares its weights with every context the client
fits, and refuses `device=` beside it, since that model is already somewhere.
The quickstart's section on a model in this process, in
[`docs/get-started/quickstart.md`](../../../docs/get-started/quickstart.md),
[`docs/get-started/quickstart.md`](https://github.com/NVIDIA/structured-data-models-client/blob/main/docs/get-started/quickstart.md),
shows it.

A model loaded that way arrives in evaluation mode and loaded for both tasks,
Expand Down
47 changes: 47 additions & 0 deletions skills/sdm-relational/skill-card.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,47 @@
## Description: <br>
Ask kumo-relational a question about an entity and the records linked to it: write the question as a predictive query over a schema of related tables, covering classification, regression, forecasting and ranking the candidates an entity may link to. <br>

This skill is ready for commercial/non-commercial use. <br>

## Owner
NVIDIA <br>

### License/Terms of Use: <br>
Apache 2.0 <br>
## Use Case: <br>
Developers and data scientists use this skill with coding agents to write Python that describes related tables (in memory or in a warehouse) and asks NVIDIA's kumo-relational structured-data foundation model predictive queries about entities through the structured-data-models client, without training a model. <br>

### Deployment Geography for Use: <br>
Global <br>

## Requirements / Dependencies: <br>
**Requires API Key or External Credential:** [Optional] <br>
**Credential Type(s):** [API key] <br>

Do not include secrets in prompts/logs/output; use least-privilege credentials; rotate keys as appropriate. See skill body for more details. <br>

## Known Risks and Mitigations: <br>
Risk: Review before execution as proposals could introduce incorrect or misleading guidance into skills. <br>
Mitigation: Review and scan skill before deployment. <br>

## Reference(s): <br>
- [pql.md](pql.md) <br>
- [references/beyond-one-answer.md](references/beyond-one-answer.md) <br>
- [references/warehouses.md](references/warehouses.md) <br>
- [references/in-process.md](references/in-process.md) <br>


## Skill Output: <br>
**Output Type(s):** [Code, Analysis] <br>
**Output Format:** [Markdown with inline Python code blocks] <br>
**Output Parameters:** [1D] <br>
**Other Properties Related to Output:** [None] <br>

## Skill Version(s): <br>
2.0.0rc1 (source: CHANGELOG, unreleased release candidate on v2-candidate) <br>

## Ethical Considerations: <br>
NVIDIA believes Trustworthy AI is a shared responsibility and we have established policies and practices to enable development for a wide array of AI applications. When downloaded or used in accordance with our terms of service, developers should work with their internal team to ensure this skill meets requirements for the relevant industry and use case and addresses unforeseen product misuse. <br>

(For Release on NVIDIA Platforms Only) <br>
Please report quality, risk, security vulnerabilities or NVIDIA AI Concerns [here](https://app.intigriti.com/programs/nvidia/nvidiavdp/detail). <br>
6 changes: 3 additions & 3 deletions skills/tabular/SKILL.md → skills/sdm-tabular/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,7 @@ One table. You hold rows whose answer is known and rows whose answer you want.
Both go in one request, the model reads them together, and the answer comes
back a row at a time.

Load [`../relational/SKILL.md`](../relational/SKILL.md) instead when the
Load [`../sdm-relational/SKILL.md`](../sdm-relational/SKILL.md) instead when the
question is about an entity and the records linked to it. The two models share
this client's objects -- `Schema`, `PredictiveQuery`, `Request` -- and the
language. What differs is almost everything that can be asked in it.
Expand Down Expand Up @@ -52,7 +52,7 @@ Keys are unique entity IDs, or `row_index` when IDs are missing or repeated.
The client imposes no separate explanation row limit; the endpoint must support gradients.
The optional Python model runtime also supports them.
`EXPLAIN` adds explanation output without dropping ordinary outputs; `outputs=[]` remains invalid.
See [the result contract](../../docs/reference/prediction-output.md).
See [the result contract](https://github.com/NVIDIA/structured-data-models-client/blob/main/docs/reference/prediction-output.md).

```python
# With missing or repeated IDs, keys are row_index values.
Expand Down Expand Up @@ -256,4 +256,4 @@ Catch `StructuredDataError` to catch all of them.

- [`references/pql.md`](references/pql.md) — the query language on one table
- [`references/in-process.md`](references/in-process.md) — the model in this process, with no NIM
- [`../relational/SKILL.md`](../relational/SKILL.md) — when the question is about an entity and what it links to
- [`../sdm-relational/SKILL.md`](../sdm-relational/SKILL.md) — when the question is about an entity and what it links to
Loading
Loading