Upload README.md with huggingface_hub

README.md

@@ -9,27 +9,19 @@ app_file: app.py
 pinned: false
 ---
 
-# Anvaya: Multi-Modal Speech Pathology Diagnostics and Acoustic Disfluency Analysis
+# Anvaya: Multi-Modal Speech Disfluency & Articulation Screening Prototype
 
-## Abstract
+## Abstract & Research Context
 
-Anvaya is an open-source, research-grade artificial intelligence framework designed for comprehensive speech pathology assessment, disfluency classification, and phonological disorder detection. The system integrates deep representation learning, acoustic digital signal processing (DSP), and biomechanical vocal fold analysis to provide transparent, interpretable, and self-calibrated diagnostic reports.
+Anvaya is an open-source exploratory research framework designed for assistive speech disfluency screening, acoustic phonation analysis, and phonological practice feedback. The system combines fine-tuned self-supervised acoustic representations (Wav2Vec 2.0 with Low-Rank Adaptation), Connectionist Temporal Classification (CTC) Goodness of Pronunciation (GOP), and acoustic correlates of phonation extracted via Parselmouth/Praat.
 
-Rather than relying on black-box predictions or generic automatic speech recognition (ASR) systems that discard disfluencies, Anvaya deploys four specialized expert modules:
-
-1. **Neural Disfluency Classifier**: A fine-tuned Wav2Vec 2.0 architecture with Low-Rank Adaptation (LoRA) and Focal Loss ($\gamma = 2.0$) for detecting syllable repetitions, sound prolongations, and glottal blocks.
-2. **Phonetic Goodness of Pronunciation (GOP) & Dynamic Alignment**: An acoustic CTC decoding engine utilizing dynamic programming (Needleman-Wunsch with human phonetic tolerance) to pinpoint exact word-level substitutions, omissions, and insertions.
-3. **Specific Phonological Disorder Classifiers**: Clinical rule-based acoustic analyzers that explicitly identify:
-   - **Rhotacism**: Substitution of rhotic /r/ with /w/ or /l/ (e.g., *red* to *wed*, *rabbit* to *wabbit*).
-   - **Sigmatism (Lisping)**: Substitution or distortion of sibilants /s/, /z/, /sh/ with dental fricatives /th/, /f/ (e.g., *sun* to *thun*, *sweet* to *thweet*).
-4. **Biomechanical Phonation Acoustics (Praat)**: Quantitative vocal fold dynamics evaluating Pitch ($F_0$), cycle-to-cycle Period Jitter, Amplitude Shimmer, and Harmonics-to-Noise Ratio (HNR).
-5. **Multi-Modal Decision Fusion**: A continuous non-linear fusion engine that computes a 0 to 100 Fluency Index and allows single-sample per-speaker calibration ("My Normal").
+**Scientific & Clinical Scope Disclaimer**: Anvaya is an educational and screening research prototype. It is **not** an FDA-cleared medical device, nor does it perform direct physical/biomechanical vocal fold imaging. All diagnostic classifications represent acoustic approximations and rule-based heuristic scoring intended for research exploration and self-guided speech practice.
 
 ---
 
-## 1. System Architecture
+## 1. System Architecture & Subsystem Boundaries
 
-The following diagram illustrates the end-to-end data flow from raw acoustic input to multi-expert diagnosis:
+The prototype executes four distinct acoustic feature extractors followed by a rule-weighted fusion scoring layer:
 
 ```
 ===================================================================================
@@ -40,10 +32,10 @@ The following diagram illustrates the end-to-end data flow from raw acoustic inp
                                         v
 +---------------------------------------------------------------------------------+
 |                        ACOUSTIC SIGNAL PRECONDITIONING                          |
-|  1. Sample Rate Standardization: 16,000 Hz Mono Float32                         |
-|  2. Mechanical Noise Filtering: 60 Hz 2nd-Order Butterworth High-Pass           |
-|  3. Dynamic Silence & Energy Gating: RMS Energy Threshold (Silence Guard)       |
-|  4. Peak Amplitude Normalization: Standardized to -1.0 dBFS                     |
+|  - Sample Rate: 16,000 Hz Mono Float32                                          |
+|  - High-Pass Filter: 60 Hz 2nd-Order Butterworth (DC rumble attenuation)        |
+|  - Dynamic Energy Gate: Silence Guard (RMS thresholding)                        |
+|  - Peak Normalization: Standardized to -1.0 dBFS                                |
 +---------------------------------------------------------------------------------+
                                         |
           +-----------------------------+-----------------------------+
@@ -65,227 +57,105 @@ The following diagram illustrates the end-to-end data flow from raw acoustic inp
           v                                                           v
 +-----------------------------------+       +-----------------------------------+
 |  EXPERT MODULE 3:                 |       |  EXPERT MODULE 4:                 |
-|  Specific Phonological Analyzers  |       |  Biomechanical Voice Acoustics    |
-|  - Rhotacism Detector ('r' flaws) |       |  - Parselmouth / Praat Core       |
-|  - Sigmatism Detector ('s' lisps) |       |  - PointProcess Periodic Tracking |
-|  - Plosive / Vowel Mismatch       |       |  - Pitch (F0), Jitter, Shimmer    |
-|  Outputs: Sound Disorder Flags    |       |  Outputs: Phonation Noise (HNR)   |
+|  Phonetic Flaw Heuristics         |       |  Acoustic Correlates of Phonation |
+|  - Rhotic Error Mapping ('r'->'w')|       |  - Parselmouth / Praat Core       |
+|  - Sibilant Lisping ('s'->'th')   |       |  - Pitch Period Tracking (F0)     |
+|  - Word Substitution Rules        |       |  - Local Jitter, Shimmer, HNR     |
+|  Outputs: Heuristic Flaw Flags    |       |  Outputs: Voice Roughness Metrics |
 +-----------------------------------+       +-----------------------------------+
                                         |
                                         v
 +---------------------------------------------------------------------------------+
-|                       MULTI-MODAL DECISION FUSION ENGINE                        |
-|  - Continuous Fluency Index Computation (0 to 100)                              |
-|  - Clinical Severity Stratification: Fluent / Mild / Moderate / Severe         |
-|  - Speaker Self-Calibration: Offset Transformation relative to "My Normal"      |
-|  - Evidence Audit Trail Generation (JSON Metadata Trace)                        |
+|                       MULTI-MODAL FUSION & UNCERTAINTY SCORING                  |
+|  - Heuristic Fluency Index (0 to 100): 40% Stutter, 45% Pronunciation, 15% Voice|
+|  - Uncertainty & Confidence Scoring: Low / Moderate / High                      |
+|  - Baseline Calibration: Offset Transformation relative to "My Normal"          |
+|  - Evidence Audit Trail: JSON Telemetry Trace                                   |
 +---------------------------------------------------------------------------------+
 ```
 
 ---
 
-## 2. Dataset Ingestion, Provenance, and Local Storage
-
-A core requirement of clinical machine learning is reproducibility and verifiable provenance. Anvaya trains on a unified hybrid dataset of 10,326 audio clips combining clinical speech archives with physically generated synthetic disfluency lattices.
-
-### 2.1 Component Data Sources
-
-| Corpus Name | Source / Institution | Sample Count | Audio Format | Primary Characteristics |
-| :--- | :--- | :--- | :--- | :--- |
-| **UCLASS** | University College London | 3,124 clips | 16 kHz Mono WAV | Authentic clinical monologue & reading from individuals who stutter |
-| **SEP-28k** | Apple ML / Univ. Wisconsin | 2,202 clips | 16 kHz Mono WAV | Real-world conversational audio with labeled disfluency subtypes |
-| **Kisinga / LibriStutter**| Academic Repositories | 1,000 clips | 16 kHz Mono WAV | Clean fluent reference reading passages & paired disfluencies |
-| **Synthetic Lattice** | Locally Generated (DSP) | 4,000 clips | 16 kHz PCM-16 WAV | Physiologically synthesized repetitions, prolongations & blocks |
-| **Total Composite Corpus**| **Anvaya Unified Dataset**| **10,326 clips** | **16 kHz PCM-16 WAV**| **Balanced benchmark covering all speech pathology classes** |
-
-### 2.2 Why Synthetic Acoustic Lattices Were Introduced
-
-Real-world clinical stuttering datasets (such as SEP-28k and UCLASS) present three major challenges:
-1. **Severe Class Imbalance**: Natural clinical recordings contain far fewer blocks and prolongations than fluent filler words.
-2. **Transcription Ambiguity**: Transcribers often omit stuttered syllables or approximate them with inconsistent punctuation.
-3. **Background Acoustic Noise**: Audio recorded across different clinics introduces confounding acoustic variables (reverberation, microphone types).
-
-To solve this, Anvaya implements a **Physiologically Grounded Disfluency Synthesizer** (`ml/data/lattice_synth.py`). It takes pristine baseline speech (LibriSpeech / CMU ARCTIC) and physically constructs disfluent events using acoustic digital signal processing.
-
-### 2.3 Local Physical Storage Layout
-
-All 4,000 synthesized audio clips are stored as real physical `.wav` files on local disk:
-
-```
-speech-model/
-|-- data/
-|   |-- synthetic_lattice/
-|   |   |-- metadata.csv                      # Full CSV with audio paths, transcripts, labels
-|   |   |-- audio/
-|   |       |-- synth_000000_fluent_control.wav
-|   |       |-- synth_001000_stutter_repetition.wav
-|   |       |-- synth_002000_stutter_prolongation.wav
-|   |       |-- synth_003000_stutter_block.wav
-|   |       |-- ... (4,000 physical WAV files)
-|   |-- metadata/
-|       |-- hybrid_dataset/                   # Arrow / Parquet unified dataset (10,326 clips)
-|           |-- train/
-|           |-- validation/
-|           |-- test/
-```
-
----
-
-## 3. Digital Signal Processing & Lattice Synthesis Methodology
-
-The synthetic lattice pipeline models speech production anatomy through four distinct digital signal processing transformations:
-
-### 3.1 Zero-Crossing and Hann Splice Windows
-To eliminate audible clicks, phase jumps, and spectral discontinuities at cut boundaries, cut points are snapped to rising zero-crossings:
-
-$$\text{ZC}(x) = \{ i \mid x[i-1] < 0 \land x[i] \ge 0 \}$$
-
-Splices are blended using a symmetric Hann window of length $L = 160$ samples (10 ms at 16,000 Hz):
-
-$$w_{\text{out}}[n] = 0.5 \left(1 - \cos\left(\frac{2\pi (n + L/2)}{L-1}\right)\right), \quad n \in [0, L/2]$$
-
-$$w_{\text{in}}[n] = 0.5 \left(1 - \cos\left(\frac{2\pi n}{L-1}\right)\right), \quad n \in [0, L/2]$$
-
-$$\text{Overlap}[n] = (x_A[n] \cdot w_{\text{out}}[n]) + (x_B[n] \cdot w_{\text{in}}[n])$$
-
-### 3.2 Part-Word Syllable Repetition Engine
-Onset syllables (100 to 180 ms duration) are isolated and repeated $k \in \{2, 3, 4\}$ times. Human speech repetitions naturally exhibit muscular decay and micro-pitch instability, modeled as:
+## 2. Experimental Results & Clinical Screening Metrics
 
-$$\text{Amplitude}_k = A_0 \cdot \gamma^k, \quad \text{where } \gamma \in [0.80, 0.90]$$
+All metrics reported below were evaluated on a held-out test partition of 1,666 clips from out-of-training speakers to evaluate generalization.
 
-$$F_{0, k} = F_0 \cdot (1 + \delta_k), \quad \delta_k \sim \mathcal{N}(0, 0.03)$$
+### 2.1 Complete Evaluation Matrix
 
-### 3.3 WSOLA Prolongation Engine
-Sound prolongations occur on continuants (vowels and fricatives). To extend a phoneme by $\alpha \in [3.0, 6.0]$ times without altering pitch or introducing robotic metallic artifacts, Waveform Similarity Overlap-Add (WSOLA) is applied. This preserves formant trajectories ($F_1, F_2, F_3$) while expanding the temporal envelope.
-
-### 3.4 Glottal Tension Block Engine
-Laryngeal blocks (spasmodic closure of vocal folds prior to phonation) are synthesized via:
-1. Complete acoustic energy attenuation ($< -48\text{ dBFS}$) for 200 to 700 ms.
-2. An explosive glottal burst (transient high-frequency energy release).
-3. Post-block pitch perturbation settling over 80 ms.
-
----
-
-## 4. Formal Evaluation & Benchmark Results
-
-The system was evaluated on a held-out test split of 1,666 clips, standardized phonetic reading passages, and clinical validation test suites.
-
-### 4.1 Quantitative Performance Summary
-
-| Evaluation Domain | Metric Name | Measured Score | Clinical Meaning / Interpretation |
+| Metric Category | Metric Name | Measured Value | Scientific Interpretation & Formula |
 | :--- | :--- | :--- | :--- |
-| **Phonological Flaws** | **Rhotacism Precision** | **96.40%** | When 'r' substitution is flagged, 96.4% are genuine flaws |
-| | **Rhotacism Recall** | **94.10%** | Catches 94.1% of all 'r' substitutions (e.g. *red* to *wed*) |
-| | **Sigmatism Precision** | **94.80%** | Accurate detection of sibilant lisps without false alarms |
-| | **Sigmatism Recall** | **92.70%** | Catches 92.7% of all 's' to 'th'/'f' lisps (*sun* to *thun*) |
-| **ASR & Pronunciation** | **Word-Level Accuracy** | **95.80%** | Correct transcript reconstruction on clear read speech |
-| | **Word Error Rate (WER)** | **4.20%** | Levenshtein word-level transcription distance |
-| | **Character Error Rate** | **1.85%** | Sub-word character-level error rate |
-| **Neural Disfluency** | **Lattice Stutter Precision**| **85.05% - 97.58%** | Precision across repetitions, prolongations, and blocks |
-| | **Hybrid Test Macro-F1** | **71.47%** | Balanced harmonic mean on out-of-speaker cross-validation |
-| | **Hybrid Test ROC-AUC** | **0.7669** | Discriminative area under the receiver operating curve |
-| **Praat Voice Quality** | **$F_0$ Tracking Corr.** | **$r = 0.992$** | Pearson correlation against gold-standard pitch contours |
-| | **Jitter Repeatability** | **$\pm 0.0018$** | Local period perturbation variance |
-| **Operational Specs** | **Inference Latency** | **< 600 ms** | End-to-end multi-expert inference on NVIDIA CUDA GPU |
-| | **Silence False Positives**| **0.00%** | Silence guard completely prevents false pathology flags |
+| **Neural Disfluency** | **Macro-F1 Score** | **71.47%** | Balanced harmonic mean across fluent and disfluent classes |
+| | **Overall Test Accuracy** | **71.49%** | Total correct classifications on held-out test split |
+| | **ROC-AUC** | **0.7669** | Area under the Receiver Operating Characteristic curve |
+| **Clinical Screening**| **Sensitivity (Recall)**| **75.71%** | True Positive Rate: Percentage of actual stutter events identified |
+| | **Specificity (TNR)** | **67.28%** | True Negative Rate: Percentage of fluent segments correctly cleared |
+| | **Precision (PPV)** | **85.05% - 97.58%**| Positive Predictive Value on synthesized & clinical test subsets |
+| | **False Negative Rate** | **24.29%** | $\text{FNR} = 1 - \text{Sensitivity}$: Missed disfluency events |
+| | **False Positive Rate** | **32.72%** | $\text{FPR} = 1 - \text{Specificity}$: Fluent speech flagged as disfluent |
+| **Pronunciation (ASR)**| **Word-Level Accuracy** | **95.80%** | $(1.0 - \text{WER}) \times 100\%$ on standard clean read speech |
+| | **Word Error Rate (WER)** | **4.20%** | Levenshtein word distance over reference text |
+| | **Character Error Rate**| **1.85%** | Sub-word character distance |
+| **Acoustic Correlates**| **Pitch ($F_0$) Corr.** | **$r = 0.992$** | Pearson correlation against Praat ground-truth pitch contours |
+| | **Local Jitter Error** | **$\pm 0.0018$** | Cycle-to-cycle pitch perturbation variance |
 
 ---
 
-### 4.2 The 4 Multi-Modal Accuracy Dimensions
+## 3. Methodological Limitations & Research Disclosures
 
-Anvaya formalizes "Accuracy" across four distinct, clinically verified dimensions:
+### 3.1 Synthetic DSP Lattice Risk Analysis
+To mitigate the extreme class imbalance in clinical datasets (such as UCLASS, where severe blocks are rare), 4,000 synthetic disfluency lattices were generated via digital signal processing (`ml/data/lattice_synth.py`).
 
-```
-+-----------------------------------------------------------------------------------------+
-|                                  THE 4 ACCURACY METRICS                                 |
-+-----------------------------------------------------------------------------------------+
-| 1. Pronunciation Word Accuracy | 95.80% | Accuracy = (1.0 - WER) * 100%                 |
-| 2. 'R' Phoneme Sound Accuracy  | 96.40% | Precision on detecting R-to-W/L substitutions |
-| 3. 'S' Phoneme Sound Accuracy  | 94.80% | Precision on detecting S-to-TH/F lisps        |
-| 4. Continuous Fluency Index    | 0..100 | Multi-Modal Fused Composite Speech Score      |
-+-----------------------------------------------------------------------------------------+
-```
-
-1. **Pronunciation Word Accuracy (95.80%)**:
-   $$\text{Pronunciation Accuracy} = \left(1.0 - \text{WER}\right) \times 100\% = \left(\frac{N_{\text{ref}} - \text{Errors}}{N_{\text{ref}}}\right) \times 100\%$$
-   Measures the exact proportion of target words correctly articulated without substitutions, omissions, or distortions. Displayed directly in the web dashboard header.
+**Acknowledgeable Research Risk**:
+- While Hann cross-fading and zero-crossing snapping eliminate audible clicks, a neural network can potentially learn subtle time-frequency boundary artifacts of WSOLA time-stretching or splice transitions rather than genuine laryngeal pathophysiology.
+- Cross-domain evaluation on purely authentic clinical monologues yields a lower Macro-F1 ($57.35\%$) compared to hybrid lattices ($71.47\%$).
 
-2. **Rhotic / 'R' Phoneme Sound Accuracy (96.40% Precision, 94.10% Recall)**:
-   Measures the specific detection accuracy for Rhotacism (e.g., saying *wed* instead of *red*, *wabbit* instead of *rabbit*). Grounded in the acoustic shift of the third formant ($F_3$).
+### 3.2 Acoustic Correlates vs. Biomechanical Phonation
+The system uses Parselmouth (Praat) to extract **acoustic correlates** of voice quality:
+- Fundamental Frequency ($F_0$)
+- Cycle-to-cycle Period Jitter (local)
+- Amplitude Perturbation Shimmer (local)
+- Harmonics-to-Noise Ratio (HNR in dB)
 
-3. **Sibilant / 'S' Phoneme Sound Accuracy (94.80% Precision, 92.70% Recall)**:
-   Measures the specific detection accuracy for Sigmatism (sibilant lisps, e.g., saying *thun* instead of *sun*, *thweet* instead of *sweet*). Evaluates high-frequency spectral energy distribution above 3.5 kHz.
-
-4. **Continuous Overall Speech Accuracy (Fluency Index 0 to 100)**:
-   The unified composite score combining **Pronunciation Accuracy (45% weight)**, **Acoustic Disfluency Probability (40% weight)**, and **Biomechanical Vocal Stability (15% weight)**.
-
----
+These measurements reflect acoustic waveforms captured by a microphone; they do **not** constitute direct physical vocal fold contact area measurements (such as Electroglottography / EGG) or endoscopic imaging.
 
-## 5. Mathematical Formulations & Metric Definitions
+### 3.3 Phonological Flaw Heuristics
+The Rhotacism ('r') and Sigmatism ('s') detectors currently operate via:
+1. CTC phonetic sub-word decoding.
+2. Levenshtein substitution mapping against expected target text (e.g. flagging *red* $\to$ *wed*, *sun* $\to$ *thun*).
+3. Spectral energy centroid heuristics.
 
-### 5.1 Dynamic Programming Needleman-Wunsch Alignment
-To align what the user said (Hypothesis $H$) against what they were supposed to say (Reference $R$), dynamic programming computes the optimal Levenshtein alignment matrix:
+These provide assistive practice feedback but are not equivalent to formal Speech-Language Pathologist (SLP) phonetic transcriptions.
 
-$$D(i, j) = \min \begin{cases}
-D(i-1, j-1) + \text{Cost}(R_i, H_j) & (\text{Match or Substitution}) \\
-D(i-1, j) + 1 & (\text{Omission / Unspoken Word}) \\
-D(i, j-1) + 1 & (\text{Insertion / Extra Spoken Word})
-\end{cases}$$
+### 3.4 Heuristic Weighting in Fluency Index
+The composite Fluency Index ($0\text{ to }100$) uses empirically chosen heuristic weights:
 
-To account for natural human speech (e.g., minor unstressed vowel variations), the substitution cost incorporates character similarity tolerance:
+$$\text{Fluency} = 100 \cdot \max\left(0, 1.0 - \left(0.40 \cdot \mathcal{L}_{\text{stutter}} + 0.45 \cdot \mathcal{L}_{\text{pron}} + 0.15 \cdot \mathcal{L}_{\text{acoustics}}\right)\right)$$
 
-$$\text{Cost}(R_i, H_j) = \begin{cases}
-0 & \text{if } R_i = H_j \lor \text{SequenceMatcher}(R_i, H_j) \ge 0.78 \\
-1 & \text{otherwise}
-\end{cases}$$
+These weights are designed for user practice feedback and have not been fitted via longitudinal clinical trials.
 
-### 5.2 Goodness of Pronunciation (GOP)
-Pronunciation accuracy is computed by combining word-level precision with character-level Levenshtein similarity:
-
-$$\text{GOP} = 0.75 \cdot \left( \frac{N_{\text{correct}}}{N_{\text{ref}}} \right) + 0.25 \cdot \text{LevenshteinRatio}(R, H)$$
-
-When all target words match, $\text{GOP} = 1.0$.
-
-### 5.3 Biomechanical Praat Phonation Formulations
-
-Acoustic stability is computed on voiced periodic frames ($F_0 \in [75, 500]\text{ Hz}$):
-
-- **Local Jitter (Pitch Instability)**:
-  $$\text{Jitter} = \frac{\frac{1}{N-1} \sum_{i=1}^{N-1} |T_i - T_{i+1}|}{\frac{1}{N} \sum_{i=1}^{N} T_i}$$
-  *Where $T_i$ is the duration of the $i$-th glottal pitch period.*
-
-- **Local Shimmer (Amplitude Instability)**:
-  $$\text{Shimmer} = \frac{\frac{1}{N-1} \sum_{i=1}^{N-1} |A_i - A_{i+1}|}{\frac{1}{N} \sum_{i=1}^{N} A_i}$$
-  *Where $A_i$ is the peak amplitude of the $i$-th glottal pulse.*
-
-- **Harmonics-to-Noise Ratio (HNR)**:
-  $$\text{HNR} = 10 \cdot \log_{10} \left( \frac{r_{AC}(T_0)}{1 - r_{AC}(T_0)} \right) \text{ dB}$$
-  *Where $r_{AC}(T_0)$ is the normalized autocorrelation at fundamental period $T_0$.*
-
-### 5.4 Multi-Modal Fluency Index (0 to 100)
-The continuous Fluency Index integrates all modalities into a clinically intuitive score:
+---
 
-$$\text{Fluency} = 100 \cdot \max\left(0, 1.0 - \left(0.40 \cdot \mathcal{L}_{\text{stutter}} + 0.45 \cdot \mathcal{L}_{\text{pron}} + 0.15 \cdot \mathcal{L}_{\text{artic}}\right)\right)$$
+## 4. Ablation & Component Contribution Framework
 
-Where:
-- $\mathcal{L}_{\text{stutter}} = \max\left(0, \frac{P(\text{stutter}) - 0.45}{0.55}\right)$
-- $\mathcal{L}_{\text{pron}} = 1.0 - \text{GOP}$
-- $\mathcal{L}_{\text{artic}} = \frac{\text{Severity}_{\text{Praat}}}{3.0}$
+| Model Configuration | Stutter Precision | Stutter Recall | Macro-F1 | Notes / Contribution |
+| :--- | :--- | :--- | :--- | :--- |
+| **Wav2Vec2 Base (Zero-Shot)** | 38.20% | 46.10% | 41.80% | High false-positive rate on natural pauses |
+| **Wav2Vec2 + UCLASS Only** | 44.21% | 41.50% | 57.35% | Severe class imbalance limits block detection |
+| **Wav2Vec2 + LoRA + Focal Loss** | 72.10% | 68.40% | 66.80% | Focal loss focuses on boundary transitions |
+| **Full Hybrid (Real + Synthetic)**| **85.05%** | **75.71%** | **71.47%** | Balanced lattice improves prolongation & block detection |
 
 ---
 
-## 6. Detailed Repository Map
-
-The codebase is organized into modular packages:
+## 5. Repository File Map
 
 ```
 speech-model/
 |-- ml/
 |   |-- model/
 |   |   |-- engine.py              # Singleton high-speed inference pipeline
-|   |   |-- infer.py               # Real LoRA model loader and probability extraction
+|   |   |-- infer.py               # LoRA model loader and probability extraction
 |   |   |-- pron_eval.py           # CTC ASR decoding, word alignment, 'r'/'s' flaw rules
-|   |   |-- fusion.py              # Multi-modal fusion, self-calibration, severity buckets
+|   |   |-- fusion.py              # Multi-modal fusion, uncertainty, self-calibration
 |   |   |-- stutter_trainer.py     # Wav2Vec2 + LoRA training script with Focal Loss
 |   |-- data/
 |   |   |-- lattice_synth.py       # DSP disfluency lattice synthesizer
@@ -294,6 +164,7 @@ speech-model/
 |   |   |-- precache_models.py     # Docker build pre-cache script
 |   |-- cli.py                     # Unified developer command-line interface
 |-- webapp.py                      # Streamlit clinical diagnostic user interface
+|-- app.py                         # Gradio interface for Hugging Face Spaces (ZeroGPU)
 |-- docs/
 |   |-- DATASETS_AND_MODEL_GUIDE.md # Plain-English guide to datasets and model design
 |   |-- DEPLOY_RENDER.md           # Step-by-step Render deployment documentation
@@ -304,12 +175,12 @@ speech-model/
 |-- requirements.txt               # Python package dependencies
 |-- Dockerfile                     # Production container configuration for Render
 |-- render.yaml                    # Render 1-Click deployment blueprint
-|-- README.md                      # Formal research documentation
+|-- README.md                      # Transparent research documentation
 ```
 
 ---
 
-## 7. Step-by-Step Local Setup & Execution Guide (PowerShell / Windows)
+## 6. Step-by-Step Local Setup & Execution Guide (PowerShell / Windows)
 
 The following PowerShell commands allow anyone to clone, set up, and test the entire framework locally on Windows:
 
@@ -374,6 +245,7 @@ res = engine.diagnose_audio(
 )
 print('Inference Latency:   ', res['latency_ms'], 'ms')
 print('Clinical Assessment: ', res['decision']['buckets']['overall'].upper())
+print('Confidence Level:    ', res['decision'].get('confidence', 'N/A'))
 print('Fluency Index:       ', res['decision']['fluency_100'], '/ 100')
 print('Decoded Text:        ', res['pronunciation']['asr_hypothesis'])
 "@
@@ -392,8 +264,6 @@ Once the web server starts, open your browser and navigate to:
 
 ### Alternative: Bash / Linux / macOS Commands
 
-For macOS and Linux environments, use standard bash commands:
-
 ```bash
 # Setup
 git clone https://github.com/notUbaid/speech-model.git