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 }}
2 changes: 1 addition & 1 deletion docs/about/architecture.md
Original file line number Diff line number Diff line change
Expand Up @@ -577,7 +577,7 @@ is assembled here rather than asked for.
served either — a forecast is sent as a regression per step, and a bare
`LIST_DISTINCT` is refused outright.

`skills/relational/SKILL.md` carries the same matrix for an agent, and
`skills/sdm-relational/SKILL.md` carries the same matrix for an agent, and
`tests/test_skills.py` asks the endpoint for every one of these on every task,
so a deployment that gains or loses an output fails the suite rather than
leaving the document wrong.
Expand Down
12 changes: 6 additions & 6 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, and the four task kinds that make the relational model
Expand All @@ -20,10 +20,10 @@ 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 |
| [`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 |

## 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
75 changes: 75 additions & 0 deletions skills/sdm-relational/evals/evals.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,75 @@
{
"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[relational]. 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": [
"Mentions installing the relational extra (structured-data-models-client[relational]) or MissingExtraError without it",
"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 builds batches of at most 10,000 rows per call (the deployment's limit; rows_per_call= only lowers it), and predict() sends one call per batch and returns one result numbered across the whole request. One materialize() gathers at most 100,000 entities in at most 100 calls. 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",
"States the per-call limit of 10,000 scored rows",
"Says rows_per_call can only lower the batch size",
"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 relational extra plus the connector extra.",
"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"
]
}
]
}
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
46 changes: 46 additions & 0 deletions skills/sdm-relational/skill-card.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,46 @@
## 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 link prediction. <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>


## 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>
1.0.0 (source: CHANGELOG, released 2026-10-15; git tag v1.0.0) <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 @@ -222,7 +222,7 @@ datetimes may appear as derived columns, and a table without numerical
features gives an empty list. A gradient is the change in that output score
per unit change in that column: a diagnostic, not a causal effect or a
feature-importance ranking. The whole shape is under Explanations in
[`docs/reference/prediction-output.md`](../../docs/reference/prediction-output.md).
[`docs/reference/prediction-output.md`](https://github.com/NVIDIA/structured-data-models-client/blob/main/docs/reference/prediction-output.md).

## When it refuses

Expand All @@ -241,4 +241,4 @@ Catch `StructuredDataError` to catch all of them.
## Then

- [`references/pql.md`](references/pql.md) — the query language on one table
- [`../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