# phanhoang1803/mrc-retroreader architecture

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

- Interactive diagram: https://gitdiagram.com/phanhoang1803/mrc-retroreader
- Repository: https://github.com/phanhoang1803/mrc-retroreader

## Overview

##### Project Type and Purpose
- The project is a Machine Reading Comprehension (MRC) system aimed at answering questions based on a provided passage of text. It leverages state-of-the-art Transformer-based models (e.g., RoBERTa, Electra, DistilBERT) to perform both answerability detection and answer generation.
- It is built to support training, evaluation, and a live demo (via a local app and Gradio) of the MRC system. The project supports multiple configurations for model training and inference (as seen in the configs directory) and provides notebooks for exploratory data analysis.

##### File Structure
- Top-level files and directories:
- app1.py: Likely serves as the entry point for running the demo locally.
- train_squad_v2.py: The training script for SQuAD v2 dataset.
- evaluation_scriptv2.0.py: Script dedicated to evaluating the model performance.
- configs/: Contains various YAML configuration files for training and inference for different backbone models.
- outputs/: Stores predictions and evaluation results (organized outputs from runs).
- retro_reader/: Acts as the core module/library that includes:
» Argument parsing utilities (under args/).
» Model definitions for different architectures (in models/), including custom modeling files for RoBERTa, Electra, DistilBert, etc.
» Base functionality, metrics, and preprocessing scripts.
- Jupyter notebooks (squad_eda.ipynb and squad_training.ipynb) provide additional insights and interactive EDA for the dataset.
- The file structure indicates a clear separation between configuration, core module code (logic and models), experiment scripts (training and evaluation), and a demo/front-end component.

##### README for Additional Insights
- The README clearly explains the MRC challenge, highlights the ability to detect unanswerable questions, and includes directions for training, evaluation, and running the demo.
- It provides dependency information (Python, PyTorch, Transformers), usage examples, and links to a live demo on Hugging Face.
- These details verify that the system consists of several interacting components: configuration management (YAML files), core processing via the retro_reader package, training and evaluation scripts, and a front-end demo.

- Main Components:
- Demo/Frontend Component: Represented by app1.py (and the Gradio deployment option).
- Training Module: train_squad_v2.py and associated Jupyter notebooks (squad_training.ipynb).
- Evaluation Module: evaluation_scriptv2.0.py along with the outputs directory.
- Core Processing Library: The retro_reader module which contains submodules for argument parsing, preprocessing, metrics, and model definitions.
- Configuration Layer: YAML configuration files in the configs directory which interface with both training and inference processes.
- External Dependencies: PyTorch, Transformers library, and possibly Gradio for deployment.

- Relationships and Interactions:
- The training pipeline reads configurations, loads data (as indicated by SQuAD dataset usage), and outputs models and logs.
- The evaluation pipeline consumes model outputs (from the outputs directory) and compares them against ground truth using the metrics defined in retro_reader.
- The demo component (app1.py) interfaces with the trained model to provide interactive responses.

- Architectural Patterns or Design Principles:
- Separation of concerns: distinct modules for configuration (configs), core functionalities (retro_reader), training (train_squad_v2.py) and evaluation (evaluation_scriptv2.0.py).
- Modularity: The retro_reader package encapsulates crucial components (argument handling, model definitions, preprocessing) which allows for easier substitution or extension of transformer models.
- Reusability: Config files and notebooks demonstrate the project's adaptability to different experimental conditions.

- Technologies and Frameworks:
- Python 3.x for programming.
- PyTorch as the deep learning framework.
- Hugging Face Transformers library for pre-trained models.
- Gradio (when deploying the demo).

##### Specific Elements
- Nodes/Components with clear labels:
- “User Interface (Demo App)” for app1.py (and Gradio endpoint).
- “Training Engine” for train_squad_v2.py.
- “Evaluation Engine” for evaluation_scriptv2.0.py.
- “Configuration Layer (YAML Files)” representing the configs directory.
- “Core Processor (RetroReader)” that subdivides further into submodules like argument parsing, models, preprocessing, and metrics.
- “Output Storage” to denote the outputs folder containing prediction files and evaluation results.
- UI → Core Processor → (Training/Evaluation pipelines)
- Configurations feeding into both Training and Inference paths.
- Rectangles for core modules and scripts.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Configuration Layer
    subgraph "Configuration Layer (YAML Files)"
        Config["Configuration Layer (YAML Files)"]
    end

    %% Training Module
    subgraph "Training Module"
        TrainScript["train_squad_v2.py"]
        TrainNotebook["squad_training.ipynb"]
    end

    %% Evaluation Module
    subgraph "Evaluation Module"
        EvalScript["evaluation_scriptv2.0.py"]
        OutputStorage["Output Storage"]
    end

    %% Demo Component
    UI["User Interface (Demo App)"]

    %% Core Processor (RetroReader) with submodules
    subgraph "Core Processor (RetroReader)"
        CoreTitle["Core Processor (RetroReader)"]
        Arg["Argument Parsing"]
        Models["Model Definitions"]
        Preproc["Preprocessing"]
        Metrics["Metrics & Base"]
    end

    %% Exploratory Data Analysis Notebook
    EDA["EDA Notebook"]

    %% External Dependencies
    PyTorch["PyTorch"]
    Transformers["Transformers"]
    Gradio["Gradio"]
    HugFace["Hugging Face Model Hub"]

    %% Connections between components
    Config -->|"configures"| TrainScript
    Config -->|"configures"| TrainNotebook
    Config -->|"configures"| EvalScript

    TrainScript -->|"triggers"| CoreTitle
    TrainNotebook -->|"triggers"| CoreTitle
    EvalScript -->|"calls"| CoreTitle
    UI -->|"queries"| CoreTitle

    CoreTitle -->|"generates"| OutputStorage
    EDA -->|"analyzes"| OutputStorage

    %% External dependencies connections
    PyTorch -->|"supports"| CoreTitle
    Transformers -->|"supports"| CoreTitle
    Gradio -->|"powers"| UI
    HugFace -->|"provides"| CoreTitle

    %% Internal distribution within Core Processor
    CoreTitle --> Arg
    CoreTitle --> Models
    CoreTitle --> Preproc
    CoreTitle --> Metrics

    %% Click Events
    click UI "https://github.com/phanhoang1803/mrc-retroreader/blob/main/app1.py"
    click TrainScript "https://github.com/phanhoang1803/mrc-retroreader/blob/main/train_squad_v2.py"
    click TrainNotebook "https://github.com/phanhoang1803/mrc-retroreader/blob/main/squad_training.ipynb"
    click EvalScript "https://github.com/phanhoang1803/mrc-retroreader/blob/main/evaluation_scriptv2.0.py"
    click OutputStorage "https://github.com/phanhoang1803/mrc-retroreader/tree/main/outputs/"
    click Config "https://github.com/phanhoang1803/mrc-retroreader/tree/main/configs/"
    click CoreTitle "https://github.com/phanhoang1803/mrc-retroreader/tree/main/retro_reader/"
    click Arg "https://github.com/phanhoang1803/mrc-retroreader/tree/main/retro_reader/args/"
    click Models "https://github.com/phanhoang1803/mrc-retroreader/tree/main/retro_reader/models/"
    click Preproc "https://github.com/phanhoang1803/mrc-retroreader/blob/main/retro_reader/preprocess.py"
    click Metrics "https://github.com/phanhoang1803/mrc-retroreader/blob/main/retro_reader/metrics.py"
    click EDA "https://github.com/phanhoang1803/mrc-retroreader/blob/main/squad_eda.ipynb"

    %% Styles
    classDef config fill:#A3E4D7,stroke:#000,stroke-width:2px;
    classDef module fill:#AED6F1,stroke:#000,stroke-width:2px;
    classDef processor fill:#D6EAF8,stroke:#000,stroke-width:2px;
    classDef demo fill:#F5B7B1,stroke:#000,stroke-width:2px;
    classDef notebook fill:#F9E79F,stroke:#000,stroke-width:2px;
    classDef external fill:#D7BDE2,stroke:#000,stroke-width:2px;

    class Config config;
    class TrainScript,TrainNotebook,EvalScript,OutputStorage module;
    class CoreTitle,Arg,Models,Preproc,Metrics processor;
    class UI demo;
    class EDA notebook;
    class PyTorch,Transformers,Gradio,HugFace external;
```
