Reference

Repository map

Every file and folder, with its purpose and whether it is in version control.

Layout

.
|-- asr.py                    ASR wrapper (Whisper-family), optional denoising
|-- llm.py                    LLM wrapper (chat template, greedy generation)
|-- pipeline.py               SpeechPipeline + JSON CLI + load_config
|-- denoise.py                spectral-subtraction front end
|-- evaluate.py               WER/CER/RTF/F1 metrics + batch evaluation CLI
|-- prepare_data.py           folder/manifest -> evaluator JSON
|-- synthesize_corpus.py      TTS corpus generator (clean + noisy)
|-- plot_results.py           headless plots from evaluation outputs
|-- hallucination.py          correct / abstained / hallucinated classifier
|-- bootstrap.py              paired bootstrap intervals
|-- verify_task2.py           setup checks + mock end-to-end run
|-- config.yaml               baseline configuration
|-- config_denoised.yaml      same, with asr.denoise: true
|-- requirements.txt          dependency ranges
|-- README.md                 operating manual
|-- AGENTS.md                 repository workflow rules
|-- DraftTask1.md             original long-form Task 1 draft
|-- tests/                    30 offline unit tests (8 files)
|-- reports/                  papers: report (unified), task1, task2 (.tex/.md/.pdf)
|-- docs/                     this documentation site
|
|-- corpus_clean/  corpus_noisy/        generated audio + labels     [git-ignored]
|-- data/                               evaluator manifests          [git-ignored]
|-- outputs/                            evaluation, plots, verify    [git-ignored]
|-- .cache/huggingface/                 downloaded model weights     [git-ignored]
|-- tmp/                                scratch/diagnostics          [git-ignored]
|-- moshi.pdf  "qwen omni.pdf"          source papers (local copies) [git-ignored]

Source files

Path	Description	Docs
`asr.py`	`ASRWrapper`, `resolve_runtime`, `synchronize`	Reference
`llm.py`	`LLMWrapper`	Reference
`pipeline.py`	`SpeechPipeline`, `PipelineResult`, `load_config`, CLI	Reference
`denoise.py`	`spectral_subtract_denoise`	Extension
`evaluate.py`	Metric functions, paired evaluation, report writing, CLI	Metrics
`prepare_data.py`	Manifest builder	Dataset formats
`synthesize_corpus.py`	Corpus generator	Dataset
`plot_results.py`	Plots	Plots
`hallucination.py`	Fact-based classifier	Definition
`bootstrap.py`	Bootstrap CIs	Method
`verify_task2.py`	Verifier	Reference

Configuration and project files

Path	Description
`config.yaml`	Baseline models, decoding and paths. Reference.
`config_denoised.yaml`	Identical but `asr.denoise: true`.
`requirements.txt`	Dependency ranges, checked by `verify_task2.py`.
`README.md`	The repository's operating manual: running, data preparation, evaluation, plotting, verification, hallucination, bootstrap, extension.
`AGENTS.md`	Workflow rules: commit each completed logical step with concise Conventional Commits messages; run appropriate checks first; keep generated outputs, model caches, temporary dependencies and local reference documents out of version control.
`DraftTask1.md`	The original, longer Task 1 draft (with figure specifications and a verification checklist). The shorter `reports/task1.md` is the cleaned-up version.
`.gitignore`	Ignores bytecode, virtualenvs, caches, `outputs/`, `data/`, `tmp/`, `corpus_clean/`, `corpus_noisy/` and the local reference PDFs.

`tests/`

test_evaluate.py, test_pipeline.py, test_prepare_data.py, test_plot_results.py, test_verify_task2.py, test_denoise.py, test_hallucination.py, test_bootstrap.py. See Tests.

`reports/`

File	Description
`report.tex`, `report.pdf`	The single ACL-style paper (11 pages) covering both parts.
`task1.md`, `.tex`, `.pdf`	Standalone Task 1 write-up (13 pages), with the three TikZ diagrams.
`task2.md`, `.tex`, `.pdf`	Standalone Task 2 write-up (7 pages), with the plots and the model-compatibility story.

`docs/`

Path	Description
`*.html`	The pages of this site, content only.
`assets/style.css`	Theme (light and dark), layout, components.
`assets/app.js`	Builds the navigation, on-page contents, search, theme toggle and copy buttons. No libraries.
`assets/search-index.js`	Generated search index (`python docs/build_search_index.py`).
`assets/fonts/`	Inter variable font (Latin subset, SIL Open Font License 1.1), self-hosted so the site needs no network.
`assets/img/`	Three diagrams cropped from the paper and six result plots (copies of the ignored `outputs/plots`).
`assets/pdf/`	Copies of the three PDFs, so the site links work when `docs/` is served on its own.
`build_search_index.py`	Regenerates the search index from the pages' headings and text.

Generated, git-ignored folders

Path	Made by	Contents
`corpus_clean/`, `corpus_noisy/`	`synthesize_corpus.py`	129 x (`.wav`, `.txt`, `.response.txt`) each
`data/`	`prepare_data.py`	`test_clean.json`, `test_noisy.json` and metadata files
`outputs/evaluation/{clean,noisy_baseline,noisy_denoised}/`	`evaluate.py`	`report.json`, `samples.csv`, `failures.csv`, `wer_vs_quality.csv`
`outputs/evaluation/hallucination.json`	`hallucination.py`	Correct / abstained / hallucinated counts per condition and arm
`outputs/plots/<condition>/`	`plot_results.py`	`wer_vs_quality.png`, `latency_breakdown.png`
`outputs/verification/`	`verify_task2.py`	`verification.log`, `checks.json`, `summary.md`, `mock/`
`.cache/huggingface/`	Hugging Face downloads	Model weights (about 1 to 3 GB)