NVIDIA/structured-data-models-client

NVIDIA/structured-data-models-client

Description: One Python client for NVIDIA's structured-data foundation models: ask a predictive question of one table or of a whole relational schema, and get an answer without training anything.

Language: Python

License: Apache-2.0

Stars: 1

Forks: 0

Open issues: 3

Created: 2026-10-06T04:05:18Z

Pushed: 2026-10-16T05:32:04Z

Default branch: main

Fork: no

Archived: no

README:

NVIDIA Structured Data Models Client

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]'

Overview

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.

Getting started

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](docs/get-started/quickstart.md) runs this end to end, and [prerequisites](docs/get-started/prerequisites.md) covers what you need first.

Installation

| 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](docs/get-started/installation.md) has the rest, including what differs on Databricks.

Requirements

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.

Packages

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](CHANGELOG.md), and what a version bump means is in [stability](docs/reference/stability.md).

Documentation

Full documentation is under [docs/](docs/index.md):

• [Overview](docs/about/overview.md) and

[architecture](docs/about/architecture.md)

• [Prerequisites](docs/get-started/prerequisites.md),

[installation](docs/get-started/installation.md), [quickstart](docs/get-started/quickstart.md)

• [Prediction output](docs/reference/prediction-output.md) and

[limits](docs/reference/limits.md)

• [Stability](docs/reference/stability.md): what is public, and what a version

bump means

[skills/](skills/README.md) 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.

Contributing

Contributions are welcome under the Developer Certificate of Origin. Start with [CONTRIBUTING.md](CONTRIBUTING.md), which has the development setup and the test commands, and please read [CODE_OF_CONDUCT.md](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

Governance and support

• Who decides what, and how a change gets merged:

[GOVERNANCE.md](GOVERNANCE.md)

• Maintainers and the escalation path: [MAINTAINERS.md](MAINTAINERS.md)
• Support level and where to ask: [SUPPORT.md](SUPPORT.md)

Security

Please do not open a public issue for a security problem. Vulnerability reporting goes to NVIDIA PSIRT. See [SECURITY.md](SECURITY.md), which...