Ask a predictive question of one table, or of a whole relational schema, and get an answer without training a model for each dataset.
pip install 'structured-data-models-client[relational]'Structured-data foundation models predict in context. You give the model labelled rows and the rows you want scored, and it answers in one pass. There is no training loop, no hyperparameter search, and no per-dataset artifact to manage.
This client talks to those models. It builds the request, sends it to a NIM
inference endpoint, and gives you back a PredictionResult, which
to_pandas() turns into a DataFrame. Inference runs in the NIM, so this
package downloads no weights and needs no GPU.
Two models are available through the client:
| Model | For | Asked with |
|---|---|---|
kumo-tabular |
rows of a single table | KumoTabular() |
kumo-relational |
several related tables, joined as a graph | KumoRelational() |
The model is an argument, not a method. Both use the same call.
You need a running NIM to predict against. Point the client at it and ask:
import pandas as pd
from sdm_client import KumoRelational, PredictiveQuery, SDMClient, Schema
users = pd.DataFrame({'user_id': range(12)})
orders = pd.DataFrame(
{
'order_id': range(120),
'user_id': [i % 12 for i in range(120)],
'price': [10.0 + i for i in range(120)],
'ordered_at': pd.date_range('2026-01-01', periods=120, freq='D'),
}
)
schema = Schema.from_data({'users': users, 'orders': orders})
query = PredictiveQuery(
'PREDICT SUM(orders.price, 0, 30, days) FOR EACH users.user_id', schema
)
request = query.materialize(indices=[1, 2, 3])
with SDMClient(url='http://localhost:8000') as client:
result = client.predict(request, model=KumoRelational())
print(result.to_pandas())The quickstart runs this end to end, and prerequisites covers what you need first.
| Command | You get |
|---|---|
pip install structured-data-models-client |
The client, the language, and the tabular model |
pip install 'structured-data-models-client[relational]' |
Adds the relational model and its native engine |
pip install 'structured-data-models-client[snowflake]' |
Reads tables from a warehouse. Also [sqlite], [duckdb], [postgres], [databricks], [lakebase], [s3] |
pip install 'structured-data-models-client[all]' |
The relational model and every warehouse backend |
Installation has the rest, including what differs on Databricks.
Python 3.10 through 3.14. The client, the language and the connectors are pure Python and install anywhere.
The relational engine is a native build. It publishes manylinux_2_28 wheels
for x86-64 and aarch64 on CPython 3.10 through 3.13 and no source
distribution, so [relational] resolves on a Linux with glibc 2.28 or newer
and nowhere else: not on musl, not on an older glibc, and not on macOS or
Windows, where pip has nothing to fall back to. kumo-tabular works on any
laptop.
Five distributions are released together and share one version, and a given version of one is only tested against the same version of the others:
| Package | Import | What it is |
|---|---|---|
structured-data-models-client |
sdm_client |
the public API: client, Schema, Request, model handles, sessions and results |
structured-data-models-api |
sdm_api |
the wire types. No third-party dependencies |
structured-data-models-pql |
predictive_query |
the Predictive Query Language: grammar, parser, validator, model profiles |
structured-data-models-connectors |
sdm_connectors |
reads source tables from SQLite, DuckDB, PostgreSQL, Snowflake, Databricks and S3 |
structured-data-models-relational-engine |
sdm_relational_engine |
the relational driver: graph building, samplers, the neighbor sampler |
The import name is not the package name, and is not derived from it.
structured-data-models-pql is an internal dependency of the client, not a
supported API: its predictive_query package can change in any release. Write
PQL with sdm_client.PredictiveQuery.
Release history is in CHANGELOG.md, and what a version bump
means is in stability.
Full documentation is under docs/:
- Overview and architecture
- Prerequisites, installation, quickstart
- Prediction output and limits
- Stability: what is public, and what a version bump means
skills/ is the same material written for a coding agent.
Every example in it that can run is run against a live endpoint by the test
suite, and compared to the output printed beneath it.
Contributions are welcome under the Developer Certificate of Origin. Start with
CONTRIBUTING.md, which has the development setup and the
test commands, and please read CODE_OF_CONDUCT.md.
git clone https://github.com/NVIDIA/structured-data-models-client
cd structured-data-models-client
python -m pip install -e './packages/structured-data-models-client[test]'
python -m pytest packages/structured-data-models-client/tests -m 'not live_nim' -q- Who decides what, and how a change gets merged:
GOVERNANCE.md - Maintainers and the escalation path:
MAINTAINERS.md - Support level and where to ask:
SUPPORT.md
Please do not open a public issue for a security problem. Vulnerability
reporting goes to NVIDIA PSIRT. See SECURITY.md, which also
records what is a deliberate design decision rather than a vulnerability.
Apache-2.0. See LICENSE. Copyright (c) 2026 NVIDIA CORPORATION &
AFFILIATES.
Each package under packages/ carries its own copy of LICENSE so its
pyproject.toml can reference it, which is what puts the license inside each
wheel. Those copies are the same terms as the root file, not additional ones:
api,
client,
connectors,
pql,
relational-engine.
One third-party component is vendored rather than resolved at install time:
mermaid.min.js, bundled in the relational engine so Graph.visualize() draws
offline, since Snowflake and Databricks notebooks block external scripts. It is
MIT licensed and is itself a bundle, so the components inside it are enumerated
with their copyrights in the third-party section of LICENSE. Its
bytes are pinned by digest and checked in CI.
Everything else is resolved at install time rather than shipped here. This project will download and install additional third-party open source software projects. Review the license terms of these open source projects before use.