ADR-225: TTS sample generation stage

[jodavis-claude]

Work item

ADR-225 — Implement the TTS sample generation stage (TtsSampleGenerator) and its DVC entry-point, converting Manifest[TextSample] into Manifest[AudioSample] by synthesizing speech via edge_tts with per-sample voice and speech-rate variation.

Changes

• New ml/pipeline/speech/__init__.py — package marker for the new speech subpackage
• New ml/pipeline/speech/tts_stage.py — TtsProvider protocol; TtsSampleGenerator(ModifierStage[TextSample, AudioSample]) with _get_applied_values, _derive_id, and _generate_output; EdgeTtsProvider concrete implementation that streams MP3 from edge_tts, converts to WAV via soundfile, and retries up to 3 times with exponential back-off
• New ml/pipeline/stages/speech_03_generate_samples.py — DVC entry-point: fetches and filters the en-US female voice list, loads params, constructs the stage, and drives asyncio.run(stage.transform(...))
• Modified ml/pipeline/stages/params.py — added GenerateSamplesParams dataclass (speech_rate_min, speech_rate_max) and wired it into PipelineParams.load() from stages.generate_speech_samples
• Modified ml/params.yaml — added stages.generate_speech_samples section with default speech_rate_min: -10 / speech_rate_max: 20
• Modified ml/dvc.yaml — added speech_03_generate_samples stage with persist: true on the output directory (required by ModifierStage seed-storage contract)
• New ml/test/pipeline/speech/__init__.py — test package marker
• New ml/test/pipeline/speech/test_tts_stage.py — 25 unit tests covering applied-values keys/types, _derive_id format, TTS provider call arguments, AudioSample.transcript correctness, rate-string formatting, and skip-path behaviour
• Modified ml/test/pipeline/stages/test_params.py — updated _VALID_DATA fixture and added 3 tests for GenerateSamplesParams loading

Design decisions

MP3 → WAV conversion via soundfile. edge_tts streams raw MP3 bytes; soundfile 0.13.1 (already installed) reads MP3 natively from a BytesIO buffer. EdgeTtsProvider decodes to a numpy array and re-encodes as PCM_16 WAV — no additional runtime dependency required.

speech_rate stored as raw int, rate string assembled at synthesis time. Keeping +5% out of applied_values means the content hash is stable even if the formatting convention changes; only the semantic value matters for skip-unchanged detection.

Voice list filtered in the entry-point, not in the stage. TtsSampleGenerator accepts a plain list[str], making it trivially testable with a two-element stub list without any network calls.

[github-actions]

Test Results

401 tests  ±0   401 ✅ ±0   2m 20s ⏱️ +2s
  5 suites ±0     0 💤 ±0 
  5 files   ±0     0 ❌ ±0 

Results for commit 2a33c51. ± Comparison against base commit 3008969.

♻️ This comment has been updated with latest results.

[jodavis-claude]

ADR-225 TTS Stage — First-pass review

All exit criteria are met: TtsProvider protocol, TtsSampleGenerator with correct _derive_id/_get_applied_values/_generate_output, EdgeTtsProvider with exponential back-off retry, entry-point voice filtering, 25 unit tests covering applied-value types, rate string formatting, skip path, and transcript/label invariants. Build and tests pass. No correctness, security, or performance issues found.

Issues

Priority 4

• .claude/settings.json (line 7): Unrelated change (clearing extraKnownMarketplaces) bundled into this PR. Should be separated.
• Missing ml/pipeline/speech/_doc_speech.md: ml/pipeline/speech/ is a new package. CONTRIBUTING.md: "When new subsystems are added, they should include a documentation file." The spec (_spec_OopPipeline.md) is pre-implementation and cannot serve this role. A _doc_*.md covering the speech subsystem's design intent (TtsProvider abstraction, EdgeTtsProvider retry contract, relationship to ModifierStage) should be added before this merges.

Priority 5 (style, non-blocking)

• tts_stage.py line 91: Multi-line docstring on EdgeTtsProvider. CLAUDE.md: one short line max; remove or collapse.
• speech_03_generate_samples.py line 1: 10-line module docstring with usage block. Same policy; remove or collapse to one line.

[jodavis-claude]

Sign-off review — all prior issues resolved, no new issues found.

Prior threads (all resolved):

• [P4] .claude/settings.json: extraKnownMarketplaces cleared accidentally — reverted in 05abd7b, marketplace entry restored. ✓ Resolved.
• [P5] tts_stage.py EdgeTtsProvider multi-line docstring — removed in 5608fbd. ✓ Resolved.
• [P5] speech_03_generate_samples.py 10-line module docstring — removed in 07d468e. ✓ Resolved.

New file scan (4 modified files: .claude/settings.json, tts_stage.py, speech_03_generate_samples.py, _doc_speech.md):

• No new Priority 1–4 issues found. The _doc_speech.md addition (commit 2c156c3) covers the required design decisions per CONTRIBUTING.md.

Outcome: approved — ready for human review.

[jodavis]

@copilot fix the test failure in this branch. It's probably a missing dependency in requirements.txt. Verify that the build passes with no warnings or errors and that all tests pass when you are done.

[Copilot]

@copilot fix the test failure in this branch. It's probably a missing dependency in requirements.txt. Verify that the build passes with no warnings or errors and that all tests pass when you are done.

Fixed in the latest commit. soundfile and edge-tts were missing from ml/requirements.txt — added soundfile>=0.13.1 and edge-tts>=6.1.9. All 177 Python tests pass locally.