# meta-recsys/generative-recommenders architecture

> Architecture diagram of the GitHub repository meta-recsys/generative-recommenders, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-13). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/meta-recsys/generative-recommenders
- Repository: https://github.com/meta-recsys/generative-recommenders

## Overview

##### Project Type & Purpose
- Type: Research / open-source codebase for sequential recommender systems re-formulated as generative models.
- Purpose:
– Preprocess and generate datasets (public MovieLens/Amazon & synthetic fractal expansion).
– Train generative recommenders (HSTU, M-FALCON, DLRM-v3) at scale on GPUs.
– Run inference benchmarks (MLPerf LoadGen integration) and efficiency experiments with CUDA & Triton kernels.

##### Top-Level Components
a. Data Layer
– Raw public data (MovieLens, Amazon Reviews).
– Synthetic data generator (run_fractal_expansion.py).
– Preprocess scripts (preprocess_public_data.py).
– Output: standardized Tensor/CSV datasets under tmp/.
b. Configuration
– gin-config files in configs/ (per-dataset, per-method).
– requirements.txt, setup.py define environment & dependencies.
c. Training Pipeline
– Entry points:
- main.py – orchestrates public experiments (Section 4.1.1).
- generative_recommenders/dlrm_v3/train/train_ranker.py – DLRM‐v3 multi‐GPU training.
– Core modules:
- generative_recommenders/modules/… – feature encoders, attention, STU transducers, preprocessors.
- generative_recommenders/ops/… – optimized kernels in C++/CUDA and Triton (FlashAttention V3, jagged tensors, etc.).
– Dataflow: raw → preprocess → batched tensors → forward/backward through modules → checkpoint.
– Logging: tensorboard under exps/.
d. Inference Pipeline
– Entry points:
- generative_recommenders/dlrm_v3/inference/main.py – MLPerf LoadGen integration.
– Components:
- LoadGen library (thirdparty/loadgen) linked via Python/C API.
- inference_modules.py – wraps model family to respond to LoadGen queries.
- DataProducer – feeds preprocessed data.
– Output: latency & throughput measurements.
e. Research Playground
– generative_recommenders/research/… – data loaders, candidate indexing, sequence modeling modules, sequential losses.
– Allows developing new ranking / similarity algorithms.
f. Efficiency Experiments
– generative_recommenders/ops/cpp/hstu_attention – FlashAttention‐based CUDA kernels.
– generative_recommenders/ops/triton – Triton kernels for end‐to‐end GPU performance testing.

##### Relationships & Data Flows
- Data Layer → Preprocess Scripts → Dataset
- Dataset + gin-config → Training Entry (main.py or train_ranker.py)
- Training → Modules + Ops (C++/CUDA/Triton) → Checkpoints
- Checkpoints + LoadGen → Inference Entry → Metrics
- Research modules can hook into Data Layer and Modules to prototype new algorithms.
– Show “configuration” as a sidecar component feeding both training and inference.

##### Architectural Patterns & Design Principles
- Modular design: Python “modules/” define abstract building blocks; “ops/” provide backend acceleration.
- Separation of concerns:
– Data‐preprocessing vs. model logic vs. optimized kernel implementations.
– CLI drivers (main.py, train_ranker.py, inference/main.py) orchestrate high-level workflows.
- Extensibility: dropping in new gin configs, research code, or optimized kernels without touching orchestration scripts.
- Scalability: multi‐GPU support via PyTorch distributed, LoadGen benchmarking, fractal data expansion.

[ ] Components: Data, Config, Training (main.py & train_ranker.py), Modules, Ops, Inference (main.py), Research
[ ] Labels: directory names, scripts, kernels, data artifacts
[ ] Notes: GPU cluster, multi-process orchestration, tensorboard logging, LoadGen integration

## Diagram (Mermaid)

```mermaid
graph TD
    %% Data Layer
    subgraph "Data Layer"
        direction TB
        RawData["Raw Public Data (MovieLens/Amazon)"]:::data
        Fractal["run_fractal_expansion.py"]:::python
        click Fractal "https://github.com/meta-recsys/generative-recommenders/blob/main/run_fractal_expansion.py"
        PreprocessScript["preprocess_public_data.py"]:::python
        click PreprocessScript "https://github.com/meta-recsys/generative-recommenders/blob/main/preprocess_public_data.py"
        subgraph "Dataset Modules"
            direction TB
            ML["movie_lens.py"]:::data
            click ML "https://github.com/meta-recsys/generative-recommenders/blob/main/generative_recommenders/dlrm_v3/datasets/movie_lens.py"
            AR["amazon_reviews (kuairand.py)"]:::data
            click AR "https://github.com/meta-recsys/generative-recommenders/blob/main/generative_recommenders/dlrm_v3/datasets/amazon_reviews/kuairand.py"
            Synth["synthetic_movie_lens.py"]:::data
            click Synth "https://github.com/meta-recsys/generative-recommenders/blob/main/generative_recommenders/dlrm_v3/datasets/synthetic_movie_lens.py"
        end
    end

    %% Configuration
    subgraph "Configuration"
        direction TB
        GinConfigs["configs/ (.gin files)"]:::external
        Requirements["requirements.txt"]:::external
        click Requirements "https://github.com/meta-recsys/generative-recommenders/blob/main/requirements.txt"
        Setup["setup.py"]:::external
        click Setup "https://github.com/meta-recsys/generative-recommenders/blob/main/setup.py"
    end

    %% Training Pipeline
    subgraph "Training Pipeline"
        direction TB
        Main["main.py"]:::python
        click Main "https://github.com/meta-recsys/generative-recommenders/blob/main/main.py"
        TrainRanker["train_ranker.py"]:::python
        click TrainRanker "https://github.com/meta-recsys/generative-recommenders/blob/main/generative_recommenders/dlrm_v3/train/train_ranker.py"
        Utils["utils.py"]:::python
        click Utils "https://github.com/meta-recsys/generative-recommenders/blob/main/generative_recommenders/dlrm_v3/train/utils.py"
        TrainTests["train_test.py"]:::python
        click TrainTests "https://github.com/meta-recsys/generative-recommenders/blob/main/generative_recommenders/dlrm_v3/train/tests/train_test.py"
        Checkpoint["checkpoint.py"]:::python
        click Checkpoint "https://github.com/meta-recsys/generative-recommenders/blob/main/generative_recommenders/dlrm_v3/checkpoint.py"
    end

    %% Core Modules
    subgraph "Model Logic Modules"
        direction TB
        ActionEnc["action_encoder.py"]:::python
        click ActionEnc "https://github.com/meta-recsys/generative-recommenders/blob/main/generative_recommenders/modules/action_encoder.py"
        DynamicSTU["dynamic_stu.py"]:::python
        click DynamicSTU "https://github.com/meta-recsys/generative-recommenders/blob/main/generative_recommenders/modules/dynamic_stu.py"
        HSTUTrans["hstu_transducer.py"]:::python
        click HSTUTrans "https://github.com/meta-recsys/generative-recommenders/blob/main/generative_recommenders/modules/hstu_transducer.py"
    end

    %% Optimization Kernels
    subgraph "Optimization Kernels"
        direction TB
        subgraph "C++/CUDA Kernels"
            direction TB
            HSTUAttnCPP["hstu_attention (C++/CUDA)"]:::cu
            click HSTUAttnCPP "https://github.com/meta-recsys/generative-recommenders/tree/main/generative_recommenders/ops/cpp/hstu_attention"
            CUDAWrap1["cuda_hstu_attention.py"]:::python
            click CUDAWrap1 "https://github.com/meta-recsys/generative-recommenders/blob/main/generative_recommenders/ops/cpp/cuda_hstu_attention.py"
            CUDAWrap2["cuda_hstu_preprocess_and_attention.py"]:::python
            click CUDAWrap2 "https://github.com/meta-recsys/generative-recommenders/blob/main/generative_recommenders/ops/cpp/cuda_hstu_preprocess_and_attention.py"
        end
        subgraph "PyTorch Bindings"
            direction TB
            PTHSTU["pt_hstu_attention.py"]:::python
            click PTHSTU "https://github.com/meta-recsys/generative-recommenders/blob/main/generative_recommenders/ops/pytorch/pt_hstu_attention.py"
            PTJagged["pt_jagged.py"]:::python
            click PTJagged "https://github.com/meta-recsys/generative-recommenders/blob/main/generative_recommenders/ops/pytorch/pt_jagged.py"
        end
        subgraph "Triton Kernels"
            direction TB
            TritonSTU["triton_hstu_attention.py"]:::python
            click TritonSTU "https://github.com/meta-recsys/generative-recommenders/blob/main/generative_recommenders/ops/triton/triton_hstu_attention.py"
            TritonJagged["triton_jagged_tensors.py"]:::python
            click TritonJagged "https://github.com/meta-recsys/generative-recommenders/blob/main/generative_recommenders/ops/triton/triton_jagged_tensors.py"
        end
    end

    %% Inference Pipeline
    subgraph "Inference Pipeline"
        direction TB
        InfMain["inference/main.py"]:::python
        click InfMain "https://github.com/meta-recsys/generative-recommenders/blob/main/generative_recommenders/dlrm_v3/inference/main.py"
        InfMods["inference_modules.py"]:::python
        click InfMods "https://github.com/meta-recsys/generative-recommenders/blob/main/generative_recommenders/dlrm_v3/inference/inference_modules.py"
        DataProd["data_producer.py"]:::python
        click DataProd "https://github.com/meta-recsys/generative-recommenders/blob/main/generative_recommenders/dlrm_v3/inference/data_producer.py"
        ModelFam["model_family.py"]:::python
        click ModelFam "https://github.com/meta-recsys/generative-recommenders/blob/main/generative_recommenders/dlrm_v3/inference/model_family.py"
        subgraph "LoadGen Library"
            direction TB
            LoadGen["thirdparty/loadgen"]:::external
            click LoadGen "https://github.com/meta-recsys/generative-recommenders/tree/main/generative_recommenders/dlrm_v3/inference/thirdparty/loadgen/"
        end
        InfTest["inference_test.py"]:::python
        click InfTest "https://github.com/meta-recsys/generative-recommenders/blob/main/generative_recommenders/dlrm_v3/inference/tests/inference_test.py"
    end

    %% Research Playground
    subgraph "Research Playground"
        direction TB
        subgraph "Data & Preprocessors"
            direction TB
            RData["data/"]:::python
            click RData "https://github.com/meta-recsys/generative-recommenders/tree/main/generative_recommenders/research/data/"
        end
        subgraph "Candidate Indexing"
            direction TB
            RIndex["indexing/"]:::python
            click RIndex "https://github.com/meta-recsys/generative-recommenders/tree/main/generative_recommenders/research/indexing/"
        end
        subgraph "Modeling & Losses"
            direction TB
            SeqModel["sequential/"]:::python
            click SeqModel "https://github.com/meta-recsys/generative-recommenders/tree/main/generative_recommenders/research/modeling/sequential/"
            SimMod["similarity_module.py"]:::python
            click SimMod "https://github.com/meta-recsys/generative-recommenders/blob/main/generative_recommenders/research/modeling/similarity_module.py"
            SimUtils["similarity_utils.py"]:::python
            click SimUtils "https://github.com/meta-recsys/generative-recommenders/blob/main/generative_recommenders/research/modeling/similarity_utils.py"
        end
        subgraph "RAILS Extensions"
            direction TB
            Rails["rails/"]:::python
            click Rails "https://github.com/meta-recsys/generative-recommenders/tree/main/generative_recommenders/research/rails/"
        end
        subgraph "Research Trainer"
            direction TB
            RTrainer["train.py"]:::python
            click RTrainer "https://github.com/meta-recsys/generative-recommenders/blob/main/generative_recommenders/research/trainer/train.py"
            RDataLoader["data_loader.py"]:::python
            click RDataLoader "https://github.com/meta-recsys/generative-recommenders/blob/main/generative_recommenders/research/trainer/data_loader.py"
        end
    end

    %% Experiments Logging
    Exps["exps/ (TensorBoard logs)"]:::external

    %% Relationships
    RawData --> PreprocessScript
    Fractal --> PreprocessScript
    PreprocessScript --> ML
    PreprocessScript --> AR
    PreprocessScript --> Synth
    ML --> Main
    AR --> Main
    Synth --> Main
    GinConfigs -.-> Main
    Requirements -.-> Main
    Setup -.-> Main
    Main --> ActionEnc
    Main --> DynamicSTU
    Main --> HSTUTrans
    Main --> Utils
    TrainRanker --> ActionEnc
    TrainRanker --> DynamicSTU
    TrainRanker --> HSTUTrans
    TrainRanker --> Checkpoint
    TrainRanker -->|PyTorch DDP| Exps
    Checkpoint --> InfMain
    GinConfigs -.-> InfMain
    Requirements -.-> InfMain
    Setup -.-> InfMain
    InfMain --> LoadGen
    InfMain --> InfMods
    InfMods --> DataProd
    DataProd --> ModelFam
    LoadGen --> InfMods
    ModelFam --> InfTest
    %% OCR: Training uses Ops
    TrainRanker --> HSTUAttnCPP
    TrainRanker --> CUDAWrap1
    TrainRanker --> CUDAWrap2
    TrainRanker --> PTHSTU
    TrainRanker --> PTJagged
    TrainRanker --> TritonSTU
    TrainRanker --> TritonJagged
    %% Research integration
    RData --> ActionEnc
    RIndex --> HSTUTrans
    SeqModel --> HSTUTrans
    SimMod --> HSTUTrans
    Rails --> HSTUTrans

    %% Styles
    classDef data fill:#CFE2F3,stroke:#036; 
    classDef python fill:#D9EAD3,stroke:#090; 
    classDef cu fill:#F9CB9C,stroke:#E69138; 
    classDef external fill:#EDEDED,stroke:#AAA;
```
