# margotmassonresearch/linguatest architecture

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

- Interactive diagram: https://gitdiagram.com/margotmassonresearch/linguatest
- Repository: https://github.com/margotmassonresearch/linguatest

## Overview

LinguaTest generates controlled synthetic accent-like speech and evaluates ASR robustness. Its principal workflow selects clean reference sentences, chooses phoneme substitutions from an accent profile, synthesizes variants, transcribes them, and aligns outputs for error analysis. The graph also preserves profile construction, supported recognizers, and evaluation/visualization capabilities. The README and excerpts establish the main orchestration and several internal calls; links involving unsampled modules are included only where the README documents them, and some implementation details remain unverified.

Main entry points: [`automatic_speech_recognition/asr_from_name.py`](https://github.com/margotmassonresearch/linguatest/blob/main/automatic_speech_recognition/asr_from_name.py) (Recognizer selection), [`linguatest.py`](https://github.com/margotmassonresearch/linguatest/blob/main/linguatest.py) (Pipeline runner), [`sentence_selection_module.py`](https://github.com/margotmassonresearch/linguatest/blob/main/sentence_selection_module.py) (Clean sentence selection), [`evaluation/weighted_alignment.py`](https://github.com/margotmassonresearch/linguatest/blob/main/evaluation/weighted_alignment.py) (Weighted alignment)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_pipeline["Test generation"]
  node_orchestrator["Pipeline runner<br/>[linguatest.py]"]
  node_sentence["Clean sentence selection"]
  node_phone_select["Phoneme selection"]
  node_variant_gen["Variant generation"]
  node_synthesis["Speech synthesis<br/>[azure_synthesis.py]"]
end

subgraph group_phonetics["Phonetic processing"]
  node_profile["Accent profile builder<br/>[build_profile.py]"]
  node_phonemizer["Phoneme conversion<br/>[phonemizer.py]"]
  node_preprocess["Phoneme preprocessing<br/>[preprocessing.py]"]
end

subgraph group_recognition["Speech recognition"]
  node_asr_select["Recognizer selection<br/>[asr_from_name.py]"]
  node_wav2vec["Wav2Vec2 recognizer<br/>[wav2vec2.py]"]
  node_wav2vec_phone["Wav2Vec2 phonemes<br/>[wav2vec2phoneme.py]"]
  node_whisper["Whisper recognizer<br/>[whisper.py]"]
  node_speecht5["SpeechT5 recognizer<br/>[speecht5.py]"]
end

subgraph group_analysis["Evaluation and analysis"]
  node_assessment["Robustness assessment"]
  node_df_eval["Dataframe evaluation<br/>[df_evaluation.py]"]
  node_alignment["Weighted alignment"]
  node_weighted["Weighted error scoring<br/>[weighted_jiwer.py]"]
  node_confusion["Phoneme confusion analysis"]
  node_visual["Analysis visualization<br/>[visualisation.py]"]
end

node_user(("Framework user"))
node_azure{{"Azure TTS"}}

node_user -->|"runs pipeline"| node_orchestrator
node_orchestrator -->|"selects sentences"| node_sentence
node_orchestrator -->|"selects phonemes"| node_phone_select
node_orchestrator -->|"generates variants"| node_variant_gen
node_orchestrator -->|"runs assessment"| node_assessment
node_sentence -->|"phonemizes text"| node_phonemizer
node_sentence -->|"synthesizes baseline"| node_synthesis
node_sentence -->|"chooses recognizer"| node_asr_select
node_sentence -->|"evaluates baseline"| node_df_eval
node_profile -->|"builds from errors"| node_confusion
node_variant_gen -.->|"synthesizes variants"| node_synthesis
node_synthesis -->|"requests speech"| node_azure
node_assessment -.->|"runs recognizer"| node_asr_select
node_assessment -.->|"aligns output"| node_alignment
node_asr_select -->|"dispatches to"| node_wav2vec
node_asr_select -->|"dispatches to"| node_wav2vec_phone
node_asr_select -->|"dispatches to"| node_whisper
node_asr_select -->|"dispatches to"| node_speecht5
node_df_eval -.->|"aligns transcripts"| node_alignment
node_alignment -->|"preprocesses phones"| node_preprocess
node_alignment -->|"scores phone errors"| node_weighted
node_profile -->|"transcribes profile data"| node_wav2vec_phone
node_visual -.->|"visualizes analysis"| node_confusion

click node_orchestrator "https://github.com/margotmassonresearch/linguatest/blob/main/linguatest.py"
click node_sentence "https://github.com/margotmassonresearch/linguatest/blob/main/sentence_selection_module.py"
click node_phone_select "https://github.com/margotmassonresearch/linguatest/blob/main/phoneme_selection_module.py"
click node_variant_gen "https://github.com/margotmassonresearch/linguatest/blob/main/test_utterances_generation_module.py"
click node_profile "https://github.com/margotmassonresearch/linguatest/blob/main/synthesis/build_profile.py"
click node_phonemizer "https://github.com/margotmassonresearch/linguatest/blob/main/phonemes_processing/phonemizer.py"
click node_preprocess "https://github.com/margotmassonresearch/linguatest/blob/main/phonemes_processing/preprocessing.py"
click node_synthesis "https://github.com/margotmassonresearch/linguatest/blob/main/synthesis/azure_synthesis.py"
click node_assessment "https://github.com/margotmassonresearch/linguatest/blob/main/robustness_assessment.py"
click node_asr_select "https://github.com/margotmassonresearch/linguatest/blob/main/automatic_speech_recognition/asr_from_name.py"
click node_wav2vec "https://github.com/margotmassonresearch/linguatest/blob/main/automatic_speech_recognition/wav2vec2.py"
click node_wav2vec_phone "https://github.com/margotmassonresearch/linguatest/blob/main/automatic_speech_recognition/wav2vec2phoneme.py"
click node_whisper "https://github.com/margotmassonresearch/linguatest/blob/main/automatic_speech_recognition/whisper.py"
click node_speecht5 "https://github.com/margotmassonresearch/linguatest/blob/main/automatic_speech_recognition/speecht5.py"
click node_df_eval "https://github.com/margotmassonresearch/linguatest/blob/main/evaluation/df_evaluation.py"
click node_alignment "https://github.com/margotmassonresearch/linguatest/blob/main/evaluation/weighted_alignment.py"
click node_weighted "https://github.com/margotmassonresearch/linguatest/blob/main/evaluation/weighted_jiwer.py"
click node_confusion "https://github.com/margotmassonresearch/linguatest/blob/main/evaluation/confusion_matrix.py"
click node_visual "https://github.com/margotmassonresearch/linguatest/blob/main/evaluation/visualisation.py"

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_orchestrator,node_sentence,node_phone_select,node_variant_gen,node_synthesis,node_user toneBlue
class node_profile,node_phonemizer,node_preprocess toneAmber
class node_asr_select,node_wav2vec,node_wav2vec_phone,node_whisper,node_speecht5 toneMint
class node_assessment,node_df_eval,node_alignment,node_weighted,node_confusion,node_visual toneRose
class node_azure toneIndigo
```

## Components

### Test generation

- [Pipeline runner](https://github.com/margotmassonresearch/linguatest/blob/main/linguatest.py): `linguatest.py`
- [Clean sentence selection](https://github.com/margotmassonresearch/linguatest/blob/main/sentence_selection_module.py): `sentence_selection_module.py`
- [Phoneme selection](https://github.com/margotmassonresearch/linguatest/blob/main/phoneme_selection_module.py): `phoneme_selection_module.py`
- [Variant generation](https://github.com/margotmassonresearch/linguatest/blob/main/test_utterances_generation_module.py): `test_utterances_generation_module.py`
- [Speech synthesis](https://github.com/margotmassonresearch/linguatest/blob/main/synthesis/azure_synthesis.py): `synthesis/azure_synthesis.py`

### Phonetic processing

- [Accent profile builder](https://github.com/margotmassonresearch/linguatest/blob/main/synthesis/build_profile.py): `synthesis/build_profile.py`
- [Phoneme conversion](https://github.com/margotmassonresearch/linguatest/blob/main/phonemes_processing/phonemizer.py): `phonemes_processing/phonemizer.py`
- [Phoneme preprocessing](https://github.com/margotmassonresearch/linguatest/blob/main/phonemes_processing/preprocessing.py): `phonemes_processing/preprocessing.py`

### Speech recognition

- [Recognizer selection](https://github.com/margotmassonresearch/linguatest/blob/main/automatic_speech_recognition/asr_from_name.py): `automatic_speech_recognition/asr_from_name.py`
- [Wav2Vec2 recognizer](https://github.com/margotmassonresearch/linguatest/blob/main/automatic_speech_recognition/wav2vec2.py): `automatic_speech_recognition/wav2vec2.py`
- [Wav2Vec2 phonemes](https://github.com/margotmassonresearch/linguatest/blob/main/automatic_speech_recognition/wav2vec2phoneme.py): `automatic_speech_recognition/wav2vec2phoneme.py`
- [Whisper recognizer](https://github.com/margotmassonresearch/linguatest/blob/main/automatic_speech_recognition/whisper.py): `automatic_speech_recognition/whisper.py`
- [SpeechT5 recognizer](https://github.com/margotmassonresearch/linguatest/blob/main/automatic_speech_recognition/speecht5.py): `automatic_speech_recognition/speecht5.py`

### Evaluation and analysis

- [Robustness assessment](https://github.com/margotmassonresearch/linguatest/blob/main/robustness_assessment.py): `robustness_assessment.py`
- [Dataframe evaluation](https://github.com/margotmassonresearch/linguatest/blob/main/evaluation/df_evaluation.py): `evaluation/df_evaluation.py`
- [Weighted alignment](https://github.com/margotmassonresearch/linguatest/blob/main/evaluation/weighted_alignment.py): `evaluation/weighted_alignment.py`
- [Weighted error scoring](https://github.com/margotmassonresearch/linguatest/blob/main/evaluation/weighted_jiwer.py): `evaluation/weighted_jiwer.py`
- [Phoneme confusion analysis](https://github.com/margotmassonresearch/linguatest/blob/main/evaluation/confusion_matrix.py): `evaluation/confusion_matrix.py`
- [Analysis visualization](https://github.com/margotmassonresearch/linguatest/blob/main/evaluation/visualisation.py): `evaluation/visualisation.py`

### Other components

- **Framework user**
- **Azure TTS**

## Connections

- Framework user → Pipeline runner: runs pipeline (evidence: `README.md`)
- Pipeline runner → Clean sentence selection: selects sentences (evidence: `linguatest.py`)
- Pipeline runner → Phoneme selection: selects phonemes (evidence: `linguatest.py`)
- Pipeline runner → Variant generation: generates variants (evidence: `linguatest.py`)
- Pipeline runner → Robustness assessment: runs assessment (evidence: `linguatest.py`)
- Clean sentence selection → Phoneme conversion: phonemizes text (evidence: `sentence_selection_module.py`)
- Clean sentence selection → Speech synthesis: synthesizes baseline (evidence: `sentence_selection_module.py`)
- Clean sentence selection → Recognizer selection: chooses recognizer (evidence: `sentence_selection_module.py`)
- Clean sentence selection → Dataframe evaluation: evaluates baseline (evidence: `sentence_selection_module.py`)
- Accent profile builder → Phoneme confusion analysis: builds from errors (evidence: `synthesis/build_profile.py`)
- Variant generation → Speech synthesis: synthesizes variants
- Speech synthesis → Azure TTS: requests speech (evidence: `synthesis/azure_synthesis.py`)
- Robustness assessment → Recognizer selection: runs recognizer (evidence: `README.md`)
- Robustness assessment → Weighted alignment: aligns output (evidence: `README.md`)
- Recognizer selection → Wav2Vec2 recognizer: dispatches to (evidence: `automatic_speech_recognition/asr_from_name.py`)
- Recognizer selection → Wav2Vec2 phonemes: dispatches to (evidence: `automatic_speech_recognition/asr_from_name.py`)
- Recognizer selection → Whisper recognizer: dispatches to (evidence: `automatic_speech_recognition/asr_from_name.py`)
- Recognizer selection → SpeechT5 recognizer: dispatches to (evidence: `automatic_speech_recognition/asr_from_name.py`)
- Dataframe evaluation → Weighted alignment: aligns transcripts
- Weighted alignment → Phoneme preprocessing: preprocesses phones (evidence: `evaluation/weighted_alignment.py`)
- Weighted alignment → Weighted error scoring: scores phone errors (evidence: `evaluation/weighted_alignment.py`)
- Accent profile builder → Wav2Vec2 phonemes: transcribes profile data (evidence: `synthesis/build_profile.py`)
- Analysis visualization → Phoneme confusion analysis: visualizes analysis
