# yewzz/eager architecture

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

- Interactive diagram: https://gitdiagram.com/yewzz/eager
- Repository: https://github.com/yewzz/eager

## Overview

##### Main components
- Data Preparation & Preprocessing:
– This is initiated via the preprocessing step described in the README (i.e. running “train_rec.py” with the raw data file) to prepare 5-core data from the Amazon dataset.
- Model Components in the Library:
– Under EAGER/lib, you have various modules implementing different model types: DIN_Model.py (for behavior modeling), HF_Model.py, Tree_Model.py, and a set of trainer modules (e.g., DIN_trainer.py, Trm4Rec_trainer.py).
– The transformer subdirectory includes encoder, decoder, multihead attention, and positional embedding implementations, hinting at deep learning architectures with attention mechanisms.
– Utility modules like "generate_training_batches.py" and "generate_train_and_test_data.py" indicate data batching and train-test split orchestration.
– “st_gumbel.py” and “t5_modules.py” indicate usages of specialized sampling or sequence-to-sequence modules, possibly for generating recommendations.
- Optimizers & Learning Rate Schedulers:
– The EAGER/optimizers directory contains custom implementations and wrappers for optimizers (adam, base optimizers) along with various learning rate schedulers (cosine, inverse_sqrt, triangular, etc.). This set-up is important for model training dynamics.
- Training Scripts:
– “train_din.py” for training the DIN (behavior code encoder) model.
– “train_rec.py” and “train_rec_gowalla.py” are used for the main recommendation training procedures, where “train_rec.py” also integrates the pre-trained DIN model as mentioned in the README.
- External Dependencies and Baselines:
– The README references the RecForest repository, which indicates that some framework concepts or structures might be borrowed from there.

##### Relationships and interactions
- Data flows from raw data to preprocessing (via the data generation scripts) and then feeding into both the DIN model and the overall recommendation framework.
- The trainer components (DIN_trainer.py, Trm4Rec_trainer.py) interact with the model components in lib (DIN_Model, Tree_Model, etc.) and use the transformers for parts of the model architecture.
- Optimizers and learning rate schedulers are used in the training processes, linking the training scripts to the optimizer modules.
- The outputs of the DIN training (a checkpoint file) serve as input for the overall recommendation training in “train_rec.py”, demonstrating a dependency between a preliminary behavior-coding stage and the final recommendation model training.

##### Architectural patterns and design principles
- Modular Design: The project is clearly structured into separate directories for models, training routines, and optimizers. This indicates a well-modularized design for ease of scalability and maintainability.
- Separation of Concerns: Each module (e.g., model definitions, data batching, training routines, optimizers) has its own role, which is a standard design principle in machine learning systems.
- Custom Optimizer Configuration: The inclusion of multiple scheduling strategies shows an emphasis on fine-tuned training control – beneficial for a research-grade recommender system.

##### Relevant technologies, frameworks, or libraries
- PyTorch: The entire implementation is based on PyTorch, so all model and training components revolve around it.
- Transformer Architecture: The transformer subdirectory suggests that the implementation leverages attention-based mechanisms, possibly enhanced or combined with DIN’s behavior modeling.
- Custom Learning Rate Scheduling: Various LR schedulers indicate intricate training dynamics that should be highlighted.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Data & Preprocessing Layer
    subgraph "Data & Preprocessing"
        DP1["Generate Train & Test Data"]:::preprocessing
        DP2["Generate Training Batches"]:::preprocessing
    end

    %% Model Components Layer
    subgraph "Model Components"
        subgraph "Behavior Modeling"
            DIN["DIN Model (Behavior)"]:::model
        end
        subgraph "Generative Recommendation"
            HF["HF Model"]:::model
            Tree["Tree Model"]:::model
            KMeans["Kmeans Tree"]:::model
            subgraph "Transformer Modules"
                Encoder["Encoder"]:::model
                Decoder["Decoder"]:::model
                Multihead["Multihead Attention"]:::model
                Positional["Positional Embedding"]:::model
            end
            stGumbel["st_gumbel"]:::model
            t5Modules["t5_modules"]:::model
        end
    end

    %% Trainer Modules Layer
    subgraph "Trainer Modules"
        DINTrainer["DIN Trainer"]:::trainer
        Trm4RecTrainer["Trm4Rec Trainer"]:::trainer
    end

    %% Training Scripts Layer
    subgraph "Training Scripts"
        TrainDIN["train_din.py"]:::trainingScript
        TrainRec["train_rec.py"]:::trainingScript
        TrainRecGow["train_rec_gowalla.py"]:::trainingScript
    end

    %% Optimizers & Schedulers Layer
    subgraph "Optimizers & Schedulers"
        Adam["adam_optimizer"]:::optimizer
        BaseOpt["base_optimizer"]:::optimizer
        Cosine["Cosine LR Scheduler"]:::optimizer
        Fairseq["Fairseq LR Scheduler"]:::optimizer
        Fixed["Fixed Schedule"]:::optimizer
        InverseLinear["Inverse Linear Root Schedule"]:::optimizer
        InverseSquare["Inverse Square Root Schedule"]:::optimizer
        ReduceLR["Reduce LR on Plateau"]:::optimizer
        Triangular["Triangular LR Scheduler"]:::optimizer
    end

    %% External Dependency
    External["RecForest Framework (External)"]:::external

    %% Data Flow
    DP1 -->|"feeds raw data"| DP2
    DP2 -->|"provides preprocessed data"| DIN
    DP2 -->|"provides preprocessed data"| HF
    DP2 -->|"provides preprocessed data"| Tree
    DP2 -->|"provides preprocessed data"| KMeans

    %% Generative branch enhancement with transformer modules
    HF ---|"integrates with"| Encoder
    HF ---|"integrates with"| Decoder
    HF ---|"integrates with"| Multihead
    HF ---|"integrates with"| Positional

    %% Model to Trainer connections
    DIN --> DINTrainer
    HF --> Trm4RecTrainer
    Tree --> Trm4RecTrainer
    KMeans --> Trm4RecTrainer
    Encoder --> Trm4RecTrainer
    Decoder --> Trm4RecTrainer
    Multihead --> Trm4RecTrainer
    Positional --> Trm4RecTrainer
    stGumbel --> Trm4RecTrainer
    t5Modules --> Trm4RecTrainer

    %% Trainer to Training Scripts connections
    DINTrainer -->|"checkpoint feeds into"| TrainRec
    TrainDIN --> DINTrainer
    Trm4RecTrainer --> TrainRec
    TrainRecGow --> Trm4RecTrainer

    %% Trainer dependency on Optimizers & Schedulers
    DINTrainer --> Adam
    DINTrainer --> BaseOpt
    DINTrainer --> Cosine
    DINTrainer --> Fairseq
    DINTrainer --> Fixed
    DINTrainer --> InverseLinear
    DINTrainer --> InverseSquare
    DINTrainer --> ReduceLR
    DINTrainer --> Triangular

    Trm4RecTrainer --> Adam
    Trm4RecTrainer --> BaseOpt
    Trm4RecTrainer --> Cosine
    Trm4RecTrainer --> Fairseq
    Trm4RecTrainer --> Fixed
    Trm4RecTrainer --> InverseLinear
    Trm4RecTrainer --> InverseSquare
    Trm4RecTrainer --> ReduceLR
    Trm4RecTrainer --> Triangular

    %% External influence
    External -.-> DINTrainer
    External -.-> Trm4RecTrainer

    %% Click Events for Component Mapping
    click DP1 "https://github.com/yewzz/eager/blob/main/EAGER/lib/generate_train_and_test_data.py"
    click DP2 "https://github.com/yewzz/eager/blob/main/EAGER/lib/generate_training_batches.py"
    click DIN "https://github.com/yewzz/eager/blob/main/EAGER/lib/DIN_Model.py"
    click HF "https://github.com/yewzz/eager/blob/main/EAGER/lib/HF_Model.py"
    click Tree "https://github.com/yewzz/eager/blob/main/EAGER/lib/Tree_Model.py"
    click KMeans "https://github.com/yewzz/eager/blob/main/EAGER/lib/KmeansTree.py"
    click Encoder "https://github.com/yewzz/eager/blob/main/EAGER/lib/transformer/encoder.py"
    click Decoder "https://github.com/yewzz/eager/blob/main/EAGER/lib/transformer/decoder.py"
    click Multihead "https://github.com/yewzz/eager/blob/main/EAGER/lib/transformer/multihead_attention.py"
    click Positional "https://github.com/yewzz/eager/blob/main/EAGER/lib/transformer/sinusoidal_positional_embedding.py"
    click DINTrainer "https://github.com/yewzz/eager/blob/main/EAGER/lib/DIN_trainer.py"
    click Trm4RecTrainer "https://github.com/yewzz/eager/blob/main/EAGER/lib/Trm4Rec_trainer.py"
    click stGumbel "https://github.com/yewzz/eager/blob/main/EAGER/lib/st_gumbel.py"
    click t5Modules "https://github.com/yewzz/eager/blob/main/EAGER/lib/t5_modules.py"
    click Adam "https://github.com/yewzz/eager/blob/main/EAGER/optimizers/adam_optimizer.py"
    click BaseOpt "https://github.com/yewzz/eager/blob/main/EAGER/optimizers/base_optimizer.py"
    click Cosine "https://github.com/yewzz/eager/blob/main/EAGER/optimizers/lr_schedulers/cosine_lr_scheduler.py"
    click Fairseq "https://github.com/yewzz/eager/blob/main/EAGER/optimizers/lr_schedulers/fairseq_lr_scheduler.py"
    click Fixed "https://github.com/yewzz/eager/blob/main/EAGER/optimizers/lr_schedulers/fixed_schedule.py"
    click InverseLinear "https://github.com/yewzz/eager/blob/main/EAGER/optimizers/lr_schedulers/inverse_linear_root_schedule.py"
    click InverseSquare "https://github.com/yewzz/eager/blob/main/EAGER/optimizers/lr_schedulers/inverse_square_root_schedule.py"
    click ReduceLR "https://github.com/yewzz/eager/blob/main/EAGER/optimizers/lr_schedulers/reduce_lr_on_plateau.py"
    click Triangular "https://github.com/yewzz/eager/blob/main/EAGER/optimizers/lr_schedulers/triangular_lr_scheduler.py"
    click TrainDIN "https://github.com/yewzz/eager/blob/main/train_din.py"
    click TrainRec "https://github.com/yewzz/eager/blob/main/train_rec.py"
    click TrainRecGow "https://github.com/yewzz/eager/blob/main/train_rec_gowalla.py"

    %% Styles
    classDef preprocessing fill:#FAD7A0,stroke:#333,stroke-width:2px;
    classDef model fill:#AED6F1,stroke:#333,stroke-width:2px;
    classDef trainer fill:#D5F5E3,stroke:#333,stroke-width:2px;
    classDef trainingScript fill:#F5CBA7,stroke:#333,stroke-width:2px;
    classDef optimizer fill:#F9E79F,stroke:#333,stroke-width:2px;
    classDef external fill:#E8DAEF,stroke:#333,stroke-width:2px;
```
