feat(backend): send the campaign vocabulary as hotwords, on a switch (#577) #578

Merged

claude-bot merged 2 commits from feat/577-asr-hotwords into main 2026-09-09 10:03:07 +00:00

Conversation 0 Commits 2 Files changed 15 +1039 -20

claude-bot commented 2026-09-09 08:58:53 +00:00

Contributor

Copy link

Closes #577.

What. The bundled WhisperX server accepts the campaign vocabulary either as an initial_prompt (what the app has always sent) or as hotwords, faster-whisper's purpose-built term bias. This adds VocabularyStyle.HOTWORDS and a worker switch, QB_ASR_VOCABULARY_STYLE=initial_prompt|hotwords|none, defaulting to initial_prompt so nothing changes for anyone who does not set it. hotwords falls back to the prompt, with a warning, on a server that does not declare it; none is the control arm and skips the wiki query entirely. The style actually used is stamped on the summarisation run (vocabulary_style, migration 4f5a6b7c8d9e, nullable, not backfilled) and surfaced on the run API, so a comparison can be read back later.

Verified against the live server, not assumed. With an invented fixture clip that says "Stillbrook": no vocabulary → Stillbrook; hotwords="Stilbroque, …" → Stilbrooke; a misspelt field name → Stillbrook (so the field is read, not silently dropped); and both fields together → the prompt wins and hotwords are ignored. That last point is why the request tests assert the other field is absent, not merely that the right one is present: sending both would be a comparison that never runs.

Design notes. caps.vocabulary holds the effective style after reconciling the switch with /health, so the request field, the log line, the capability panel and the stored value cannot disagree. The style is captured right after resolve_asr_vocabulary, before per-span failures can invalidate the capability cache. The switch is scoped to the bundled adapter: the OpenAI-compatible path has only prompt on the wire. One accepted gap: with none set, the capability panel's remedy text still suggests updating the server; documented in OPERATIONS.md rather than fixed, since fixing it means carrying the raw declaration separately.

Tests: 21 new in test_asr_hotwords.py; full backend suite 2,985 passed; migration upgraded, downgraded and re-upgraded on a real database.

🤖 Generated with Claude Code

Closes #577. **What.** The bundled WhisperX server accepts the campaign vocabulary either as an `initial_prompt` (what the app has always sent) or as `hotwords`, faster-whisper's purpose-built term bias. This adds `VocabularyStyle.HOTWORDS` and a worker switch, `QB_ASR_VOCABULARY_STYLE=initial_prompt|hotwords|none`, defaulting to `initial_prompt` so nothing changes for anyone who does not set it. `hotwords` falls back to the prompt, with a warning, on a server that does not declare it; `none` is the control arm and skips the wiki query entirely. The style actually used is stamped on the summarisation run (`vocabulary_style`, migration `4f5a6b7c8d9e`, nullable, not backfilled) and surfaced on the run API, so a comparison can be read back later. **Verified against the live server, not assumed.** With an invented fixture clip that says "Stillbrook": no vocabulary → *Stillbrook*; `hotwords="Stilbroque, …"` → *Stilbrooke*; a misspelt field name → *Stillbrook* (so the field is read, not silently dropped); and both fields together → the prompt wins and hotwords are ignored. That last point is why the request tests assert the other field is *absent*, not merely that the right one is present: sending both would be a comparison that never runs. **Design notes.** `caps.vocabulary` holds the effective style after reconciling the switch with `/health`, so the request field, the log line, the capability panel and the stored value cannot disagree. The style is captured right after `resolve_asr_vocabulary`, before per-span failures can invalidate the capability cache. The switch is scoped to the bundled adapter: the OpenAI-compatible path has only `prompt` on the wire. One accepted gap: with `none` set, the capability panel's remedy text still suggests updating the server; documented in OPERATIONS.md rather than fixed, since fixing it means carrying the raw declaration separately. Tests: 21 new in `test_asr_hotwords.py`; full backend suite 2,985 passed; migration upgraded, downgraded and re-upgraded on a real database. 🤖 Generated with [Claude Code](https://claude.com/claude-code)

claude-bot added 1 commit 2026-09-09 08:58:53 +00:00

feat(backend): send the campaign vocabulary as hotwords, on a switch (#577) ... 33d3d40e2f

The bundled WhisperX server takes the campaign's proper nouns two ways.
`initial_prompt` is a sentence the decoder is told it has just transcribed,
so the model conditions on the style of the list as well as its contents;
`hotwords` is faster-whisper's dedicated bias for exactly this job. Verified
against the live server that they are alternatives rather than layers — both
occupy the same slot in the prompt, and a request carrying both is served as
though only the initial prompt were there — so exactly one is ever sent.

Which is better is an empirical question about one deployment's audio, its
model and its campaign's names, and nothing in here can answer it. So this
is a switch plus a record of which arm each run was on, not a decision:

- `QB_ASR_VOCABULARY_STYLE` — `initial_prompt` (default), `hotwords`, `none`.
  Unset makes byte-identical requests to every release before this one, even
  though the current server declares both mechanisms. Validated at boot,
  because a typo would otherwise be silent: the pipeline keeps working and
  every run of the comparison lands on the default arm.
- `hotwords` against a server that does not declare it falls back to the
  prompt and warns on each capability probe, rather than quietly running the
  comparison on the arm the operator was trying to leave.
- `none` is the control arm and is genuinely free — the wiki is not queried,
  because nothing would read the answer.
- New nullable `summarisation_runs.vocabulary_style` (migration
  `4f5a6b7c8d9e`, raw DDL, no CHECK or enum since the style set belongs to
  the provider layer), surfaced as `vocabulary_style` on the summarisation-run
  responses. NULL is "not recorded" — a run predating the column, or a
  re-summarisation reading someone else's transcript. Captured before the
  first request rather than after transcription, because a failed span drops
  the capability cache and would otherwise stamp a prompt-biased run "none".

The switch reaches the bundled adapter only; a managed provider's vocabulary
is whatever its own wire shape offers.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>

claude-bot scheduled this pull request to auto merge when all checks succeed 2026-09-09 08:59:01 +00:00

rbrooks added 1 commit 2026-09-09 09:46:35 +00:00

style: format the vocabulary_style migration with the ruff version CI pins (#577) ... 0be6d2d356

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>

claude-bot merged commit 5ef4bec4fd into main 2026-09-09 10:03:07 +00:00

claude-bot referenced this pull request from a commit 2026-09-09 10:03:08 +00:00

Merge PR #578: feat(backend): send the campaign vocabulary as hotwords, on a switch (#577)

claude-bot deleted branch feat/577-asr-hotwords 2026-09-09 10:03:08 +00:00

Sign in to join this conversation.

Reviewers

No reviewers

Labels

Clear labels   

backend

Issue related to the backend

  

bot

Issue related to the bot

  

bug

Something is not working

  

duplicate

This issue or pull request already exists

  

enhancement

New feature

  

frontend

Issue related to the frontend

  

help wanted

Need some help

  

invalid

Something is wrong

  

question

More information is needed

  

recording

Issue related to the recording system

  

security

Security hardening / vulnerability work

  

wontfix

This won't be fixed

No labels

backend

bot

bug

duplicate

enhancement

frontend

help wanted

invalid

question

recording

security

wontfix

Milestone

Clear milestone

No items

No milestone

Projects

Clear projects

No items

No project

Assignees

Clear assignees

No assignees

2 participants

Notifications

Subscribe

Due date

The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set

Reference

rbrooks/Quest-Board!578

No description provided.