# yixinl7/brio architecture

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

- Interactive diagram: https://gitdiagram.com/yixinl7/brio
- Repository: https://github.com/yixinl7/brio

## Overview

##### Project Type and Purpose
- Recognize that this is a machine learning research project with a strong focus on natural language processing, specifically on abstractive summarization.
- That the system goes beyond standard maximum likelihood training by incorporating contrastive learning to refine candidate ranking and improve the generation quality.
- Keep in mind that the project also supports integration with Huggingface Transformers for model initialization and generation.

##### Main Components
- Data Preprocessing Module:
- Files: preprocess.py, data_utils.py, and utility functions in utils.py.
- Role: Tokenizes raw input data (using Stanford CoreNLP for PTB tokenization), organizes raw data, and processes candidate summaries (see gen_candidate.py for candidate generation).
- Model Module:
- Files: model.py, modeling_bart.py, and modeling_pegasus.py.
- Role: Contains the implementations of the summarization models, extending the Huggingface Transformers’ BART and Pegasus classes to fit the BRIO training efficiencies and contrastive learning framework.
- Training and Evaluation Module:
- Files: main.py, config.py, and label_smoothing_loss.py.
- Role: Orchestrates the training, hyper-parameter setup, evaluation, and checkpoint saving/loading. It ties together the preprocessing, model creation, candidate generation, and evaluation strategies.
- Evaluation Module:
- File: cal_rouge.py.
- Role: Calculates ROUGE metrics by either invoking a Perl script (external dependency) or using a pure Python-based implementation via the compare-mt package.
- Examples and Integration:
- Directory: examples (with example scripts such as hf.py and sample raw data).
- Role: Demonstrates how to integrate the BRIO models with external frameworks (like Huggingface) and shows example usages.

##### Relationships and Interactions
- From raw data to preprocessing.
- From preprocessing to candidate generation.
- From candidate generation to training (where the model receives both processed data and candidate summaries).
- From training to evaluation, and then to output storage.
- Interactions with external libraries such as the tokenization service and Huggingface modules.

##### Architectural Patterns and Technologies
- That the project uses a modular design where each stage (preprocessing, training, evaluation) is handled by distinct scripts/modules—a pattern common in machine learning pipelines.
- Use of a configuration module (config.py) responsible for hyperparameter settings and experiment control.
- Recognize the reliance on external libraries (e.g., Huggingface Transformers, compare-mt, Stanford CoreNLP) that provide critical functionality.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Raw Data & External Dependencies
    Datasets["Datasets (CNN/DailyMail, XSum, NYT)"]:::datamod
    CoreNLP["Stanford CoreNLP (Tokenization)"]:::datamod

    %% Data Preprocessing Pipeline
    subgraph "Data Preprocessing Pipeline"
        Preprocess["Preprocessing (preprocess.py)"]:::datamod
        DataUtils["Data Utils (data_utils.py)"]:::datamod
        Utils["Utility Functions (utils.py)"]:::datamod
        Candidate["Candidate Generation (gen_candidate.py)"]:::datamod
    end

    %% Training & Evaluation Engine
    subgraph "Training/Evaluation Engine"
        Main["Training Engine (main.py & config.py)"]:::model
        Model["Model Module (model.py)"]:::model
        Bart["BART Model (modeling_bart.py)"]:::model
        Pegasus["Pegasus Model (modeling_pegasus.py)"]:::model
        Loss["Loss & Optimization (label_smoothing_loss.py)"]:::model
        Rouge["Evaluation (cal_rouge.py)"]:::eval
    end

    %% External Services/Integration
    subgraph "External Services/Integration"
        HF["Huggingface Transformers"]:::external
        Compare["compare-mt"]:::external
        Examples["Examples & Integration (examples)"]:::external
    end

    %% Output and Checkpoint Storage
    Output["Output Storage (output directory)"]:::output

    %% Connections from Raw Data to Preprocessing
    Datasets -->|"feeds"| Preprocess
    CoreNLP -->|"supports"| Preprocess

    %% Internal Preprocessing Pipeline Flow
    Preprocess -->|"processes data"| DataUtils
    Preprocess -->|"processes data"| Utils
    DataUtils --> Candidate
    Utils --> Candidate

    %% From Preprocessing to Training Engine
    Candidate -->|"provides candidates"| Main

    %% Training Engine Internal Flow
    Main -->|"triggers model"| Model
    Main -->|"applies loss"| Loss
    Main -->|"evaluates"| Rouge

    %% Model Module Composition
    Model -->|"implements"| Bart
    Model -->|"implements"| Pegasus

    %% External Services Integration
    HF -->|"initializes"| Model
    Compare -->|"assists"| Rouge
    Examples -->|"demonstrates integration"| HF

    %% Output Flow
    Main -->|"saves checkpoints"| Output
    Rouge -->|"writes results"| Output

    %% Styling Classes
    classDef datamod fill:#D0E6F7,stroke:#1B82D2,stroke-width:2px;
    classDef model fill:#C1E1C1,stroke:#197D46,stroke-width:2px;
    classDef eval fill:#FEF3C7,stroke:#D69C25,stroke-width:2px;
    classDef external fill:#F7CDD2,stroke:#C0392B,stroke-width:2px;
    classDef output fill:#E8DAEF,stroke:#6C3483,stroke-width:2px;

    %% Click Events
    click Preprocess "https://github.com/yixinl7/brio/blob/main/preprocess.py"
    click DataUtils "https://github.com/yixinl7/brio/blob/main/data_utils.py"
    click Utils "https://github.com/yixinl7/brio/blob/main/utils.py"
    click Candidate "https://github.com/yixinl7/brio/blob/main/gen_candidate.py"
    click Model "https://github.com/yixinl7/brio/blob/main/model.py"
    click Bart "https://github.com/yixinl7/brio/blob/main/modeling_bart.py"
    click Pegasus "https://github.com/yixinl7/brio/blob/main/modeling_pegasus.py"
    click Main "https://github.com/yixinl7/brio/blob/main/main.py"
    click Loss "https://github.com/yixinl7/brio/blob/main/label_smoothing_loss.py"
    click Rouge "https://github.com/yixinl7/brio/blob/main/cal_rouge.py"
    click Examples "https://github.com/yixinl7/brio/tree/main/examples"
    click HF "https://github.com/yixinl7/brio/blob/main/examples/hf.py"
    click Output "https://github.com/yixinl7/brio/tree/main/output"
```
