# nvidia/structured-data-models architecture

> Architecture diagram of the GitHub repository nvidia/structured-data-models, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-05). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/nvidia/structured-data-models
- Repository: https://github.com/nvidia/structured-data-models

## Overview

Structured Data Models is a GPU-native Python library for structured-data tensors, preprocessing, and foundation models. The documented user workflow converts a dataframe into a typed TableTensor, supplies context and query data to a model for prediction, and can reuse a fit-time cache for later predictions. The graph also preserves the library’s relational-data, model-family, evaluation, explanation, and reusable neural-network capabilities. Some connections are documented only at a high level; unsampled implementations are represented by their existing directories rather than inferred internal call chains.

Main entry points: [`sdm/models/base.py`](https://github.com/nvidia/structured-data-models/blob/main/sdm/models/base.py) (Model interface), [`sdm/models/tabfm`](https://github.com/nvidia/structured-data-models/tree/main/sdm/models/tabfm) (TabFM), [`sdm/tensor/table.py`](https://github.com/nvidia/structured-data-models/blob/main/sdm/tensor/table.py) (TableTensor), [`sdm/cache.py`](https://github.com/nvidia/structured-data-models/blob/main/sdm/cache.py) (Inference cache)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_tensor["Tensor semantics"]
  node_table["TableTensor<br/>[table.py]"]
  node_tensor_types["Typed tensors"]
  node_tensor_io["Dataframe converters"]
end

subgraph group_processing["Data processing"]
  node_processors["Pre/postprocessors"]
  node_recipes["Processing recipes<br/>[recipe.py]"]
end

subgraph group_models["Model families"]
  node_model_api["Model interface<br/>[base.py]"]
  node_tabiclv2["TabICLv2"]
  node_tabfm["TabFM"]
  node_kumo_tabular["KumoTabular"]
  node_kumo_relational["KumoRelational"]
  node_timesfm["TimesFM3"]
  node_evaluation["Classification evaluation<br/>[classification.py]"]
  node_explanation["Model explanations"]
end

subgraph group_relational["Relational learning"]
  node_relational_data["Relational data<br/>[data.py]"]
  node_relational_task["Relational tasks<br/>[task.py]"]
  node_relational_join["Relational joins<br/>[join.py]"]
end

subgraph group_runtime["Shared runtime"]
  node_nn["Neural network layers<br/>[attention.py]"]
  node_cache["Inference cache<br/>[cache.py]"]
  node_memory["Memory utilities<br/>[_memory.py]"]
  node_ensemble["Model ensembles<br/>[ensemble.py]"]
end

node_user(("Data scientist"))
node_dataframe["Input dataframe"]

node_user -->|"provides data"| node_dataframe
node_user -->|"constructs"| node_table
node_dataframe -->|"converts from"| node_tensor_io
node_tensor_io -.->|"builds"| node_table
node_table -->|"uses tensor types"| node_tensor_types
node_user -->|"invokes prediction"| node_model_api
node_model_api -->|"unified interface"| node_tabiclv2
node_model_api -->|"unified interface"| node_tabfm
node_model_api -->|"unified interface"| node_kumo_tabular
node_model_api -->|"unified interface"| node_kumo_relational
node_model_api -.->|"model family"| node_timesfm
node_user -.->|"preprocesses data"| node_processors
node_processors -->|"composes processors"| node_recipes
node_table -.->|"combines with"| node_relational_data
node_relational_task -->|"uses joins"| node_relational_join
node_user -.->|"evaluates predictions"| node_evaluation
node_user -.->|"requests explanations"| node_explanation
node_model_api -->|"records fit state"| node_cache
node_tabfm -->|"uses layers"| node_nn
node_tabfm -->|"checks memory"| node_memory
node_kumo_tabular -->|"uses cache"| node_cache
node_tabfm -->|"uses cache"| node_cache
node_tabiclv2 -->|"uses cache"| node_cache
node_user -.->|"uses ensembles"| node_ensemble

click node_table "https://github.com/nvidia/structured-data-models/blob/main/sdm/tensor/table.py"
click node_tensor_types "https://github.com/nvidia/structured-data-models/tree/main/sdm/tensor"
click node_tensor_io "https://github.com/nvidia/structured-data-models/tree/main/sdm/tensor/io"
click node_processors "https://github.com/nvidia/structured-data-models/tree/main/sdm/processing"
click node_recipes "https://github.com/nvidia/structured-data-models/blob/main/sdm/processing/recipe.py"
click node_model_api "https://github.com/nvidia/structured-data-models/blob/main/sdm/models/base.py"
click node_tabiclv2 "https://github.com/nvidia/structured-data-models/tree/main/sdm/models/tabiclv2"
click node_tabfm "https://github.com/nvidia/structured-data-models/tree/main/sdm/models/tabfm"
click node_kumo_tabular "https://github.com/nvidia/structured-data-models/tree/main/sdm/models/kumo/tabular"
click node_kumo_relational "https://github.com/nvidia/structured-data-models/tree/main/sdm/models/kumo/relational"
click node_timesfm "https://github.com/nvidia/structured-data-models/tree/main/sdm/models/timesfm3"
click node_evaluation "https://github.com/nvidia/structured-data-models/blob/main/sdm/evaluation/classification.py"
click node_explanation "https://github.com/nvidia/structured-data-models/tree/main/sdm/explain"
click node_relational_data "https://github.com/nvidia/structured-data-models/blob/main/sdm/relational/data.py"
click node_relational_task "https://github.com/nvidia/structured-data-models/blob/main/sdm/relational/task.py"
click node_relational_join "https://github.com/nvidia/structured-data-models/blob/main/sdm/relational/join.py"
click node_nn "https://github.com/nvidia/structured-data-models/blob/main/sdm/nn/attention.py"
click node_cache "https://github.com/nvidia/structured-data-models/blob/main/sdm/cache.py"
click node_memory "https://github.com/nvidia/structured-data-models/blob/main/sdm/_memory.py"
click node_ensemble "https://github.com/nvidia/structured-data-models/blob/main/sdm/ensemble.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_table,node_tensor_types,node_tensor_io toneBlue
class node_processors,node_recipes toneAmber
class node_model_api,node_tabiclv2,node_tabfm,node_kumo_tabular,node_kumo_relational,node_timesfm,node_evaluation,node_explanation toneMint
class node_relational_data,node_relational_task,node_relational_join toneRose
class node_nn,node_cache,node_memory,node_ensemble,node_user,node_dataframe toneIndigo
```

## Components

### Tensor semantics

- [TableTensor](https://github.com/nvidia/structured-data-models/blob/main/sdm/tensor/table.py): `sdm/tensor/table.py`
- [Typed tensors](https://github.com/nvidia/structured-data-models/tree/main/sdm/tensor): `sdm/tensor`
- [Dataframe converters](https://github.com/nvidia/structured-data-models/tree/main/sdm/tensor/io): `sdm/tensor/io`

### Data processing

- [Pre/postprocessors](https://github.com/nvidia/structured-data-models/tree/main/sdm/processing): `sdm/processing`
- [Processing recipes](https://github.com/nvidia/structured-data-models/blob/main/sdm/processing/recipe.py): `sdm/processing/recipe.py`

### Model families

- [Model interface](https://github.com/nvidia/structured-data-models/blob/main/sdm/models/base.py): `sdm/models/base.py`
- [TabICLv2](https://github.com/nvidia/structured-data-models/tree/main/sdm/models/tabiclv2): `sdm/models/tabiclv2`
- [TabFM](https://github.com/nvidia/structured-data-models/tree/main/sdm/models/tabfm): `sdm/models/tabfm`
- [KumoTabular](https://github.com/nvidia/structured-data-models/tree/main/sdm/models/kumo/tabular): `sdm/models/kumo/tabular`
- [KumoRelational](https://github.com/nvidia/structured-data-models/tree/main/sdm/models/kumo/relational): `sdm/models/kumo/relational`
- [TimesFM3](https://github.com/nvidia/structured-data-models/tree/main/sdm/models/timesfm3): `sdm/models/timesfm3`
- [Classification evaluation](https://github.com/nvidia/structured-data-models/blob/main/sdm/evaluation/classification.py): `sdm/evaluation/classification.py`
- [Model explanations](https://github.com/nvidia/structured-data-models/tree/main/sdm/explain): `sdm/explain`

### Relational learning

- [Relational data](https://github.com/nvidia/structured-data-models/blob/main/sdm/relational/data.py): `sdm/relational/data.py`
- [Relational tasks](https://github.com/nvidia/structured-data-models/blob/main/sdm/relational/task.py): `sdm/relational/task.py`
- [Relational joins](https://github.com/nvidia/structured-data-models/blob/main/sdm/relational/join.py): `sdm/relational/join.py`

### Shared runtime

- [Neural network layers](https://github.com/nvidia/structured-data-models/blob/main/sdm/nn/attention.py): `sdm/nn/attention.py`
- [Inference cache](https://github.com/nvidia/structured-data-models/blob/main/sdm/cache.py): `sdm/cache.py`
- [Memory utilities](https://github.com/nvidia/structured-data-models/blob/main/sdm/_memory.py): `sdm/_memory.py`
- [Model ensembles](https://github.com/nvidia/structured-data-models/blob/main/sdm/ensemble.py): `sdm/ensemble.py`

### Other components

- **Data scientist**
- **Input dataframe**

## Connections

- Data scientist → Input dataframe: provides data (evidence: `README.md`)
- Data scientist → TableTensor: constructs (evidence: `README.md`)
- Input dataframe → Dataframe converters: converts from (evidence: `README.md`)
- Dataframe converters → TableTensor: builds (evidence: `sdm/tensor/table.py`)
- TableTensor → Typed tensors: uses tensor types (evidence: `sdm/tensor/table.py`)
- Data scientist → Model interface: invokes prediction (evidence: `README.md`)
- Model interface → TabICLv2: unified interface (evidence: `README.md`)
- Model interface → TabFM: unified interface (evidence: `README.md`)
- Model interface → KumoTabular: unified interface (evidence: `README.md`)
- Model interface → KumoRelational: unified interface (evidence: `README.md`)
- Model interface → TimesFM3: model family
- Data scientist → Pre/postprocessors: preprocesses data
- Pre/postprocessors → Processing recipes: composes processors (evidence: `sdm/processing/__init__.py`)
- TableTensor → Relational data: combines with
- Relational tasks → Relational joins: uses joins (evidence: `sdm/relational/task.py`)
- Data scientist → Classification evaluation: evaluates predictions
- Data scientist → Model explanations: requests explanations
- Model interface → Inference cache: records fit state (evidence: `README.md`)
- TabFM → Neural network layers: uses layers
- TabFM → Memory utilities: checks memory (evidence: `sdm/models/tabfm/cell_embedding.py`)
- KumoTabular → Inference cache: uses cache (evidence: `sdm/models/kumo/tabular/row_embedding.py`)
- TabFM → Inference cache: uses cache (evidence: `sdm/models/tabfm/row_embedding.py`)
- TabICLv2 → Inference cache: uses cache (evidence: `sdm/models/tabiclv2/row_embedding.py`)
- Data scientist → Model ensembles: uses ensembles
