# mohamedaminebentayeb/llmrec architecture

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

- Interactive diagram: https://gitdiagram.com/mohamedaminebentayeb/llmrec
- Repository: https://github.com/mohamedaminebentayeb/llmrec

## Overview

##### Project Type and Purpose
- This is a research‐oriented recommendation system pipeline (“LLMRec”) that augments a user–item interaction graph using Large Language Models (LLMs) and then trains a GNN‐style recommender on the augmented data.
- Stage 1: Data augmentation via three LLM‐powered scripts.
- Stage 2: Graph‐based recommender training and evaluation.

##### File‐Structure Analysis
- Top‐level:
- LLM_augmentation_construct_prompt/ – three augmentation scripts:
– gpt_ui_aug.py (u–i edge augmentation)
– gpt_user_profiling.py (user node profiling)
– gpt_i_attribute_generate_aug.py (item attribute augmentation)
- main.py – orchestrates dataset‐loading, model instantiation & training.
- Models.py – defines GNN / recommendation architectures.
- utility/ – helper modules (data loaders, metrics, logging, command‐line parser).
- requirements.txt – lists PyTorch, OpenAI, CLIP, S‐BERT, etc.

##### README Insights
- Clearly describes the three augmentation strategies (edges, user nodes, item nodes).
- Specifies two main stages and supported datasets (netflix, movielens).
- Mentions encoders: CLIP‐ViT for images, Sentence‐BERT for text.
- Indicates use of OpenAI GPT‐3.5 & text‐embedding‐ada‐002 APIs.

a. Data Sources (leftmost)
- Raw interaction data (CF training data, basic u–i interactions)
- Original multi‐modal content: item_attribute.csv, images folder
b. LLM Augmentation Layer
1. “u–i Edge Augmentor” (gpt_ui_aug.py) → produces augmented edges
2. “User Profiling Augmentor” (gpt_user_profiling.py) → user metadata
3. “Item Attribute Augmentor” (gpt_i_attribute_generate_aug.py) → item metadata
c. Data Storage / Merge
- “Augmented Dataset Store” merges raw + augmented edges & node attributes
- Represented as CSVs / pickled tensors under data/{dataset}/
d. Recommender Training Layer
- main.py invokes:
- utility/parser.py (CLI args)
- utility/load_data.py → constructs graph structure (u–i adjacency + node features)
- Models.py → GNN layers (e.g., GraphSAGE, GAT) or matrix factorization modules
- Encoders: CLIP‐ViT & Sentence‐BERT (called once to precompute features or on‐the‐fly)
- Loss & pruning logic (prune_loss_drop_rate)
- Training loop with metrics.py and logging.py
e. Evaluation & Output
- Batch testing (utility/batch_test.py) → computes recommendation metrics (HR@K, NDCG)
- Results logged / visualized

##### Relationships & Data Flows
- Raw data → LLM Augmentor scripts → augmented outputs
- Augmented + raw data → Data Storage → Recommender Training
- Recommender subcomponents communicate via function calls / data loaders
- Training → Evaluation → Logs / Metrics

##### Architectural Patterns & Technologies
- Pipeline pattern: clear two‐stage pipeline (augmentation → training)
- Modularization: augmentation scripts, utility modules, model definitions all decoupled
- External service integration: OpenAI API calls encapsulated in scripts
- Graph‐based learning pattern: treats recommendation as graph problem
- Multi‐modal encoding: CLIP & S‐BERT for node features

##### Essential Elements
- Component labels (script / module / service names)
- Clear grouping of Stage 1 vs. Stage 2

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Data Sources
    RawData["Raw Interaction Data (CSV)"]:::dataStore
    MultiModal["Original Item Attributes & Images"]:::dataStore
    README["Project README & Documentation"]:::external
    Images["Illustrative Diagrams"]:::external
    Req["Dependency Specifications (requirements.txt)"]:::external

    %% Stage 1: LLM Augmentation
    subgraph "Stage 1: LLM Augmentation"
        direction TB
        UIEdge["u–i Edge Augmentor\n(gpt_ui_aug.py)"]:::scriptRect
        ProfileAug["User Profiling Augmentor\n(gpt_user_profiling.py)"]:::scriptRect
        ItemAug["Item Attribute Augmentor\n(gpt_i_attribute_generate_aug.py)"]:::scriptRect
        OpenAI["OpenAI GPT-3.5 / embeddings API"]:::external
        AugStore["Augmented Dataset Store\n(data/{dataset}/)"]:::dataStore
    end

    %% Stage 2: Recommender Training
    subgraph "Stage 2: Recommender Training"
        direction TB
        Main["Main Orchestrator\n(main.py)"]:::scriptRect
        Parser["CLI Parser\n(parser.py)"]:::scriptRect
        LoadData["Data Loader\n(load_data.py)"]:::scriptRect
        Models["GNN / Recommendation Architectures\n(Models.py)"]:::scriptRect
        CLIP["CLIP-ViT Encoder"]:::external
        SBERT["Sentence-BERT Encoder"]:::external
        Norm["Data Normalization Helper\n(norm.py)"]:::scriptRect
        Logging["Logging Utility\n(logging.py)"]:::scriptRect
        Metrics["Metrics Computation\n(metrics.py)"]:::scriptRect
        BatchTest["Batch Testing / Evaluation\n(batch_test.py)"]:::scriptRect
        Results["Evaluation Results & Logs"]:::dataStore
    end

    %% Data Flows Stage 1
    RawData --> UIEdge
    RawData --> ProfileAug
    MultiModal --> ItemAug

    UIEdge -->|Call GPT-3.5-turbo API| OpenAI
    ProfileAug -->|Call GPT-3.5-turbo API| OpenAI
    ItemAug -->|Call GPT-3.5-turbo API| OpenAI

    UIEdge --> AugStore
    ProfileAug --> AugStore
    ItemAug --> AugStore

    %% Data Flows to Stage 2
    AugStore --> LoadData
    RawData --> LoadData
    MultiModal --> LoadData

    %% Orchestration & Modules
    LoadData --> Main
    Parser --> Main
    Main --> Models
    Main --> CLIP
    Main --> SBERT
    Main --> Norm
    Main --> Logging
    Main --> Metrics
    Main --> BatchTest
    BatchTest --> Results
    Metrics --> Results
    Logging --> Results

    %% Documentation & Dependencies
    README --- Main
    Images --- Main
    Req --- Main

    %% Click Events
    click UIEdge "https://github.com/mohamedaminebentayeb/llmrec/blob/main/LLM_augmentation_construct_prompt/gpt_ui_aug.py"
    click ProfileAug "https://github.com/mohamedaminebentayeb/llmrec/blob/main/LLM_augmentation_construct_prompt/gpt_user_profiling.py"
    click ItemAug "https://github.com/mohamedaminebentayeb/llmrec/blob/main/LLM_augmentation_construct_prompt/gpt_i_attribute_generate_aug.py"
    click Main "https://github.com/mohamedaminebentayeb/llmrec/blob/main/main.py"
    click Models "https://github.com/mohamedaminebentayeb/llmrec/blob/main/Models.py"
    click Parser "https://github.com/mohamedaminebentayeb/llmrec/blob/main/utility/parser.py"
    click LoadData "https://github.com/mohamedaminebentayeb/llmrec/blob/main/utility/load_data.py"
    click Logging "https://github.com/mohamedaminebentayeb/llmrec/blob/main/utility/logging.py"
    click Metrics "https://github.com/mohamedaminebentayeb/llmrec/blob/main/utility/metrics.py"
    click BatchTest "https://github.com/mohamedaminebentayeb/llmrec/blob/main/utility/batch_test.py"
    click Norm "https://github.com/mohamedaminebentayeb/llmrec/blob/main/utility/norm.py"
    click README "https://github.com/mohamedaminebentayeb/llmrec/blob/main/README.md"
    click Images "https://github.com/mohamedaminebentayeb/llmrec/tree/main/image/"
    click Req "https://github.com/mohamedaminebentayeb/llmrec/blob/main/requirements.txt"

    %% Styles
    classDef scriptRect fill:#B3CDE3,stroke:#333,stroke-width:1px;
    classDef dataStore fill:#CCEBC5,stroke:#333,stroke-width:1px;
    classDef external fill:#F2F2F2,stroke:#333,stroke-width:1px;
```
