# snap-research/grid architecture

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

- Interactive diagram: https://gitdiagram.com/snap-research/grid
- Repository: https://github.com/snap-research/grid

## Overview

GRID is a generative-recommendation framework whose main workflow turns item text into language-model embeddings, learns hierarchical semantic IDs by quantization, then trains and runs a TIGER transformer to generate recommendations from user histories. The README documents this staged handoff and supported semantic-ID approaches; source-index references and excerpts show the runtime entry point, clustering abstractions, model blocks, and data contracts. Several feature internals are unsampled, so the graph preserves their documented roles without asserting unverified implementation-level calls.

Main entry points: [`src/models/modules/semantic_id/tiger_generation_model.py`](https://github.com/snap-research/grid/blob/main/src/models/modules/semantic_id/tiger_generation_model.py) (TIGER generation model), [`src/models/modules/clustering/base_clustering_module.py`](https://github.com/snap-research/grid/blob/main/src/models/modules/clustering/base_clustering_module.py) (Clustering base), [`src/inference.py`](https://github.com/snap-research/grid/blob/main/src/inference.py) (Inference entry), [`src/modules/semantic_embedding_inference_module.py`](https://github.com/snap-research/grid/blob/main/src/modules/semantic_embedding_inference_module.py) (Embedding inference)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Runtime orchestration"]
  node_train["Training entry<br/>[train.py]"]
  node_infer["Inference entry<br/>[inference.py]"]
  node_launcher["Pipeline launcher<br/>[launcher_utils.py]"]
end

subgraph group_data["Data and embeddings"]
  node_datafiles["Prepared datasets"]
  node_seqdata["Sequence data module"]
  node_loadparts["Loading components"]
  node_embedinfer["Embedding inference"]
  node_language["HuggingFace language model"]
  node_embedout["Item embeddings"]
end

subgraph group_sid["Semantic ID learning"]
  node_quant["Residual quantization"]
  node_vq["Vector quantization"]
  node_kmeans["Mini-batch k-means"]
  node_clusterbase["Clustering base"]
  node_clusterops["Clustering primitives"]
  node_sidout["Semantic IDs"]
end

subgraph group_recommend["Generative recommendation"]
  node_tiger["TIGER generation model"]
  node_transformer["Transformer base"]
  node_aggregation["Embedding aggregation"]
  node_predictions["Generated recommendations"]
  node_modelcontracts["Model interfaces<br/>[interfaces.py]"]
end

node_user(("Researcher"))

node_user -->|"runs inference"| node_infer
node_user -->|"runs training"| node_train
node_train -->|"launches pipeline"| node_launcher
node_infer -->|"launches pipeline"| node_launcher
node_user -->|"prepares data"| node_datafiles
node_datafiles -->|"loads sequences"| node_seqdata
node_seqdata -->|"uses components"| node_loadparts
node_user -->|"generates embeddings"| node_embedinfer
node_embedinfer -->|"uses model"| node_language
node_embedinfer -->|"produces embeddings"| node_embedout
node_embedout -->|"learns IDs from"| node_quant
node_quant -->|"extends clustering"| node_clusterbase
node_vq -->|"uses base module"| node_clusterbase
node_kmeans -->|"extends base module"| node_clusterbase
node_clusterbase -->|"initializes centroids"| node_clusterops
node_quant -->|"produces IDs"| node_sidout
node_sidout -->|"trains on IDs"| node_tiger
node_tiger -->|"uses base"| node_transformer
node_transformer -->|"uses aggregator"| node_aggregation
node_tiger -->|"uses interfaces"| node_modelcontracts
node_tiger -->|"generates recommendations"| node_predictions
node_infer -->|"returns predictions"| node_predictions

click node_train "https://github.com/snap-research/grid/blob/main/src/train.py"
click node_infer "https://github.com/snap-research/grid/blob/main/src/inference.py"
click node_launcher "https://github.com/snap-research/grid/blob/main/src/utils/launcher_utils.py"
click node_seqdata "https://github.com/snap-research/grid/blob/main/src/data/loading/datamodules/sequence_datamodule.py"
click node_loadparts "https://github.com/snap-research/grid/tree/main/src/data/loading/components"
click node_embedinfer "https://github.com/snap-research/grid/blob/main/src/modules/semantic_embedding_inference_module.py"
click node_language "https://github.com/snap-research/grid/blob/main/src/components/network_blocks/hf_language_model.py"
click node_quant "https://github.com/snap-research/grid/blob/main/src/modules/clustering/residual_quantization.py"
click node_vq "https://github.com/snap-research/grid/blob/main/src/modules/clustering/vector_quantization.py"
click node_kmeans "https://github.com/snap-research/grid/blob/main/src/models/modules/clustering/mini_batch_kmeans.py"
click node_clusterbase "https://github.com/snap-research/grid/blob/main/src/models/modules/clustering/base_clustering_module.py"
click node_clusterops "https://github.com/snap-research/grid/blob/main/src/components/clustering_initializers.py"
click node_tiger "https://github.com/snap-research/grid/blob/main/src/models/modules/semantic_id/tiger_generation_model.py"
click node_transformer "https://github.com/snap-research/grid/blob/main/src/models/modules/huggingface/transformer_base_module.py"
click node_aggregation "https://github.com/snap-research/grid/blob/main/src/models/components/network_blocks/embedding_aggregator.py"
click node_modelcontracts "https://github.com/snap-research/grid/blob/main/src/models/components/interfaces.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_train,node_infer,node_launcher toneBlue
class node_datafiles,node_seqdata,node_loadparts,node_embedinfer,node_language,node_embedout toneAmber
class node_quant,node_vq,node_kmeans,node_clusterbase,node_clusterops,node_sidout toneMint
class node_tiger,node_transformer,node_aggregation,node_predictions,node_modelcontracts toneRose
class node_user toneIndigo
```

## Components

### Runtime orchestration

- [Training entry](https://github.com/snap-research/grid/blob/main/src/train.py): `src/train.py`
- [Inference entry](https://github.com/snap-research/grid/blob/main/src/inference.py): `src/inference.py`
- [Pipeline launcher](https://github.com/snap-research/grid/blob/main/src/utils/launcher_utils.py): `src/utils/launcher_utils.py`

### Data and embeddings

- **Prepared datasets**
- [Sequence data module](https://github.com/snap-research/grid/blob/main/src/data/loading/datamodules/sequence_datamodule.py): `src/data/loading/datamodules/sequence_datamodule.py`
- [Loading components](https://github.com/snap-research/grid/tree/main/src/data/loading/components): `src/data/loading/components`
- [Embedding inference](https://github.com/snap-research/grid/blob/main/src/modules/semantic_embedding_inference_module.py): `src/modules/semantic_embedding_inference_module.py`
- [HuggingFace language model](https://github.com/snap-research/grid/blob/main/src/components/network_blocks/hf_language_model.py): `src/components/network_blocks/hf_language_model.py`
- **Item embeddings**

### Semantic ID learning

- [Residual quantization](https://github.com/snap-research/grid/blob/main/src/modules/clustering/residual_quantization.py): `src/modules/clustering/residual_quantization.py`
- [Vector quantization](https://github.com/snap-research/grid/blob/main/src/modules/clustering/vector_quantization.py): `src/modules/clustering/vector_quantization.py`
- [Mini-batch k-means](https://github.com/snap-research/grid/blob/main/src/models/modules/clustering/mini_batch_kmeans.py): `src/models/modules/clustering/mini_batch_kmeans.py`
- [Clustering base](https://github.com/snap-research/grid/blob/main/src/models/modules/clustering/base_clustering_module.py): `src/models/modules/clustering/base_clustering_module.py`
- [Clustering primitives](https://github.com/snap-research/grid/blob/main/src/components/clustering_initializers.py): `src/components/clustering_initializers.py`
- **Semantic IDs**

### Generative recommendation

- [TIGER generation model](https://github.com/snap-research/grid/blob/main/src/models/modules/semantic_id/tiger_generation_model.py): `src/models/modules/semantic_id/tiger_generation_model.py`
- [Transformer base](https://github.com/snap-research/grid/blob/main/src/models/modules/huggingface/transformer_base_module.py): `src/models/modules/huggingface/transformer_base_module.py`
- [Embedding aggregation](https://github.com/snap-research/grid/blob/main/src/models/components/network_blocks/embedding_aggregator.py): `src/models/components/network_blocks/embedding_aggregator.py`
- **Generated recommendations**
- [Model interfaces](https://github.com/snap-research/grid/blob/main/src/models/components/interfaces.py): `src/models/components/interfaces.py`

### Other components

- **Researcher**

## Connections

- Researcher → Inference entry: runs inference (evidence: `README.md`)
- Researcher → Training entry: runs training (evidence: `README.md`)
- Training entry → Pipeline launcher: launches pipeline (evidence: `src/train.py`)
- Inference entry → Pipeline launcher: launches pipeline (evidence: `src/inference.py`)
- Researcher → Prepared datasets: prepares data (evidence: `README.md`)
- Prepared datasets → Sequence data module: loads sequences (evidence: `README.md`)
- Sequence data module → Loading components: uses components (evidence: `src/data/loading/datamodules/sequence_datamodule.py`)
- Researcher → Embedding inference: generates embeddings (evidence: `README.md`)
- Embedding inference → HuggingFace language model: uses model (evidence: `src/components/network_blocks/hf_language_model.py`)
- Embedding inference → Item embeddings: produces embeddings (evidence: `README.md`)
- Item embeddings → Residual quantization: learns IDs from (evidence: `README.md`)
- Residual quantization → Clustering base: extends clustering (evidence: `src/modules/clustering/residual_quantization.py`)
- Vector quantization → Clustering base: uses base module (evidence: `src/modules/clustering/vector_quantization.py`)
- Mini-batch k-means → Clustering base: extends base module (evidence: `src/models/modules/clustering/mini_batch_kmeans.py`)
- Clustering base → Clustering primitives: initializes centroids (evidence: `src/models/modules/clustering/base_clustering_module.py`)
- Residual quantization → Semantic IDs: produces IDs (evidence: `README.md`)
- Semantic IDs → TIGER generation model: trains on IDs (evidence: `README.md`)
- TIGER generation model → Transformer base: uses base (evidence: `src/models/modules/semantic_id/tiger_generation_model.py`)
- Transformer base → Embedding aggregation: uses aggregator (evidence: `src/models/modules/huggingface/transformer_base_module.py`)
- TIGER generation model → Model interfaces: uses interfaces (evidence: `src/models/modules/semantic_id/tiger_generation_model.py`)
- TIGER generation model → Generated recommendations: generates recommendations (evidence: `README.md`)
- Inference entry → Generated recommendations: returns predictions (evidence: `README.md`)
