NVIDIA has released Structured Data Models, a library allowing users to run zero-training tabular predictions by feeding labelled examples alongside new queries. The tool wraps foundation models like TabICLv2 and KumoTabular for single tables, plus KumoRelational for database schemas. It answers by in-context learning, returning probabilities or full predictive distributions in a single forward pass. This guide covers typed table tensors, compares the models against scikit-learn baselines, reuses encoded contexts, reads calibrated intervals from regression outputs, and scales to twenty classes. It also identifies default preprocessing errors that drop timestamps and text columns, explains a flawed explainer, and builds a three-table shop database to predict customer activity. Full code is available in the repository.
Installation and dependency traps
The library installs from a pinned GitHub commit because the PyPI package is currently a placeholder. A specific installation error requires manual handling of the pyg-lib dependency. PyTorch releases publish wheels on pages named torch-2.14.0+cpu, but the library’s own ImportError constructs a URL from the exact patch version, torch-2.14.1+cpu, which returns an empty page. The fix is to build the index URL using only the major and minor versions. The tutorial runs on CPU, verified end to end, though T4 runtimes can set the device to “cuda”. The library exposes four models:
- TabICLv2 for tabular in-context learning, roughly 110 MB per task head under BSD-3.
- KumoTabular for tabular tasks in small, medium, and large sizes, ranging from 110 MB to 855 MB under OpenMDW.
- KumoRelational for multi-table queries using KumoRFM-2, around 120 MB under OpenMDW.
- TabFM and TimesFM 3 for tabular and time series data, which are 6.5 GB and 1.3 GB respectively and excluded here due to non-commercial licensing.
No model is trained or fine-tuned. Every prediction is a forward pass that reads labelled context rows to answer query rows, similar to a prompt with examples.
Typed tables and inference flags
Data flows through TableTensor, a PyTorch tensor subclass that maintains one typed block per semantic type: numerical, categorical, datetime, text, and id. The infer_stypes function decides these types. Using defaults on a realistic support-ticket dataset creates two errors: free-text comments become a categorical with four hundred levels, and the ticket id becomes a number. Both would then reach the model as features. Passing text and id inference flags corrects this.
With the defaults the free-text comment becomes a 400-level categorical and the id column a number. Both would reach the model as features. Override, or ask: text=’infer’, id=’infer’.
The round trip back to pandas preserves every value, including missing ones, but not every dtype. Numbers return as float32 because the numerical block is a single float tensor. Nullable integers become floats with NaN, and categorical strings return as a pandas category. On pandas 2.x, string columns print as object rather than str, and timestamps enter at nanosecond resolution. The same values return regardless of the input format.
Timestamp precision limits
One more trap exists before loading a real event log. The library stores datetimes as integer microseconds. Arrow refuses any cast that drops a digit. A nanosecond column of whole seconds converts fine, but a single value with nanosecond digits fails the whole column. The solution is to floor timestamps to microseconds first.
What it means
Users can now bypass the training pipeline for tabular data by providing a few labelled examples. This removes the need to collect historical datasets or engineer features manually. However, developers must manually configure inference flags to prevent text and ID columns from being treated as categorical features. Data types also shift during conversion, so float32 output is expected for numerical blocks.
