# nassimaouldouali/asr-arabic-finetuning architecture

> Architecture diagram of the GitHub repository nassimaouldouali/asr-arabic-finetuning, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-02). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/nassimaouldouali/asr-arabic-finetuning
- Repository: https://github.com/nassimaouldouali/asr-arabic-finetuning

## Overview

This repository is a reproducible Arabic speech-recognition research pipeline: it downloads Common Voice 18, normalizes and filters the audio/transcripts, measures zero-shot baselines, fine-tunes Whisper-small with LoRA, then evaluates and reports the adapted model. The README also describes figures, checkpoint publication, and experiment tracking. The script excerpts show the principal data and model flows; figure-generation and publication details are only partly documented, so uncertain links are omitted or marked unverified.

Main entry points: [`src/04_train.py`](https://github.com/nassimaouldouali/asr-arabic-finetuning/blob/main/src/04_train.py) (LoRA fine-tuning), [`src/checkpoints/best`](https://github.com/nassimaouldouali/asr-arabic-finetuning/tree/main/src/checkpoints/best) (Best LoRA checkpoint), [`src/01_download.py`](https://github.com/nassimaouldouali/asr-arabic-finetuning/blob/main/src/01_download.py) (Dataset download), [`src/03_evaluate_baselines.py`](https://github.com/nassimaouldouali/asr-arabic-finetuning/blob/main/src/03_evaluate_baselines.py) (Zero-shot baselines)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_data_prep["Data preparation"]
  node_download["Dataset download<br/>[01_download.py]"]
  node_raw_data[("Raw dataset")]
  node_preprocess["Arabic preprocessing<br/>[02_preprocess.py]"]
  node_processed_data[("Processed splits")]
end

subgraph group_modeling["Modeling"]
  node_training["LoRA fine-tuning<br/>[04_train.py]"]
  node_checkpoint[("Best LoRA checkpoint")]
end

subgraph group_evaluation["Evaluation"]
  node_baseline["Zero-shot baselines"]
  node_final_eval["Full-set evaluation"]
end

subgraph group_outputs["Research outputs"]
  node_results["Evaluation reports"]
  node_figures["Research figures"]
  node_figure_files["Generated figures"]
end

node_researcher(("Researcher"))
node_cv_dataset[("Common Voice 18")]
node_base_model["Whisper-small"]
node_wandb["Weights &amp; Biases"]
node_hub["Hugging Face Hub"]

node_researcher -->|"runs pipeline"| node_download
node_cv_dataset -->|"provides splits"| node_download
node_download -->|"saves dataset"| node_raw_data
node_raw_data -->|"loads dataset"| node_preprocess
node_preprocess -->|"saves splits"| node_processed_data
node_processed_data -->|"supplies test set"| node_baseline
node_base_model -->|"provides model"| node_baseline
node_baseline -->|"writes metrics"| node_results
node_processed_data -->|"supplies training data"| node_training
node_base_model -->|"provides base weights"| node_training
node_training -->|"saves adapter"| node_checkpoint
node_training -.->|"logs experiments"| node_wandb
node_processed_data -->|"supplies test set"| node_final_eval
node_checkpoint -->|"loads adapter"| node_final_eval
node_final_eval -->|"writes reports"| node_results
node_processed_data -->|"reads distributions"| node_figures
node_raw_data -->|"reads raw text"| node_figures
node_figures -->|"saves plots"| node_figure_files
node_checkpoint -.->|"published model"| node_hub

click node_download "https://github.com/nassimaouldouali/asr-arabic-finetuning/blob/main/src/01_download.py"
click node_preprocess "https://github.com/nassimaouldouali/asr-arabic-finetuning/blob/main/src/02_preprocess.py"
click node_baseline "https://github.com/nassimaouldouali/asr-arabic-finetuning/blob/main/src/03_evaluate_baselines.py"
click node_training "https://github.com/nassimaouldouali/asr-arabic-finetuning/blob/main/src/04_train.py"
click node_checkpoint "https://github.com/nassimaouldouali/asr-arabic-finetuning/tree/main/src/checkpoints/best"
click node_final_eval "https://github.com/nassimaouldouali/asr-arabic-finetuning/blob/main/src/05_evaluate_finetuned.py"
click node_results "https://github.com/nassimaouldouali/asr-arabic-finetuning/tree/main/results"
click node_figures "https://github.com/nassimaouldouali/asr-arabic-finetuning/blob/main/src/06_generate_figures.py"
click node_figure_files "https://github.com/nassimaouldouali/asr-arabic-finetuning/tree/main/src/images"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_download,node_raw_data,node_preprocess,node_processed_data toneBlue
class node_training,node_checkpoint,node_cv_dataset toneAmber
class node_baseline,node_final_eval toneMint
class node_results,node_figures,node_figure_files toneRose
class node_researcher,node_base_model,node_wandb,node_hub toneIndigo
```

## Components

### Data preparation

- [Dataset download](https://github.com/nassimaouldouali/asr-arabic-finetuning/blob/main/src/01_download.py): `src/01_download.py`
- **Raw dataset**
- [Arabic preprocessing](https://github.com/nassimaouldouali/asr-arabic-finetuning/blob/main/src/02_preprocess.py): `src/02_preprocess.py`
- **Processed splits**

### Modeling

- [LoRA fine-tuning](https://github.com/nassimaouldouali/asr-arabic-finetuning/blob/main/src/04_train.py): `src/04_train.py`
- [Best LoRA checkpoint](https://github.com/nassimaouldouali/asr-arabic-finetuning/tree/main/src/checkpoints/best): `src/checkpoints/best`

### Evaluation

- [Zero-shot baselines](https://github.com/nassimaouldouali/asr-arabic-finetuning/blob/main/src/03_evaluate_baselines.py): `src/03_evaluate_baselines.py`
- [Full-set evaluation](https://github.com/nassimaouldouali/asr-arabic-finetuning/blob/main/src/05_evaluate_finetuned.py): `src/05_evaluate_finetuned.py`

### Research outputs

- [Evaluation reports](https://github.com/nassimaouldouali/asr-arabic-finetuning/tree/main/results): `results`
- [Research figures](https://github.com/nassimaouldouali/asr-arabic-finetuning/blob/main/src/06_generate_figures.py): `src/06_generate_figures.py`
- [Generated figures](https://github.com/nassimaouldouali/asr-arabic-finetuning/tree/main/src/images): `src/images`

### Other components

- **Researcher**
- **Common Voice 18**
- **Whisper-small**
- **Weights & Biases**
- **Hugging Face Hub**

## Connections

- Researcher → Dataset download: runs pipeline (evidence: `README.md`)
- Common Voice 18 → Dataset download: provides splits (evidence: `src/01_download.py`)
- Dataset download → Raw dataset: saves dataset (evidence: `src/01_download.py`)
- Raw dataset → Arabic preprocessing: loads dataset (evidence: `src/02_preprocess.py`)
- Arabic preprocessing → Processed splits: saves splits (evidence: `src/02_preprocess.py`)
- Processed splits → Zero-shot baselines: supplies test set (evidence: `src/03_evaluate_baselines.py`)
- Whisper-small → Zero-shot baselines: provides model (evidence: `src/03_evaluate_baselines.py`)
- Zero-shot baselines → Evaluation reports: writes metrics (evidence: `src/03_evaluate_baselines.py`)
- Processed splits → LoRA fine-tuning: supplies training data (evidence: `src/04_train.py`)
- Whisper-small → LoRA fine-tuning: provides base weights (evidence: `README.md`)
- LoRA fine-tuning → Best LoRA checkpoint: saves adapter
- LoRA fine-tuning → Weights & Biases: logs experiments (evidence: `README.md`)
- Processed splits → Full-set evaluation: supplies test set (evidence: `src/05_evaluate_finetuned.py`)
- Best LoRA checkpoint → Full-set evaluation: loads adapter (evidence: `src/05_evaluate_finetuned.py`)
- Full-set evaluation → Evaluation reports: writes reports (evidence: `src/05_evaluate_finetuned.py`)
- Processed splits → Research figures: reads distributions (evidence: `src/06_generate_figures.py`)
- Raw dataset → Research figures: reads raw text (evidence: `src/06_generate_figures.py`)
- Research figures → Generated figures: saves plots (evidence: `src/06_generate_figures.py`)
- Best LoRA checkpoint → Hugging Face Hub: published model (evidence: `README.md`)
