# utkarsharma7/hackenza_2026 architecture

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

- Interactive diagram: https://gitdiagram.com/utkarsharma7/hackenza_2026
- Repository: https://github.com/utkarsharma7/hackenza_2026

## Overview

#### Purpose and execution surface
This is a Python batch ML pipeline for classifying Arabic speakers as Native or Non-Native from audio. Its primary run path is:
`scripts/load_data.py` → `scripts/extract_embeddings.py` → `scripts/train_classifier_compare.py` → `scripts/compare_models_on_test.py`.
A separate final prediction path writes submission-style results through `scripts/final_testing_on_test.py`.

#### Input acquisition and audio preparation
`scripts/load_data.py` consumes URL-and-label records from `manifests/input_data.csv`, downloads audio, converts it to 16 kHz mono, and creates overlapping 10-second chunks. The boundary between external audio sources and local ML artifacts is captured by `manifests/processed_manifest.csv`; chunk files are generated outside the tracked tree under `data/processed_audio_chunks/`.

#### Representation extraction
`scripts/extract_embeddings.py` transforms chunked audio into fixed-size `.npy` feature vectors. It uses the Hugging Face Transformer model `facebook/wav2vec2-lv-60-espeak-cv-ft`, combines temporal Wav2Vec2 statistics with pitch features, normalizes vectors, and emits embedding metadata in `manifests/final_training_manifest.csv` plus the schema dimension in `manifests/embedding_dim.txt`.
`scripts/extract_embeddings_for_CNN.py` is a distinct representation path for sequence-preserving CNN inputs, tracked by `manifests/embedding_dim_cnn.txt`.

#### Model definitions and training
`scripts/model.py` centralizes PyTorch classifier architectures, including the baseline MLP and attention-equipped variant. `scripts/train_classifier_compare.py` loads embedding manifests, performs speaker-aware train/validation splitting, trains MLP, attention MLP, and LightGBM candidates, and chooses an operating threshold by validation F1. Trained artifacts are expected under an untracked `models/` directory; its decision threshold is an essential inference contract.

#### Evaluation and prediction
`scripts/compare_models_on_test.py` evaluates trained candidate models against test data and reports classification metrics across thresholds. `scripts/final_testing_on_test.py` produces persisted final predictions at `manifests/final_preds.csv`; test-oriented inputs/manifests include `manifests/test_data.csv` and `manifests/final_test.csv`. `scripts/make_predictions.py` is the likely standalone inference entry point for applying trained artifacts.

#### CNN alternative branch
The repository also supports an alternative 1D-CNN experiment path: `scripts/extract_embeddings_for_CNN.py` prepares sequential embeddings, `scripts/train1DCNN.py` trains the CNN, and `scripts/compare_cnn_on_test.py` evaluates it. Its dataset contract is separated in `manifests/cnn_training_manifest.csv`, avoiding accidental interchange with pooled-vector MLP/LightGBM inputs.

#### Runtime and external dependencies
The runtime is Python 3.8+ with PyTorch, Transformers, librosa/scipy/torchaudio, scikit-learn, and LightGBM, declared in `requirements.txt`. CUDA is optional but material for Wav2Vec2 extraction and training. External services are source audio URLs and Hugging Face model download/cache infrastructure; the README also references a deployed Hugging Face Space, but deployment code is not present in this tree.

Main entry points: [`scripts/extract_embeddings.py`](https://github.com/utkarsharma7/hackenza_2026/blob/main/scripts/extract_embeddings.py) (Extract pooled embeddings), [`scripts/extract_embeddings_for_CNN.py`](https://github.com/utkarsharma7/hackenza_2026/blob/main/scripts/extract_embeddings_for_CNN.py) (Extract sequential embeddings), [`manifests/test_data.csv`](https://github.com/utkarsharma7/hackenza_2026/blob/main/manifests/test_data.csv) (Test manifests), [`scripts/load_data.py`](https://github.com/utkarsharma7/hackenza_2026/blob/main/scripts/load_data.py) (Load and chunk audio)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ingest["Audio ingestion"]
  node_audio_urls(("Source audio URLs<br/>external source"))
  node_input_manifest["Input records<br/>CSV manifest<br/>[input_data.csv]"]
  node_load_data["Load and chunk audio<br/>Python batch script<br/>[load_data.py]"]
  node_processed_manifest["Processed manifest<br/>CSV manifest"]
  node_audio_chunks[("Processed audio chunks<br/>local artifact store")]
end

subgraph group_vector["Pooled-vector pipeline"]
  node_hf_wav2vec{{"Wav2Vec2 model cache<br/>external model"}}
  node_extract_embeddings["Extract pooled embeddings<br/>Python batch script"]
  node_training_manifest["Vector training manifest<br/>CSV manifest"]
  node_embedding_dim["Vector schema dimension<br/>schema contract<br/>[embedding_dim.txt]"]
  node_model_defs["Classifier architectures<br/>PyTorch module<br/>[model.py]"]
  node_train_compare["Train and select models<br/>Python training script"]
  node_model_artifacts[("Trained models and threshold<br/>local artifact store")]
end

subgraph group_cnn["CNN experiment branch"]
  node_extract_cnn["Extract sequential embeddings<br/>Python batch script"]
  node_cnn_manifest["CNN training manifest<br/>CSV manifest"]
  node_cnn_dim["CNN schema dimension<br/>schema contract"]
  node_train_cnn["Train 1D CNN<br/>Python training script<br/>[train1DCNN.py]"]
end

subgraph group_inference["Evaluation and inference"]
  node_test_manifests["Test manifests<br/>CSV manifests<br/>[test_data.csv]"]
  node_compare_models["Evaluate candidate models<br/>Python evaluation script"]
  node_compare_cnn["Evaluate CNN<br/>Python evaluation script"]
  node_make_predictions["Standalone inference<br/>Python inference script"]
  node_final_testing["Produce final predictions<br/>Python prediction script"]
  node_final_preds["Final predictions<br/>CSV output<br/>[final_preds.csv]"]
end

node_audio_urls -->|"downloads"| node_load_data
node_input_manifest -->|"URLs and labels"| node_load_data
node_load_data -->|"converts and chunks"| node_audio_chunks
node_load_data -->|"records chunks"| node_processed_manifest
node_processed_manifest -->|"chunk metadata"| node_extract_embeddings
node_audio_chunks -->|"audio"| node_extract_embeddings
node_hf_wav2vec -.->|"feature model"| node_extract_embeddings
node_extract_embeddings -->|"vector metadata"| node_training_manifest
node_extract_embeddings -->|"writes schema"| node_embedding_dim
node_training_manifest -->|"pooled vectors"| node_train_compare
node_embedding_dim -.->|"input contract"| node_train_compare
node_model_defs -->|"MLP variants"| node_train_compare
node_train_compare -->|"models and threshold"| node_model_artifacts
node_processed_manifest -->|"chunk metadata"| node_extract_cnn
node_audio_chunks -->|"audio"| node_extract_cnn
node_hf_wav2vec -.->|"feature model"| node_extract_cnn
node_extract_cnn -->|"sequence metadata"| node_cnn_manifest
node_extract_cnn -->|"writes schema"| node_cnn_dim
node_cnn_manifest -->|"sequences"| node_train_cnn
node_train_cnn -->|"CNN artifact"| node_model_artifacts
node_test_manifests -->|"test inputs"| node_compare_models
node_model_artifacts -->|"candidates and threshold"| node_compare_models
node_test_manifests -->|"test inputs"| node_compare_cnn
node_model_artifacts -->|"CNN artifact"| node_compare_cnn
node_test_manifests -->|"prediction inputs"| node_make_predictions
node_model_artifacts -->|"inference contract"| node_make_predictions
node_test_manifests -->|"final test inputs"| node_final_testing
node_model_artifacts -->|"selected model"| node_final_testing
node_final_testing -->|"writes"| node_final_preds

click node_input_manifest "https://github.com/utkarsharma7/hackenza_2026/blob/main/manifests/input_data.csv"
click node_load_data "https://github.com/utkarsharma7/hackenza_2026/blob/main/scripts/load_data.py"
click node_processed_manifest "https://github.com/utkarsharma7/hackenza_2026/blob/main/manifests/processed_manifest.csv"
click node_extract_embeddings "https://github.com/utkarsharma7/hackenza_2026/blob/main/scripts/extract_embeddings.py"
click node_training_manifest "https://github.com/utkarsharma7/hackenza_2026/blob/main/manifests/final_training_manifest.csv"
click node_embedding_dim "https://github.com/utkarsharma7/hackenza_2026/blob/main/manifests/embedding_dim.txt"
click node_model_defs "https://github.com/utkarsharma7/hackenza_2026/blob/main/scripts/model.py"
click node_train_compare "https://github.com/utkarsharma7/hackenza_2026/blob/main/scripts/train_classifier_compare.py"
click node_extract_cnn "https://github.com/utkarsharma7/hackenza_2026/blob/main/scripts/extract_embeddings_for_CNN.py"
click node_cnn_manifest "https://github.com/utkarsharma7/hackenza_2026/blob/main/manifests/cnn_training_manifest.csv"
click node_cnn_dim "https://github.com/utkarsharma7/hackenza_2026/blob/main/manifests/embedding_dim_cnn.txt"
click node_train_cnn "https://github.com/utkarsharma7/hackenza_2026/blob/main/scripts/train1DCNN.py"
click node_test_manifests "https://github.com/utkarsharma7/hackenza_2026/blob/main/manifests/test_data.csv"
click node_compare_models "https://github.com/utkarsharma7/hackenza_2026/blob/main/scripts/compare_models_on_test.py"
click node_compare_cnn "https://github.com/utkarsharma7/hackenza_2026/blob/main/scripts/compare_cnn_on_test.py"
click node_make_predictions "https://github.com/utkarsharma7/hackenza_2026/blob/main/scripts/make_predictions.py"
click node_final_testing "https://github.com/utkarsharma7/hackenza_2026/blob/main/scripts/final_testing_on_test.py"
click node_final_preds "https://github.com/utkarsharma7/hackenza_2026/blob/main/manifests/final_preds.csv"

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_audio_urls,node_input_manifest,node_load_data,node_processed_manifest,node_audio_chunks toneBlue
class node_hf_wav2vec,node_extract_embeddings,node_training_manifest,node_embedding_dim,node_model_defs,node_train_compare,node_model_artifacts toneAmber
class node_extract_cnn,node_cnn_manifest,node_cnn_dim,node_train_cnn toneMint
class node_test_manifests,node_compare_models,node_compare_cnn,node_make_predictions,node_final_testing,node_final_preds toneRose
```

## Components

### Audio ingestion

- **Source audio URLs**: external source · Remote audio and associated labels.
- [Input records](https://github.com/utkarsharma7/hackenza_2026/blob/main/manifests/input_data.csv): CSV manifest · `manifests/input_data.csv`
- [Load and chunk audio](https://github.com/utkarsharma7/hackenza_2026/blob/main/scripts/load_data.py): Python batch script · Downloads, converts to 16 kHz mono, and creates overlapping chunks. · `scripts/load_data.py`
- [Processed manifest](https://github.com/utkarsharma7/hackenza_2026/blob/main/manifests/processed_manifest.csv): CSV manifest · Boundary for local chunked-audio artifacts. · `manifests/processed_manifest.csv`
- **Processed audio chunks**: local artifact store · Untracked 10-second audio chunks.

### Pooled-vector pipeline

- **Wav2Vec2 model cache**: external model · facebook/wav2vec2-lv-60-espeak-cv-ft download/cache.
- [Extract pooled embeddings](https://github.com/utkarsharma7/hackenza_2026/blob/main/scripts/extract_embeddings.py): Python batch script · Combines Wav2Vec2 temporal statistics and pitch into normalized vectors. · `scripts/extract_embeddings.py`
- [Vector training manifest](https://github.com/utkarsharma7/hackenza_2026/blob/main/manifests/final_training_manifest.csv): CSV manifest · `manifests/final_training_manifest.csv`
- [Vector schema dimension](https://github.com/utkarsharma7/hackenza_2026/blob/main/manifests/embedding_dim.txt): schema contract · `manifests/embedding_dim.txt`
- [Classifier architectures](https://github.com/utkarsharma7/hackenza_2026/blob/main/scripts/model.py): PyTorch module · Baseline and attention-equipped MLP definitions. · `scripts/model.py`
- [Train and select models](https://github.com/utkarsharma7/hackenza_2026/blob/main/scripts/train_classifier_compare.py): Python training script · Speaker-aware split; compares MLP, attention MLP, and LightGBM using validation F1. · `scripts/train_classifier_compare.py`
- **Trained models and threshold**: local artifact store · Untracked models plus the selected inference threshold.

### CNN experiment branch

- [Extract sequential embeddings](https://github.com/utkarsharma7/hackenza_2026/blob/main/scripts/extract_embeddings_for_CNN.py): Python batch script · Preserves embedding sequences for CNN experiments. · `scripts/extract_embeddings_for_CNN.py`
- [CNN training manifest](https://github.com/utkarsharma7/hackenza_2026/blob/main/manifests/cnn_training_manifest.csv): CSV manifest · Separate contract for sequential CNN inputs. · `manifests/cnn_training_manifest.csv`
- [CNN schema dimension](https://github.com/utkarsharma7/hackenza_2026/blob/main/manifests/embedding_dim_cnn.txt): schema contract · `manifests/embedding_dim_cnn.txt`
- [Train 1D CNN](https://github.com/utkarsharma7/hackenza_2026/blob/main/scripts/train1DCNN.py): Python training script · `scripts/train1DCNN.py`

### Evaluation and inference

- [Test manifests](https://github.com/utkarsharma7/hackenza_2026/blob/main/manifests/test_data.csv): CSV manifests · Test-oriented input and final test records. · `manifests/test_data.csv`
- [Evaluate candidate models](https://github.com/utkarsharma7/hackenza_2026/blob/main/scripts/compare_models_on_test.py): Python evaluation script · Reports test classification metrics across thresholds. · `scripts/compare_models_on_test.py`
- [Evaluate CNN](https://github.com/utkarsharma7/hackenza_2026/blob/main/scripts/compare_cnn_on_test.py): Python evaluation script · `scripts/compare_cnn_on_test.py`
- [Standalone inference](https://github.com/utkarsharma7/hackenza_2026/blob/main/scripts/make_predictions.py): Python inference script · Applies trained artifacts to prediction inputs. · `scripts/make_predictions.py`
- [Produce final predictions](https://github.com/utkarsharma7/hackenza_2026/blob/main/scripts/final_testing_on_test.py): Python prediction script · `scripts/final_testing_on_test.py`
- [Final predictions](https://github.com/utkarsharma7/hackenza_2026/blob/main/manifests/final_preds.csv): CSV output · Persisted submission-style results. · `manifests/final_preds.csv`

## Connections

- Source audio URLs → Load and chunk audio: downloads
- Input records → Load and chunk audio: URLs and labels
- Load and chunk audio → Processed audio chunks: converts and chunks
- Load and chunk audio → Processed manifest: records chunks
- Processed manifest → Extract pooled embeddings: chunk metadata
- Processed audio chunks → Extract pooled embeddings: audio
- Wav2Vec2 model cache → Extract pooled embeddings: feature model
- Extract pooled embeddings → Vector training manifest: vector metadata
- Extract pooled embeddings → Vector schema dimension: writes schema
- Vector training manifest → Train and select models: pooled vectors
- Vector schema dimension → Train and select models: input contract
- Classifier architectures → Train and select models: MLP variants
- Train and select models → Trained models and threshold: models and threshold
- Processed manifest → Extract sequential embeddings: chunk metadata
- Processed audio chunks → Extract sequential embeddings: audio
- Wav2Vec2 model cache → Extract sequential embeddings: feature model
- Extract sequential embeddings → CNN training manifest: sequence metadata
- Extract sequential embeddings → CNN schema dimension: writes schema
- CNN training manifest → Train 1D CNN: sequences
- Train 1D CNN → Trained models and threshold: CNN artifact
- Test manifests → Evaluate candidate models: test inputs
- Trained models and threshold → Evaluate candidate models: candidates and threshold
- Test manifests → Evaluate CNN: test inputs
- Trained models and threshold → Evaluate CNN: CNN artifact
- Test manifests → Standalone inference: prediction inputs
- Trained models and threshold → Standalone inference: inference contract
- Test manifests → Produce final predictions: final test inputs
- Trained models and threshold → Produce final predictions: selected model
- Produce final predictions → Final predictions: writes