# princeton-nlp/less architecture

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

- Interactive diagram: https://gitdiagram.com/princeton-nlp/less
- Repository: https://github.com/princeton-nlp/less

## Overview

##### Main Components
- Data Input & Preparation:
– Represent raw and processed datasets (e.g., training datasets like Flan v2, Dolly, COT, Open Assistant; evaluation datasets such as MMLU, TydiQA, BBH).
- Warmup Training Module:
– Use the scripts under less/scripts/train (specifically, warmup_lora_train.sh) in conjunction with the “run” directory examples. This stage initializes a LoRA-based training process on a small percentage (e.g., 5%) of the data.
- Gradient Datastore Builder:
– Highlight the gradient computation stage. Modules in the less/data_selection and less/scripts/get_info directories as well as scripts in “run/first_order_checking” form this component.
– This part builds the “gradient datastore” by collecting, storing, and processing gradients from the warmup model at selected checkpoints.
- Data Selection Module:
– Illustrated by components in less/data_selection and the matching scripts (e.g., matching.sh & write_selected_data). This module computes influence scores from gradients and selects the top-k influential training points.
- Final Training Module:
- Evaluation Module:
– Reflect the evaluation scripts found in the evaluation directory (which includes multiple subcomponents like alpaca_farm, bbh, codex_humaneval, gsm, toxicgen, truthfulqa, tydiqa).
– Emphasize that different evaluation scripts target different standardized evaluation datasets.

##### Relationships and Data Flow
- The output from the Warmup Training then becomes the source for the Gradient Datastore Builder, which calculates gradients across various checkpoints.
- The gradients are subsequently fed into the Data Selection Module that computes the influence scores (note the directional flow: gradients → influence score computation → selection outcomes).
- The selected top-k influential training samples then form the input for the Final Training Module that uses LoRA fine-tuning (or even full-parameter finetuning).
- Simultaneously, evaluation workflows tap outputs from both the warmup and fine-tuned models to assess performance across multiple tasks.
- Optionally, include a feedback loop from evaluation indicating further data selection adjustments or retraining loops for iterative refinement.

##### Architectural Patterns & Design Principles
- Modular Design: The project is organized into logically separated modules (data preparation, training, gradient extraction, selection, evaluation).
- Pipeline Architecture: Emphasize a sequential data flow where each stage produces outputs that are mandatory inputs for subsequent stages.
- Experimentation Focus: Many components (e.g., various evaluation scripts) reflect a research experiment design where modularity and reproducibility are key.
- Integration with External Tools: The dependency on PyTorch and shell scripts shows supported integration between Python modules and command-line utilities.

– Data Inputs: External datasets, training & validation files.
– Training Modules: “Warmup Training” (LoRA training), “Final Training”
– Gradient Collection: “Gradient Datastore Builder” utilizing scripts (e.g., get_train_lora_grads.sh, get_eval_lora_grads.sh)
– Data Matching & Selection: depicted with scripts like matching.sh and write_selected_data.py.
- Optionally, annotate any external tooling requirements (e.g., PyTorch version, installation steps from requirement.txt).

##### Final Recommendations for the Engineer
- Module is clearly annotated with its corresponding folder or script reference as indicated by the file tree.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Data Preparation Layer
    subgraph "Data Preparation"
        A1["Training Dataset"]:::data
        A2["Validation Dataset"]:::data
        A3["Test Dataset"]:::data
    end

    %% Warmup Training Module
    subgraph "Warmup Training"
        B["Warmup Training (LoRA)"]:::train
    end

    %% Gradient Datastore Builder
    subgraph "Gradient Datastore Builder"
        C1["Grad: get_train"]:::grad
        C2["Grad: calculate_train"]:::grad
        C3["Grad: get_eval"]:::grad
        C4["Grad: calculate_eval"]:::grad
        C5["Gradient Datastore"]:::grad
    end

    %% Data Selection Module
    subgraph "Data Selection Module"
        D1["Matching (Python)"]:::select
        D2["Write Selected Data"]:::select
        D3["Matching (Shell)"]:::select
        D4["Selected Data"]:::select
    end

    %% Final Training Module
    subgraph "Final Training Module"
        E["Final Training (LoRA)"]:::train
    end

    %% Evaluation Module
    subgraph "Evaluation Module"
        F9["Evaluation Summary"]:::eval
        F1["Alpaca Farm"]:::eval
        F2["BBH"]:::eval
        F3["Codex Humaneval"]:::eval
        F4["GSM"]:::eval
        F5["MMLU"]:::eval
        F6["Toxigen"]:::eval
        F7["TruthfulQA"]:::eval
        F8["TydiQA"]:::eval
    end

    %% Data Flow Connections
    A1 & A2 & A3 -->|"preparedData"| B
    B -->|"initModel"| C1
    B --> C2
    B --> C3
    B --> C4
    C1 --> C5
    C2 --> C5
    C3 --> C5
    C4 --> C5
    C5 -->|"gradients"| D1
    C5 --> D2
    C5 --> D3
    D1 --> D4
    D2 --> D4
    D3 --> D4
    D4 -->|"selectedData"| E
    E -->|"fineTunedModel"| F9
    B --> F9
    F9 --> F1
    F9 --> F2
    F9 --> F3
    F9 --> F4
    F9 --> F5
    F9 --> F6
    F9 --> F7
    F9 --> F8
    F9 -->|"feedback"| D1

    %% Click Events for Data Preparation
    click A1 "https://github.com/princeton-nlp/less/blob/main/less/data_selection/get_training_dataset.py"
    click A2 "https://github.com/princeton-nlp/less/blob/main/less/data_selection/get_validation_dataset.py"
    click A3 "https://github.com/princeton-nlp/less/blob/main/less/data_selection/get_test_dataset.py"

    %% Click Event for Warmup Training
    click B "https://github.com/princeton-nlp/less/blob/main/less/scripts/train/warmup_lora_train.sh"

    %% Click Events for Gradient Datastore Builder
    click C1 "https://github.com/princeton-nlp/less/blob/main/less/scripts/get_info/grad/get_train_lora_grads.sh"
    click C2 "https://github.com/princeton-nlp/less/blob/main/run/first_order_checking/calculate_train_grad.sh"
    click C3 "https://github.com/princeton-nlp/less/blob/main/less/scripts/get_info/grad/get_eval_lora_grads.sh"
    click C4 "https://github.com/princeton-nlp/less/blob/main/run/first_order_checking/calculate_eval_grad.sh"

    %% Click Events for Data Selection Module
    click D1 "https://github.com/princeton-nlp/less/blob/main/less/data_selection/matching.py"
    click D2 "https://github.com/princeton-nlp/less/blob/main/less/data_selection/write_selected_data.py"
    click D3 "https://github.com/princeton-nlp/less/blob/main/less/scripts/data_selection/matching.sh"

    %% Click Event for Final Training Module
    click E "https://github.com/princeton-nlp/less/blob/main/less/scripts/train/lora_train.sh"

    %% Click Events for Evaluation Module
    click F1 "https://github.com/princeton-nlp/less/tree/main/evaluation/eval/alpaca_farm"
    click F2 "https://github.com/princeton-nlp/less/tree/main/evaluation/eval/bbh"
    click F3 "https://github.com/princeton-nlp/less/tree/main/evaluation/eval/codex_humaneval"
    click F4 "https://github.com/princeton-nlp/less/tree/main/evaluation/eval/gsm"
    click F5 "https://github.com/princeton-nlp/less/tree/main/evaluation/eval/mmlu"
    click F6 "https://github.com/princeton-nlp/less/tree/main/evaluation/eval/toxigen"
    click F7 "https://github.com/princeton-nlp/less/tree/main/evaluation/eval/truthfulqa"
    click F8 "https://github.com/princeton-nlp/less/tree/main/evaluation/eval/tydiqa"
    click F9 "https://github.com/princeton-nlp/less/tree/main/evaluation"

    %% Styles
    classDef data fill:#A8E6CF,stroke:#333,stroke-width:2px;
    classDef train fill:#FFD700,stroke:#333,stroke-width:2px;
    classDef grad fill:#90EE90,stroke:#333,stroke-width:2px;
    classDef select fill:#87CEFA,stroke:#333,stroke-width:2px;
    classDef eval fill:#FFB6C1,stroke:#333,stroke-width:2px;
```
