# ljy0ustc/llara architecture

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

- Interactive diagram: https://gitdiagram.com/ljy0ustc/llara
- Repository: https://github.com/ljy0ustc/llara

## Overview

##### Main Components
a. External Systems & Artifacts
– Raw Datasets (MovieLens, Steam, LastFM)
– Pre-trained LLaMA2-7B model (from Hugging Face)
b. Data Layer
– data_interface.py (abstract loader interface)
– [lastfm_data.py, movielens_data.py, steam_data.py] (dataset-specific loaders)
c. Prompt Layer
– prompt/*.txt (template prompts for artist, movie, game recommendations)
d. Model Layer
– SASRecModules_ori.py (core sequential modeling blocks)
– model_interface.py (defines train/eval API for rec model)
– mlp_projector.py (final rating/ranking head)
– optims.py (optimizer and scheduler definitions)
e. Orchestration & Execution
– main.py (entry point for training and evaluation pipelines)
– recommender/A_SASRec_final_bce_llm.py (integration of SASRec + LLaRA prompts + LLaMA calls)
– Shell scripts (train_*.sh, test_*.sh) to launch experiments per dataset
f. Artifacts
– rec_model/*.pt (trained checkpoint files)
– logs, metrics outputs

##### Relationships & Data Flows
– Raw Datasets → Data Layer: data loaders read raw files, preprocess into sequences.
– Data Layer → Model Layer: batched sequences fed into SASRecModules (embedding → self-attention → MLP projector).
– Model Layer ↔ LLM Layer: recommender script uses model outputs to construct prompt, sends to LLaMA2-7B, receives ranking logits or next-item suggestions.
– Model + LLM outputs → Loss Computation (within optims) → Backprop → Parameter Updates.
– Trained Model → rec_model checkpoint.
– Evaluation Pipeline: same flows but in inference mode, metrics computed (ValidRatio, HitRatio@1).

##### Architectural Patterns & Design Principles
– Modular layering: separate data, model, prompt, orchestration.
– Interface abstraction: data_interface.py and model_interface.py enable plugging in new datasets or model variants.
– Shell-based experiment orchestration for reproducibility.
– Reuse of pre-trained LLM as a service via prompt files.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% External Systems
    subgraph "External Systems"
        direction TB
        RawDatasets(["Raw Datasets\n(MovieLens, Steam, LastFM)"]):::service
        LLMService(["LLaMA2-7B Service"]):::service
    end

    %% Data Layer
    subgraph "Data Layer"
        direction TB
        DataInterface["data_interface.py"]:::data
        LastFMData["lastfm_data.py"]:::data
        MovieLensData["movielens_data.py"]:::data
        SteamData["steam_data.py"]:::data
    end

    %% Model Layer
    subgraph "Model Layer"
        direction TB
        SASRec["SASRecModules_ori.py"]:::model
        ModelAPI["model_interface.py"]:::model
        MLPProjector["mlp_projector.py"]:::model
        Optims["optims.py"]:::model
    end

    %% Prompt/LLM Layer
    subgraph "Prompt/LLM Layer"
        direction TB
        PromptArtist["artist.txt"]:::data
        PromptMovie["movie.txt"]:::data
        PromptGame["game.txt"]:::data
    end

    %% Orchestration
    subgraph "Orchestration & Execution"
        direction TB
        TrainShells(["train_*.sh"]):::orches
        TestShells(["test_*.sh"]):::orches
        MainPy["main.py"]:::orches
        Recommender["A_SASRec_final_bce_llm.py"]:::orches
    end

    %% Artifacts
    subgraph "Artifacts"
        direction TB
        Checkpoints(["rec_model/*.pt"]):::artifact
        LogsMetrics(["logs & metrics"]):::artifact
    end

    %% Data Flow
    RawDatasets -->|ingest raw files| LastFMData
    RawDatasets -->|ingest raw files| MovieLensData
    RawDatasets -->|ingest raw files| SteamData

    LastFMData -->|implements| DataInterface
    MovieLensData -->|implements| DataInterface
    SteamData -->|implements| DataInterface

    DataInterface -->|token sequences| SASRec
    SASRec -->|sequence embeddings| MLPProjector
    MLPProjector -->|rank logits| Recommender

    %% Prompt/LLM Flow
    Recommender -->|reads| PromptArtist
    Recommender -->|reads| PromptMovie
    Recommender -->|reads| PromptGame

    Recommender -->|"prompt text"| LLMService
    LLMService -->|"item suggestions"| Recommender

    Recommender -->|"logits"| Optims
    Optims -->|"updates"| SASRec

    %% Orchestration Control
    TrainShells -.->|executes| MainPy
    TestShells -.->|executes| MainPy
    MainPy -->|calls| DataInterface
    MainPy -->|calls| SASRec
    MainPy -->|calls| Optims
    MainPy -->|invokes| Recommender

    MainPy -->|"checkpoint"| Checkpoints
    MainPy -->|"metrics"| LogsMetrics

    %% Click Events
    click DataInterface "https://github.com/ljy0ustc/llara/blob/main/data/data_interface.py"
    click LastFMData "https://github.com/ljy0ustc/llara/blob/main/data/lastfm_data.py"
    click MovieLensData "https://github.com/ljy0ustc/llara/blob/main/data/movielens_data.py"
    click SteamData "https://github.com/ljy0ustc/llara/blob/main/data/steam_data.py"
    click PromptArtist "https://github.com/ljy0ustc/llara/blob/main/prompt/artist.txt"
    click PromptMovie "https://github.com/ljy0ustc/llara/blob/main/prompt/movie.txt"
    click PromptGame "https://github.com/ljy0ustc/llara/blob/main/prompt/game.txt"
    click SASRec "https://github.com/ljy0ustc/llara/blob/main/SASRecModules_ori.py"
    click ModelAPI "https://github.com/ljy0ustc/llara/blob/main/model/model_interface.py"
    click MLPProjector "https://github.com/ljy0ustc/llara/blob/main/model/mlp_projector.py"
    click Optims "https://github.com/ljy0ustc/llara/blob/main/optims.py"
    click MainPy "https://github.com/ljy0ustc/llara/blob/main/main.py"
    click Recommender "https://github.com/ljy0ustc/llara/blob/main/recommender/A_SASRec_final_bce_llm.py"

    %% Styles
    classDef data fill:#D6EAF8,stroke:#3498DB,color:#1B4F72;
    classDef model fill:#D5F5E3,stroke:#28B463,color:#145A32;
    classDef service fill:#FDEBD0,stroke:#E67E22,color:#7E5109;
    classDef orches fill:#E5E7E9,stroke:#95A5A6,color:#566573;
    classDef artifact fill:#FADBD8,stroke:#C0392B,color:#641E16;
```
