Files
Andrew Beveridge ☄️andClaude Opus 4.7 8c530f5ade feat: syllable-aware custom lyrics with validate-and-repair loop (#741)
## Summary

Enhances the Custom Lyrics LLM mode with syllable-count validation and
per-line repair, plus user-facing settings (`allow_reword`,
`allow_omit`, `fixed_line_count`, `strictness`) and a per-line preview
UI showing target/actual syllables and severity badges.

- **Backend**: New `GenerationSettings` model, validator computing
per-line `min_delta` against the existing `SyllablesMatchHandler`
engine, repair loop (max 3 iterations, plateau-aware on the full
`(violations, total_delta)` score tuple), proportional timing
redistribution for variable-line-count outputs, structured per-iteration
logging with worst-3-line breadcrumbs.
- **Frontend**: Collapsible `CustomLyricsSettings` panel (3 toggles +
5-button strictness segmented control with ARIA group semantics +
contradiction warning), `CustomLyricsPreview` with severity badges +
iterations badge + stop-reason banner, wired into existing
`CustomLyricsMode` modal. Snake-case API response shape
(`line_metadata`, `iterations_used`, `stop_reason`, `settings_applied`,
`new_segment_timing`).
- **i18n**: 33 new keys across 33 locales (auto-translated via Gemini
pipeline).
- **Eval harness**: `backend/eval/custom_lyrics/` with disk-backed
Gemini cache (record-and-replay), per-line + per-fixture + corpus
scorers, CLI runner (`make eval-custom-lyrics`), and 4 fixtures (Year 5
Stars from production + 3 handcrafted public-domain).
- **Production E2E**: Updated existing test for the new preview UI + 3
new tests for settings panel toggles.

## Risk / Deferred Validation

The eval harness is built and ready, but **Phase 8 baseline capture
(v1-ships criteria validation) was deferred** — we ship and test in
prod. If the Year-5-Stars fixture doesn't hit `pct_pass_at_2 >= 75%`
post-merge, the spec lists fallback paths (chunked generation, per-line
repair); the eval can be run anytime via `make eval-custom-lyrics`.

Repair-loop logging is structured and rich so any prod failure is
diagnosable from Cloud Logging without re-running locally — log
breadcrumbs include per-iteration violation count, score deltas, and the
worst 3 failing lines with their target/candidate text + syllable
arrays.

## Test plan

- [x] Backend unit tests: 77 passing
- [x] Frontend unit tests: 32 passing across CustomLyricsSettings,
CustomLyricsPreview, CustomLyricsMode, customLyrics API client,
segmentsFromLines
- [x] TypeScript compiles cleanly for the touched files
- [x] CodeRabbit local review run; real bugs in timing.py (median +
zero-syllable) and validator.py (segment-duration hardening) fixed
inline
- [ ] **Post-merge**: real Gemini run against Year-5-Stars production
job, check Cloud Logging for `custom_lyrics_repair_iter_complete`
events, verify `pct_pass_at_2` matches expectations
- [ ] **Post-merge**: run prod E2E suite once admin token is plumbed in
CI (or manually)

@coderabbitai ignore

🤖 Generated with [Claude Code](https://claude.com/claude-code)

---------

Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2026-05-02 23:26:09 -04:00
..