structured-data-models README

Structured Data Models

A GPU-native library of foundation models, tensor subclasses, and data processors for structured data.

Models: Reference implementations of structured data foundation models, including tabular models (TabICLv2, KumoTabular, etc), relational models (KumoRelational), and time series models (KumoForecast, TimesFM3, KumoAnomaly, etc), built on a unified interface with room for future model families.
Tensor semantics: PyTorch-compatible tensor types for numerical, categorical, datetime, text, and relational data.
Data processing: Composable, extensible, and GPU-accelerated preprocessing and postprocessing for structured data workflows.

Installation

The structured-data-models package is available from Python 3.11 and PyTorch 2.7 onwards. Install from PyPI:

pip install structured-data-models

Alternatively, install from main via:

pip install git+https://github.com/NVIDIA/structured-data-models.git

[!NOTE] For CUDA workloads, we highly recommend installing cudf as an additional dependency to keep dataframe-style operations on GPU and avoid unnecessary data movement.

Model Families

Tabular Foundation Models:

TabICLv2 from Qu et al.: TabICLv2: A Better, Faster, Scalable, and Open Tabular Foundation Model (ICML '26)
TabFM from Kong et al.: TabFM: A Zero-Shot Foundation Model for Tabular Data (CoRR '26)
KumoTabular from Qu et al.: NVIDIA Kumo Tabular Sets a New Accuracy-Efficiency Frontier for Tabular Prediction ('26)

Relational Foundation Models:

KumoRelational from Hudovernik et al.: KumoRFM-2: Scaling Foundation Models for Relational Learning (CoRR '26)

Times Series Forecasting Foundation Models:

KumoForecast from Gautam et al.: Memory-Augmented Forecasting: Scalability and Generalization Across Temporal Domains (IEEE BigData '25)
TimesFM3 from Jain et al.: TimesFM-3: A Zero-Shot Foundation Model for Multivariate Forecasting ('26)

Times Series Anomaly Detection Foundation Models:

KumoAnomaly from Gautam et al.: NV-Tesseract-AD: Curriculum-Enhanced Conditional Diffusion for Multivariate Time-Series Anomaly Detection (CoRR '26)

Quick Tour

from sklearn.datasets import load_breast_cancer

import sdm

df = load_breast_cancer(as_frame=True).frame

# A lossless, fully tensorized representation of the raw data on GPU:
table = sdm.TableTensor.from_pandas(
    df=df,
    stypes=sdm.infer_stypes(df, overrides={"target": "categorical"}),
    device="cuda",
)

# Access to a variety of pre-trained structured data models:
model = sdm.models.TabICLv2(device="cuda")

# Default in-context learning forward pass:
model(
    x_context=table[:300].drop_columns("target"),
    y_context=table[:300, "target"],
    x_query=table[300:].drop_columns("target"),
    num_estimators=8,
)

# Fit + Predict forward pass via key/value caching for fast inference:
model.fit(
    x=table[:300].drop_columns("target"),
    y=table[:300, "target"],
    num_estimators=8,
)
model.predict(table[300:].drop_columns("target"))
model.clear()

Additional examples are available in examples/. Benchmarks for reproducing reported results live in benchmark/.

Notice and Disclaimer

This software automatically retrieves, accesses or interacts with external materials. Those retrieved materials are not distributed with this software and are governed solely by separate terms, conditions and licenses. You are solely responsible for finding, reviewing and complying with all applicable terms, conditions, and licenses, and for verifying the security, integrity and suitability of any retrieved materials for your specific use case. This software is provided "AS IS", without warranty of any kind. The author makes no representations or warranties regarding any retrieved materials, and assumes no liability for any losses, damages, liabilities or legal consequences from your use or inability to use this software or any retrieved materials. Use this software and the retrieved materials at your own risk.

License

The NVIDIA-authored source code is licensed under the Apache License 2.0. Third-party software and separately distributed model assets are documented in THIRD_PARTY_LICENSES.md:

sdm/models/tabiclv2/ contains code derived from TabICLv2 under the BSD 3-Clause License; its terms are distributed in sdm/models/tabiclv2/LICENSE.
sdm/models/tabfm/ contains code derived from TabFM under the Apache License 2.0; its terms are distributed in sdm/models/tabfm/LICENSE.
sdm/models/timesfm3/ contains code derived from TimesFM under the Apache License 2.0; its terms are distributed in sdm/models/timesfm3/LICENSE.
sdm/models/timestral/ contains code derived from Timestral under the Apache License 2.0; its terms are distributed in sdm/models/timestral/LICENSE.
sdm/models/kumo/relational/NOTICE documents KumoRelational's reuse of TabICLv2-derived components.
sdm/models/kumo/timeseries/anomaly/NOTICE documents KumoAnomaly's attribution to DPM-Solver.
third_party/pytorch/ contains the BSD 3-Clause License for material adapted from PyTorch in CONTRIBUTING.md; its terms are distributed in third_party/pytorch/LICENSE.
third_party/contributor-covenant/ contains the MIT License for Contributor Covenant version 1.4; its terms are distributed in third_party/contributor-covenant/LICENSE.

404 ·GitHub

Structured-data-models

What is this?

Structured Data Models (SDM) is a GPU-native library of foundation models, tensor subclasses, and data processors for working with structured data like tables, relational databases, and time series.

Is this a library I import, or a standalone app?

It's a Python library you install via PyPI and import into your own code; it provides model implementations, PyTorch-compatible tensor types, and preprocessing utilities rather than a standalone application.

What do I need before installing it?

You need Python 3.11+ and PyTorch 2.7+; for CUDA workloads, cudf is recommended as an additional dependency to keep dataframe operations on GPU.

Does it require a GPU to run well?

It's described as GPU-native, so while it may run on CPU, the design and the cudf recommendation make clear that GPU acceleration is the intended way to get full performance.

What kinds of models does it include?

It covers three families: tabular models (TabICLv2, TabFM, KumoTabular), a relational model (KumoRelational), and time series models for forecasting (KumoForecast, TimesFM3) and anomaly detection (KumoAnomaly).

Can I use TabICLv2 or TimesFM3 directly?

Yes, the library ships reference implementations built on a unified model interface, so you can load and use models like TabICLv2, TabFM, KumoRelational, KumoForecast, TimesFM3, and KumoAnomaly directly from the package.

Are there examples to get started?

Yes, additional usage examples are available in the examples/ directory, and benchmarks for reproducing published results live in benchmark/.

Does the library handle data preprocessing too?

Yes, it includes composable, extensible, and GPU-accelerated preprocessing and postprocessing utilities for structured data workflows, in addition to the models themselves.

What are similar projects?

Time-Series-Library, timestral, pyod, autogluon, timeseries-atlas, bioemu2, LTX-Video, timesfm

Which topics is it in?

time-series-analysis, tabular-data, anomaly-detection, deep-neural-networks, time-series, foundation-models, gpu-acceleration, transformer, data-science, academic-research, nvidia, cuda

Creator: NVIDIA
Size: 41.1 MB
Stars: 404
Updated: CommitOct 26 Releasev0.2.1Oct 14
Age: 4mo
Commits · 90 Days