# bsl-traveller/caligen architecture

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

- Interactive diagram: https://gitdiagram.com/bsl-traveller/caligen
- Repository: https://github.com/bsl-traveller/caligen

## Overview

##### Project type and purpose
- This is a research-style machine-learning pipeline (“CaliGen”) for classifier calibration in unseen contexts.
- It’s a command-line-driven, config-based experiment orchestration system with discrete stages (preprocess, train, calibrate, eval), plus Jupyter notebooks for visualization.

##### File structure
- Entry point: main.py
- Configuration: model/configs/*.py → dataset, model, loss definitions
- Preprocessing: preprocessing/preprocess.py, preprocessing/corruptions.py, data_utils.py
- Model training & evaluation: model/dnn_models.py, model/steps.py, model/model_utils.py
- Calibration logic: calibration/calibrate.py, calibration/cal_methods.py
- Results & artifacts:
- DataSets folder (external raw datasets)
- logs/<workdir> (experiment outputs, checkpoints, calibrated models)
- results/ (aggregated CSVs for different architectures/datasets/losses)
- Visualization: Notebooks/
- Environment setup: environment.yml, requirements.txt

##### README for additional insights
- CLI modes: preprocess, train, calibrate, eval_performance
- External dataset downloads (CIFAR-10C, Office-Home, DomainNet)
- Outputs go into workdir, then notebooks read logs to produce figures

##### Main components & their interactions
a. Components:
- CLI Orchestrator (main.py)
- Config Loader (reads model/configs)
- Data Preprocessing Module
- Training Module
- Calibration Module
- Evaluation Module
- Artifact Storage (workdir: raw/preprocessed data, model checkpoints, calibrated weights)
- Metrics & Results Store (results/ folder with CSVs)
- Visualization Layer (Notebooks/)
- External Data Sources (downloaded datasets)
b. Relationships & Data Flow:
1. User invokes CLI → main.py
2. Config Loader parses flags & .py configs → passes parameters to modules
3. Preprocessing Module reads raw DataSets → writes preprocessed data to workdir
4. Training Module consumes preprocessed data → outputs model checkpoints to workdir
5. Calibration Module consumes checkpoints → outputs calibrated weights under workdir/calib_models
6. Evaluation Module uses calibrated weights → writes metrics CSVs under results/
7. Notebooks read metrics & figures from workdir/results for visualization
8. All modules log to file system; no direct network calls except initial dataset download
c. Architectural patterns & design principles:
- Modular pipeline – each stage is a separate component, invoked by a single orchestrator
- Config-driven – experiment behavior is determined by Python config files
- Separation of concerns – preprocessing, training, calibration, evaluation, and visualization are distinct
- Reproducibility – environment.yml and workdir snapshot per run
d. Key technologies & libraries:
- PyTorch or TensorFlow (implied by DNN modules)
- Hydra-style or argparse config loading
- pandas/numpy for CSV results
- Jupyter for notebooks
- CLI entry via python -m main

##### Detail
- Every major directory as a component if seen in the file tree
- How model/configs feeds into each stage
- Which scripts or packages live in each component

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% External Data Source
    ExternalData["External Data Sources"]:::external
    RawData["Raw Data"]:::storage
    ExternalData --> RawData

    %% CLI and Config
    CLI["CLI Orchestrator"]:::compute
    ConfigLoader["Config Loader"]:::config
    CLI --> ConfigLoader

    %% Pipeline Stages
    subgraph "Preprocessing Module"
        Preprocess["Preprocessing Script"]:::compute
        Corruptions["Corruptions Script"]:::compute
        DataUtils["Data Utils"]:::compute
    end
    ConfigLoader --> Preprocess
    ConfigLoader --> Corruptions
    ConfigLoader --> DataUtils
    RawData --> Preprocess
    Preprocess --> PreprocessedData["Preprocessed Data"]:::storage
    Corruptions --> PreprocessedData
    DataUtils --> PreprocessedData

    subgraph "Training Module"
        TrainSteps["Training Steps"]:::compute
        DNNModels["DNN Models"]:::compute
        ModelUtils["Model Utils"]:::compute
    end
    ConfigLoader --> TrainSteps
    TrainSteps --> DNNModels
    TrainSteps --> ModelUtils
    PreprocessedData --> TrainSteps
    TrainSteps --> Checkpoints["Model Checkpoints"]:::storage

    subgraph "Calibration Module"
        CalibrateScript["Calibration Script"]:::compute
        CalMethods["Calibration Methods"]:::compute
    end
    ConfigLoader --> CalibrateScript
    CalibrateScript --> CalMethods
    Checkpoints --> CalibrateScript
    CalMethods --> CalibModels["Calibrated Models"]:::storage

    subgraph "Evaluation Module"
        EvalSteps["Evaluation Steps"]:::compute
    end
    ConfigLoader --> EvalSteps
    CalibModels --> EvalSteps
    EvalSteps --> ResultsCSVs["Results CSVs"]:::storage

    %% Visualization
    Notebooks["Jupyter Notebooks"]:::viz
    ResultsCSVs --> Notebooks

    %% Environment Setup
    EnvSetup["Environment Setup"]:::config
    CLI --> EnvSetup

    %% Click Events
    click CLI "https://github.com/bsl-traveller/caligen/blob/main/main.py"
    click ConfigLoader "https://github.com/bsl-traveller/caligen/tree/main/model/configs/"
    click Preprocess "https://github.com/bsl-traveller/caligen/blob/main/preprocessing/preprocess.py"
    click Corruptions "https://github.com/bsl-traveller/caligen/blob/main/preprocessing/corruptions.py"
    click DataUtils "https://github.com/bsl-traveller/caligen/blob/main/data_utils.py"
    click TrainSteps "https://github.com/bsl-traveller/caligen/blob/main/model/steps.py"
    click DNNModels "https://github.com/bsl-traveller/caligen/blob/main/model/dnn_models.py"
    click ModelUtils "https://github.com/bsl-traveller/caligen/blob/main/model/model_utils.py"
    click CalibrateScript "https://github.com/bsl-traveller/caligen/blob/main/calibration/calibrate.py"
    click CalMethods "https://github.com/bsl-traveller/caligen/blob/main/calibration/cal_methods.py"
    click EvalSteps "https://github.com/bsl-traveller/caligen/blob/main/model/steps.py"
    click ResultsCSVs "https://github.com/bsl-traveller/caligen/tree/main/results/"
    click Notebooks "https://github.com/bsl-traveller/caligen/tree/main/Notebooks/"
    click EnvSetup "https://github.com/bsl-traveller/caligen/blob/main/environment.yml"
    click EnvSetup "https://github.com/bsl-traveller/caligen/blob/main/requirements.txt"

    %% Styles
    classDef compute fill:#8ab6d6,stroke:#1f4e79,color:#000;
    classDef storage fill:#a8d5a2,stroke:#31662b,color:#000;
    classDef config fill:#f5b971,stroke:#b86e00,color:#000;
    classDef viz fill:#c89ecf,stroke:#6b3c82,color:#000;
    classDef external fill:#d3d3d3,stroke:#777,color:#000;
```
