> 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.

# Installation

> Install SDM, set up CPU, GPU, or Snowflake execution, and manage model weight downloads.

## Requirements

| Requirement        | Value                                                                                        |
| ------------------ | -------------------------------------------------------------------------------------------- |
| Python             | 3.11 or later                                                                                |
| PyTorch            | 2.7 or later (installed as a dependency)                                                     |
| Other dependencies | `numpy`, `pyarrow`, `huggingface_hub`, `safetensors`, `typing_extensions`                    |
| Hardware           | CPU works for small examples. Use an NVIDIA GPU for larger tables and the large model sizes. |
| Network            | Needed for installation and the first download of each model's weights                       |

Kumo Forecast and Kumo Anomaly install separately from [Kumo-TS](https://github.com/NVIDIA/Kumo-TS).
Kumo-Anomaly requires Python 3.12 or later.

## Install from PyPI

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

SDM runs Kumo Tabular and Kumo Relational.

## Install Kumo-TS for Time Series

Kumo Forecast and Kumo Anomaly ship as two packages in the Kumo-TS repository.
Install each in its own environment: both expose a top-level `sdk` module, so they cannot share one.
The commands use [uv](https://docs.astral.sh/uv/) and the lockfile in each package.

Clone the repository and set up Kumo Forecast:

**`Kumo Forecast`**

```bash title="Kumo Forecast"
git clone https://github.com/NVIDIA/Kumo-TS.git
cd Kumo-TS/Kumo-Forecast
uv sync --frozen --python 3.12
```

From the directory where you cloned Kumo-TS, set up Kumo Anomaly:

**`Kumo Anomaly`**

```bash title="Kumo Anomaly"
cd Kumo-TS/Kumo-Anomaly
uv sync --frozen --python 3.12
```

Run scripts from the package directory with `uv run python your_script.py`, or activate that package's `.venv`.

## Set Up a GPU

Install a CUDA-enabled PyTorch build that matches your driver, following the [PyTorch installation instructions](https://pytorch.org/get-started/locally/).
Check that `torch.cuda.is_available()` returns `True`.
For CUDA workloads, the SDM maintainers recommend installing [cuDF](https://docs.rapids.ai/install) to keep dataframe operations on the GPU.

## Set Up Snowflake

To run SDM in a Snowflake Notebook, the notebook service needs network access to Hugging Face for model weights.
The [Quickstart](/sdgm/structured-data-models/quickstart#download-the-example-notebook) provides a Snowflake notebook that uses this setup.

### Configure Snowflake External Access

Before running the Snowflake notebook, allow its service to download pretrained
model weights from Hugging Face.

In a Snowflake SQL worksheet, run the following statements with a role that can
create network rules and external access integrations. Replace `<database>`,
`<schema>`, `<network_rule>`, and `<integration_name>` with your Snowflake object
names. Use the same network rule name in all three statements.

```sql
CREATE OR REPLACE NETWORK RULE <database>.<schema>.<network_rule>
  MODE = EGRESS
  TYPE = HOST_PORT
  VALUE_LIST = ('huggingface.co', '*.huggingface.co', '*.hf.co');

CREATE OR REPLACE EXTERNAL ACCESS INTEGRATION <integration_name>
  ALLOWED_NETWORK_RULES = (<database>.<schema>.<network_rule>)
  ENABLED = TRUE;

ALTER NETWORK RULE <database>.<schema>.<network_rule> SET
  VALUE_LIST = ('huggingface.co', '*.huggingface.co', '*.hf.co',
                '*.xethub.hf.co', '*.cdn.hf.co', '*.aws.cdn.hf.co');
```

These statements create an egress network rule for Hugging Face hosts, create
an enabled external access integration that uses the rule, and extend the rule
to include model download hosts.

Attach the integration to the notebook service when provisioning and connecting
the notebook's compute pool:

1. Open the **Edit service** dialog for the notebook service.
2. In **External access**, add the external access integration you created as
   `<integration_name>`.
3. Save the service configuration and connect the notebook to its compute pool.

With the integration attached, the notebook service can access the listed hosts
to download the model from Hugging Face. The notebook's role must have `USAGE`
on the integration. For access grants and session restart requirements, see
[Set up external access for Snowflake Notebooks](https://docs.snowflake.com/en/user-guide/ui-snowsight/notebooks-external-access).

Before importing `sdm` in the notebook, add the following Python code to disable
Hugging Face's Xet download backend:

```python
import os
os.environ["HF_HUB_DISABLE_XET"] = "1"
import huggingface_hub.constants as hf_constants
hf_constants.HF_HUB_DISABLE_XET = True

import sdm
```

Keep `HF_HUB_DISABLE_XET` unchanged in Python. For details,
see [Hugging Face environment variables](https://huggingface.co/docs/huggingface_hub/package_reference/environment_variables).

## Model Weights and Caching

All four models download their weights from public Hugging Face repositories on first use; no token is required.

| Model           | Repository                                                              | Where the files go                                                                                               |
| --------------- | ----------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- |
| Kumo Tabular    | [nvidia/Kumo-Tabular](https://huggingface.co/nvidia/Kumo-Tabular)       | Hugging Face cache, pinned revision `v1.0.1`                                                                     |
| Kumo Relational | [nvidia/Kumo-Relational](https://huggingface.co/nvidia/Kumo-Relational) | Hugging Face cache, pinned revision `v1.0.1`                                                                     |
| Kumo Forecast   | [nvidia/Kumo-Forecast](https://huggingface.co/nvidia/Kumo-Forecast)     | `standardizer.pkl` and `run8_best_model_cr.pt` in the working directory, or the paths set in `ForecastingConfig` |
| Kumo Anomaly    | [nvidia/Kumo-Anomaly](https://huggingface.co/nvidia/Kumo-Anomaly)       | `final_model.pth` and `curriculum_medium.yaml` in the working directory, or `model_path` and `model_config_path` |

For SDM, set `HF_HOME` to move the cache, and set `HF_HUB_OFFLINE=1` after the first download to run without network access.
For Kumo-TS, point the weight paths at a shared directory so each project does not download its own copy.

## Optional Dependencies

| Workflow                                   | Install                  |
| ------------------------------------------ | ------------------------ |
| Sample relational subgraphs on CPU         | `pyg-lib`                |
| Sample relational subgraphs on GPU         | `cugraph`                |
| Embed text columns                         | `sentence-transformers`  |
| Repository examples                        | `pandas`, `scikit-learn` |
| Kumo Forecast PDF interpretability reports | `matplotlib`             |

## Check Your Installation

Print the installed SDM version and the models it provides:

```bash
python -c "import sdm; print(sdm.__version__); print(sdm.models.__all__)"
```

**`Expected output (PyPI 0.2.1)`**

```text title="Expected output (PyPI 0.2.1)"
0.2.1
['ICLModel', 'ECOC', 'TabICLv2', 'TabFM', 'KumoTabular', 'KumoRelational']
```

For Kumo-TS, import each package's entry point from its own directory:

**`In Kumo-TS/Kumo-Forecast`**

```bash title="In Kumo-TS/Kumo-Forecast"
uv run python -c "from sdk.forecasting import perform_forecasting; print('Kumo-Forecast OK')"
```

**`In Kumo-TS/Kumo-Anomaly`**

```bash title="In Kumo-TS/Kumo-Anomaly"
uv run python -c "from sdk.anomaly_analysis import perform_anomaly_analysis_with_diffusion; print('Kumo-Anomaly OK')"
```

Each command prints its `OK` line.
A `ModuleNotFoundError` for `sdk.forecasting` or `sdk.anomaly_analysis` means the command ran in the other package's environment.

Continue with the [Quickstart](/sdgm/structured-data-models/quickstart).