# chanyoung-ken/ai_proj architecture

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

- Interactive diagram: https://gitdiagram.com/chanyoung-ken/ai_proj
- Repository: https://github.com/chanyoung-ken/ai_proj

## Overview

##### Project Type and Purpose
- This is an ML research/pipeline project focused on training and evaluating robust image-classification models (ResNet variants) on CIFAR-10 and CIFAR-100. It includes modules for data generation, model training (including adversarially trained variants), hyperparameter tuning, ensemble construction, robustness evaluation, and visualization (Grad-CAM, plotting).

##### File-Structure Analysis
- Top-level scripts and orchestration:
- run_pipeline.sh, run_at_alp.sh, run_ensemble.sh, run_epsilon_sweep.sh – bash drivers that chain together data preparation, training, ensembling, and evaluation.
- benchmark.py, hyperparameter_tuning.py, evaluate_models.py, multi_ensem_logs/… – standalone Python scripts for specific tasks.
- Key directories:
- data_generator/ – contains data_generator.py (creates synthetic/adversarial data), train_resnet.py (model training loop), pipeline.ipynb for exploration, checkpoints and models subfolders.
- ensemble_models/ – stores final ensemble weights.
- robustness_results/, ensemble_robustness_results/ – CSVs and model files capturing evaluation metrics under different attacks.
- gradcam_visualizations/, graphs/ – visual output of model explanations and performance plots.
- Logging and artifacts:
- logs/, multi_ensem_logs/, nohup.out, sweep_output.log – track runtime logs by component.

##### README Insights
- Minimal README; primary clues come from file names and directory layout. The goal is end-to-end robustness research: data → single-model training → ensemble assembly → evaluation → visualization.

a. Main Components
1. Data Ingestion & Preprocessing (data_generator/data_generator.py)
2. Model Training Service
– Standard training (train_resnet.py)
– Adversarial training (attentionlpt.py, ensemble_multi_attak.py)
– Hyperparameter tuner (hyperparameter_tuning.py)
3. Ensemble Orchestrator (realensemble.py, ensemble_models/)
4. Evaluation & Robustness Analysis (evaluate_models.py, robustness_results/, ensemble_robustness_results/)
5. Visualization & Reporting (gradcam.py → gradcam_visualizations/, plotting.py → graphs/)
6. Orchestration Scripts (run_*.sh)
7. Artifact Storage (checkpoints/, models/, logs/, CSV result folders)
b. Relationships & Data Flows
– Raw CIFAR data → Data Ingestion → Preprocessed data/augmented adversarial examples
– Preprocessed data → Model Training → Checkpointed weights
– Checkpoints → Ensemble Orchestrator → ensemble_models/*.pth
– Single and ensemble models → Evaluation module → robustness_results/*.csv
– Raw evaluation results → Plotting/Grad-CAM modules → graphs/ and gradcam_visualizations/
– Orchestration scripts tie above modules in pipelines and log to logs/ and multi_ensem_logs/
c. Architectural Patterns & Principles
– Modular pipeline: each step isolated in its own script or directory for reusability.
– Artifact versioning: checkpoints and logs organized by timestamped folders.
– Separation of concerns: training, ensembling, evaluation, and visualization are distinct components.
d. Technologies & Frameworks
– Python 3.x, PyTorch for model definition and training
– NumPy/Pandas for data handling
– Matplotlib/Seaborn (in plotting.py) for visualizations
– Bash scripts for orchestration
– Jupyter notebooks for exploratory analysis (pipeline.ipynb)

##### Level-of-Detail
- Every major directory as a component.
- Interactions between training and evaluation through shared model artifacts.
- External dependencies (PyTorch library, adversarial-attack utilities).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Data
    RawData["Raw CIFAR-10/100 Data"]:::external

    %% Data Stage
    subgraph "Data Ingestion & Preprocessing"
        DG["Data Generator"]:::compute
        DGStg[[Preprocessed Data / Adversarial Examples]]:::dataStorage
    end

    %% Training Stage
    subgraph "Model Training"
        RT["ResNet Trainer"]:::compute
        AT["Adversarial Trainer"]:::compute
        HT["Hyperparameter Tuner"]:::compute
        CKP[[Checkpoints]]:::dataStorage
        MOD[[Models]]:::dataStorage
    end

    %% Ensemble Stage
    subgraph "Ensemble Orchestrator"
        EO["Ensemble Builder"]:::compute
        EMW[[Ensemble Weights]]:::dataStorage
    end

    %% Evaluation Stage
    subgraph "Evaluation & Robustness Analysis"
        EV["Model Evaluator"]:::compute
        RR[[Robustness Results CSVs]]:::dataStorage
        ER[[Ensemble Robustness Results CSVs]]:::dataStorage
    end

    %% Visualization Stage
    subgraph "Visualization & Reporting"
        GC["Grad-CAM Visualizer"]:::viz
        PV["Plotting Module"]:::viz
        GCV[[gradcam_visualizations/]]:::dataStorage
        GP[[graphs/]]:::dataStorage
    end

    %% Orchestration
    subgraph "Orchestration Scripts"
        OPS1["run_pipeline.sh"]:::orchestration
        OPS2["run_at_alp.sh"]:::orchestration
        OPS3["run_ensemble.sh"]:::orchestration
        OPS4["run_epsilon_sweep.sh"]:::orchestration
        LOGS[[logs/ / multi_ensem_logs/ / nohup.out / sweep_output.log]]:::dataStorage
    end

    %% Flows
    RawData -->|ingest| DG
    DG --> DGStg
    DGStg --> RT
    DGStg --> AT
    DGStg --> HT

    RT --> CKP
    AT --> CKP
    HT --> CKP
    RT --> MOD
    AT --> MOD
    HT --> MOD

    CKP --> EO
    MOD --> EO
    EO --> EMW

    EMW --> EV
    CKP --> EV
    MOD --> EV
    EV --> RR
    EV --> ER

    RR --> PV
    ER --> PV
    RR --> GC
    ER --> GC

    PV --> GP
    GC --> GCV

    %% Orchestration flows
    OPS1 --> DG
    OPS1 --> RT
    OPS1 --> AT
    OPS1 --> EO
    OPS1 --> EV
    OPS1 --> PV
    OPS1 --> GC
    OPS1 --> LOGS
    OPS2 --> AT
    OPS3 --> EO
    OPS4 --> HT

    %% Click Events
    click DG "https://github.com/chanyoung-ken/ai_proj/blob/main/data_generator/data_generator.py"
    click RT "https://github.com/chanyoung-ken/ai_proj/blob/main/data_generator/train_resnet.py"
    click AT "https://github.com/chanyoung-ken/ai_proj/blob/main/attentionlpt.py"
    click AT "https://github.com/chanyoung-ken/ai_proj/blob/main/ensemble_multi_attak.py"
    click HT "https://github.com/chanyoung-ken/ai_proj/blob/main/hyperparameter_tuning.py"
    click EO "https://github.com/chanyoung-ken/ai_proj/blob/main/realensemble.py"
    click EMW "https://github.com/chanyoung-ken/ai_proj/tree/main/ensemble_models/"
    click EV "https://github.com/chanyoung-ken/ai_proj/blob/main/evaluate_models.py"
    click RR "https://github.com/chanyoung-ken/ai_proj/tree/main/robustness_results/"
    click ER "https://github.com/chanyoung-ken/ai_proj/tree/main/ensemble_robustness_results/"
    click GC "https://github.com/chanyoung-ken/ai_proj/blob/main/gradcam.py"
    click GCV "https://github.com/chanyoung-ken/ai_proj/tree/main/gradcam_visualizations/"
    click PV "https://github.com/chanyoung-ken/ai_proj/blob/main/plotting.py"
    click GP "https://github.com/chanyoung-ken/ai_proj/tree/main/graphs/"
    click OPS1 "https://github.com/chanyoung-ken/ai_proj/blob/main/run_pipeline.sh"
    click OPS2 "https://github.com/chanyoung-ken/ai_proj/blob/main/run_at_alp.sh"
    click OPS3 "https://github.com/chanyoung-ken/ai_proj/blob/main/run_ensemble.sh"
    click OPS4 "https://github.com/chanyoung-ken/ai_proj/blob/main/run_epsilon_sweep.sh"
    click CKP "https://github.com/chanyoung-ken/ai_proj/tree/main/data_generator/checkpoints/"
    click MOD "https://github.com/chanyoung-ken/ai_proj/tree/main/data_generator/models/"
    click LOGS "https://github.com/chanyoung-ken/ai_proj/tree/main/logs/"

    %% Styles
    classDef compute fill:#90EE90,stroke:#333,stroke-width:1px
    classDef dataStorage fill:#ADD8E6,stroke:#333,stroke-width:1px
    classDef orchestration fill:#FFA500,stroke:#333,stroke-width:1px
    classDef viz fill:#DDA0DD,stroke:#333,stroke-width:1px
    classDef external fill:#CCCCCC,stroke:#333,stroke-width:1px
```
