How eshaanpra/scaihackathonv2 works
Project Type and Purpose
• This is a Python-based research/hackathon prototype (CLI application) that benchmarks ASR equity in customer-support call flows.
• It runs a configurable pipeline: loads speech samples → transcribes (ASR) → classifies intent → computes fairness metrics → generates visual reports.
File Structure Analysis
• Top-level:
• configs/ – YAML configurations for different modes (quick demo, real-data, OpenAI Whisper, etc.)
• src/ – core modules: main.py, pipeline, data loader, ASR wrapper, intent classifier, metrics, visualization
• requirements.txt, run_quick_demo.sh – setup/run scripts
• src/ modules follow a clear ETL pipeline pattern:
• data_loader.py (input)
• asr_engine.py (transcription)
• intent_classifier.py (downstream model)
• metrics.py (calculations)
Architecture Insights from README
• Entry point: src/main.py reads a config, instantiates Pipeline.
• Pipeline components are pluggable (mock ASR vs. Whisper vs. HF), driven by configs.
• Outputs: CSV/JSON metrics + matplotlib plots, organized under outputs/<run_name>.
a. Main Components
• CLI / Config Loader
• Data Loader
• ASR Engine (mock | Whisper)
• Intent Classifier
• Metrics Calculator
• Visualizer (plots, heatmaps)
• File System (configs, input corpora, outputs)
• External Services: speech datasets (Common Voice, CallHome, GLOBE), model repos (HuggingFace, OpenAI)
b. Relationships & Data Flow
1) User invokes CLI → config.yaml
2) Config Loader → Pipeline orchestrator
3) Pipeline calls Data Loader → loads/streams audio + metadata
4) Each sample → ASR Engine → transcript
5) Transcript → Intent Classifier → predicted intent
6) References vs. predictions → Metrics Calculator → WER, intent error, disparity index
7) Metrics + raw results → Visualizer → plots/CSVs under outputs/
c. Architectural Patterns & Principles
• Modular pipeline: single-responsibility modules chained in sequence
• Configuration-driven behavior enabling offline demo or real-data runs
• Pluggable ASR backends using a wrapper interface (mock vs. whisper vs. hf_whisper)
d. Technologies & Frameworks
• Python 3.10+ core, PyYAML (config), numpy, matplotlib
• Optional: datasets, openai-whisper, librosa, soundfile, torch/transformers