> This page is for Structured Data Models.

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.nvidia.com/sdgm/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.nvidia.com/sdgm/_mcp/server.

# Quickstart

> Make your first predictions with Kumo Tabular, then scale up to a GPU and larger workloads.

In this quickstart you load a public dataset, predict its labels with Kumo Tabular, and check the accuracy.

## Before You Begin

* Python 3.11 or later
* About 1 GB of disk space for PyTorch and model weights
* Network access for the first run
* No GPU and no Hugging Face account are required

## 1. Install SDM

```bash
pip install structured-data-models scikit-learn
```

`scikit-learn` provides the example dataset.
For GPU setup and other options, see [Installation](/sdgm/structured-data-models/installation).

## 2. Run a Classification

```python
import torch
from sklearn.datasets import load_breast_cancer

import sdm
from sdm.evaluation import to_class_indices

device = "cuda" if torch.cuda.is_available() else "cpu"

# 1. Load a table and declare column semantic types
df = load_breast_cancer(as_frame=True).frame
table = sdm.TableTensor.from_pandas(
    df=df,
    stypes=sdm.infer_stypes(df, overrides={"target": "categorical"}),
    device=device,
)
context, query = table[:300], table[300:]

# 2. Load pretrained Kumo Tabular (weights download on first use)
model = sdm.models.KumoTabular(task="classification", size="small", device=device)

# 3. Predict query rows from labeled context rows, with no training
probs = model(
    x_context=context.drop_columns("target"),
    y_context=context["target"],
    x_query=query.drop_columns("target"),
    num_estimators=8,
    generator=torch.Generator(device=device).manual_seed(0),
)
print(probs.to_pandas().head(3))

# 4. Score the predictions
scores, labels = to_class_indices(probs, query["target"])
accuracy = (scores.argmax(dim=-1) == labels).float().mean()
print(f"Accuracy: {accuracy:.3f}")
```

1. `TableTensor.from_pandas` converts the data frame. `infer_stypes` assigns a semantic type to each column; the override marks `target` as categorical, which makes this a classification task.
2. `KumoTabular` downloads pretrained weights. `size="small"` keeps the download and CPU time small; the default is `"large"`.
3. The forward pass reads 300 labeled context rows and predicts the 269 query rows. `num_estimators=8` averages eight randomized views of the table. The seeded `generator` makes the result reproducible.
4. `to_class_indices` aligns probability columns with the true labels by class name.

## 3. Check the Output

**`Expected output`**

```text title="Expected output"
          0         1
0  0.999958  0.000042
1  0.000192  0.999808
2  0.999905  0.000095
Accuracy: 0.974
```

The result is a `TableTensor` with one probability column per class, named by class value.
Select classes by name, for example `probs["1"]`, not by position: without a seeded generator, column order and probabilities can change between runs.

> **First run**
>
> The first run prints a Hugging Face warning about unauthenticated requests.
> It is safe to ignore; the Kumo weights are public.

## Try a Regression Task

When the target is numerical, Kumo Tabular performs regression and returns 999 quantiles named `q001` to `q999`.

```python
from sklearn.datasets import load_diabetes

df = load_diabetes(as_frame=True).frame
table = sdm.TableTensor.from_pandas(df, stypes=sdm.infer_stypes(df), device=device)
context, query = table[:300], table[300:]

model = sdm.models.KumoTabular(task="regression", size="small", device=device)
quantiles = model(
    x_context=context.drop_columns("target"),
    y_context=context["target"],
    x_query=query.drop_columns("target"),
    generator=torch.Generator(device=device).manual_seed(0),
)
median = quantiles["q500"].numerical.squeeze(-1)  # 999 columns: q001 to q999
mae = (median - query["target"].numerical.squeeze(-1)).abs().mean()
print(quantiles.size(), f"MAE: {mae:.2f}")
```

**`Expected output`**

```text title="Expected output"
torch.Size([142, 999]) MAE: 41.23
```

## Reuse Context for Many Queries

If you score many batches against the same labeled rows, call `fit` once and `predict` per batch.
SDM caches the context side of the model, so each batch only computes the query side.
This example continues from the classification script:

```python
model.fit(
    x=context.drop_columns("target"),
    y=context["target"],
    num_estimators=8,
)
for batch in query.drop_columns("target").split(64):
    probs = model.predict(batch)
model.clear()  # release cached context state
```

The 269 query rows run in batches of 64, so the last batch of probabilities has shape `torch.Size([13, 2])`.

## Run on a GPU

The quickstart script selects a CUDA device when PyTorch can see one, and creates its random generator on the same device.
First set up a CUDA-enabled PyTorch build as described in [Set Up a GPU](/sdgm/structured-data-models/installation#set-up-a-gpu).
On a GPU, you can drop `size="small"` to use the default large model.
The random generator draws a different sequence on a GPU, so probabilities can differ slightly from the CPU output shown above.

## Download the Example Notebook

Classify breast masses from four clinical features using the UCI Mammographic Mass dataset on Kumo Tabular (small).

The notebook installs its dependencies, downloads the dataset and pretrained weights, and runs without a GPU.

Download the Kumo Tabular notebook

To run the example in Snowflake, download the Snowflake notebook.
First [configure Snowflake external access](/sdgm/structured-data-models/installation#configure-snowflake-external-access) so the notebook can download model weights:

Download the Kumo Tabular notebook (Snowflake)

For import, download, device, and input errors, refer to [Troubleshooting](/sdgm/structured-data-models/troubleshooting).