Repository navigation
feat(stt): manage speech models in a table with download, select and remove - #17624
Pearcekieser wants to merge 1 commit into
Conversation
cdeb2c1 to
a9a4d59
Compare
Design Review (Opus 5.5, fork) — ✅ PASSDesign-level review of Design-Verdict: PASS Nothing blocks. Users get back up to 1.6 GB without a shell command, and the delete takes only a catalog name, so a request can never turn into a filesystem path. Notes
[DESIGN-REVIEWED] fe272ff Description read[DESCRIPTION-READ] b5eafe111dfadf5d6534f034b561a09693c414a74eb1cebe6858dc5db787aa61 That sha256 names everything this verdict read: the PR description, plus the 1 evidence file(s) the workflow collected from it and handed this review. It covers that evidence because the media strip replaces every attachment URL with the same placeholder, so an edit swapping one attachment for another would leave the description's captured text identical while what this review judged changed. Recompute it with |
First Principles Review (Opus 5.5, fork) — ✅ PASSPremise-level review of First-Principles-Verdict: PASS Nothing blocks: the table, Remove and the deselected-model release each remove a harm the description names. The opt-in claim system on every transcription path costs more than the narrow race it closes. Notes
What this change shipsInventory (9 items) — 8 justifiedIntent: let a user see, download, select and remove local speech models from Settings instead of the data directory. ADDITION.
[FIRST-PRINCIPLES-REVIEWED] 72c0341 Description read[DESCRIPTION-READ] 6ed298968e524709ecf3376b8212a6e804968d98d9a0879e0d82e7bbcc18f1d0 That sha256 names the PR description this verdict read. Recompute it with |
UX Review (Opus 5.5, fork) — ✅ PASSUX-level review of UX-Verdict: PASS Nothing blocks. The screenshots show every new table state, but nobody has read them cold: this lane has no blind reader. Pushing the branch to this repository would get one. Notes
[UX-REVIEWED] fe272ff Description read[DESCRIPTION-READ] 14a14e5b9d21b13235fb7322a34d9980cce448c244839d51ef297617a0019a85 That sha256 names everything this verdict read: the PR description, plus the 22 evidence file(s) the workflow collected from it and handed this review. It covers that evidence because the media strip replaces every attachment URL with the same placeholder, so an edit swapping one attachment for another would leave the description's captured text identical while what this review judged changed. Recompute it with |
Opus 5.5 Review (fork) — ✅ no blocking findingsReviewed Review detailsNo findings. Notes:
[OPUS-REVIEWED] fe272ff |
GPT 6.1 Review (fork) — ✅ no blocking findingsReviewed Review detailsNo findings. |
|
span=ec7d7961be59
|
|
span=6b1de615f2e3
|
|
span=b265d3e80576
|
a9a4d59 to
fa3bd9c
Compare
|
span=12977fcca565
|
|
span=86e05a4c8cfc
|
|
span=9eebae47fd57
|
|
span=2c8aa6fc69d9
|
|
span=1e4cecfe0caf
|
fa3bd9c to
2865c06
Compare
|
Rebased onto main 09e4e0b as 90311b8 to clear a conflict in |
|
|
|
|
|
|
|
|
|
Rebased onto main 122005d as 0e59705 to clear another conflict in |
|
Rebased onto main 477c91a as fe90dfc to clear another conflict in |
|
Rebased onto main |
|
HOLD for human review (policy-sensitive), reviewed at 95176a0. Both r134 blockers are fixed. The spec paragraph now states the claim rule for new code that reads a model. The description now matches the code: an overrun build is refused by What still blocks:
AI findings judged non-blocking:
I read the source and CI; I did not run any PR code. — crew-pr-reviewer (r137) |
|
Rebased onto main |
|
Pushed |
|
Rebased onto main |
|
Rebased onto main |
|
HOLD at This head rebases What still blocks:
AI findings judged non-blocking:
I read the source and CI; I did not run any PR code. — crew-pr-reviewer (r145) |
|
Rebased onto main Two files needed changes:
Lint, line cap, comment-history, 1,678 backend tests, tsc, i18n check, 892 Settings, STT and destructiveConfirm vitest cases and the bundle gate (1,021 chunks within budget) pass locally. |
|
Pushed
Await Fast Gate, Coverage Gate and PR Readiness were red on |
|
Rebased onto main GPT 6.1 Review was incomplete on Lint, black, line cap, comment-history, the flake ratchet, 1,754 backend tests, tsc, i18n check, 890 vitest cases and the bundle gate (1,021 chunks within budget) pass locally. |
|
HOLD at fe272ff, reserved for human review. This head rebases 35bb7bc (our r145) onto main. The range-diff changes only tests and i18n context: the flake-ratchet K19 fixes in What still blocks:
AI findings judged non-blocking:
Our earlier change request (54f4231) can be dismissed once a maintainer approves. I read the source and CI; I did not run any PR code. — crew-pr-reviewer (r146) |
|
🤖 Kiro Crew Auto-Pipeline [operator: buluoray#ce473fca]: Reviewed at fe272ff. Both points from the last request-changes are fixed on this head. The spec now states the claim rule for new model readers, and the description now matches the The delete path holds up. The name only ever selects a catalog entry. Non-blocking follow-ups:
AI lane notes on this head, none blocking: Design's single-refusal idea would block removal during a live dictation session. First Principles item 6 overlaps the planned #20713. UX's three notes are cosmetic. Opus's "is downloading" wording during verification is retryable. The linked issue is tier T3 and this adds a route that deletes files on disk, so I am leaving the approval to a maintainer. |
|
All three follow-ups are fixed in a local commit,
|
|
This PR is ready for maintainer review. It replaces the speech-model dropdown in Voice settings with a table that can download, select and remove models. It adds Where review stands on
Two decisions need a maintainer:
The branch conflicts with main again, in an import list in |
Problem / Motivation
Goal: In Settings > Voice > Speech-to-Text, a user can see every local speech model's size and state, and download, select or remove each one from one place.
The Model row is a dropdown. It shows the state of the selected model only, and a Download button appears only when that model is missing. A user cannot see which other models are on disk, cannot fetch a model without first selecting it, and cannot delete one. Models run from 78 MB (
tiny) to 1.6 GB (large-v3-turbo), so a user who tried the large one has to delete files under<data home>/models/whisper/by hand to get the space back. A transfer of an unselected model is also invisible: the panel shows progress only for the selected model.Why it matters
The space cost is real and the only remedy today is a shell command in the gateway's data directory. Without a list of what is installed, a user also cannot tell which models the next selection will download.
Not a goal
What changed (motivation → approach → change)
A user can now manage the speech models from Settings instead of the data directory, and the panel says what each model costs and whether it is on disk.
The new route
DELETE /api/stt/models/{name}insrc/kiro_crew/dashboard/handlers/core.pylooks the name up in the catalog, so an alias, a filename or a traversal is a 404 and never becomes a path.ModelStore.removeinsrc/kiro_crew/stt/models.pydeletes onlymodels_dir() / model.filename; every catalog filename is one plain component, which a test pins, so the delete cannot name another directory. A symlink at that path is unlinked as a link, never followed. It refuses with 409 and a code instead of changing anything else: the configured model, aliases included (stt_model_selected); a model that work still reads (stt_model_in_use): a live voice session keeps the model it started with after the user selects another, and a batch transcription fixes its model before the upload and transcode awaits. A removed file would make that work re-download it, or fail offline and lose the audio. Both take aModelClaimfromsrc/kiro_crew/stt/models.py(LocalSessionuntilfinishhas decoded orcancelruns,POST /api/stt/transcribefor the whole request,_transcribe_localfor the Slack path, and a meetings audio import from its config snapshot until the transcript is back, so a split import keeps its model across every segment; the transcribe route, the meetings import, Slack voice memos and channel attachments all take it throughtranscribe.local_model_claim, which claims only for thelocalprovider), andModelStore.removerefuses a claimed model in the same synchronous step as the unlink. The route also checks before releasing anything. Claims sit in a weak set, so a holder dropped without releasing cannot pin a model; the model resident in the recogniser (stt_model_in_use), matched on the residency key's full path and never the file name, because a custom model may sit in a subfolder under a catalog file name (sub/ggml-small.bin) and is then the user's own selected model; the model a load is reading:WhisperEngine.ensure_loadedclaims its own model before its first await, so the claim check refuses it (stt_model_in_use), and a native build that outlived its timeout, which keeps reading after that call returns, is refused by its path (stt_model_loading, matched onWhisperEngine.building_path); a load or download of another model does not block; and the model being downloaded (stt_model_downloading). A deselected model is often still resident, because only the idle sweep unloads it (600 s by default). Removing it is the table's main use, so the route first releases it with the newWhisperEngine.release_if_resident, under the load and decode locks the way idle eviction takes them, and re-reads the selection after that await;stt_model_in_usethen answers only a model something put back. While any load is running the route skips that release, because it would wait on the load lock for a whole first download; the model then answers a retryablestt_model_in_use, and #20713 plans to drop the release step.ModelStore.removerefuses on the store's transfer record (ModelStore._transfers), not on the display status, and a secondensurefor a model whose transfer is still running, for example after its caller was cancelled, joins that transfer underasyncio.shieldinstead of starting a second writer; the record clears when the transfer completes. No await sits between the remaining checks and the unlink, so no load or download can start in the gap.SttModelTableinwebsite/src/pages/settings/SttModelTable.tsxmarks the row the status endpoint resolves the configured model to, so an oldmediumconfig showslarge-v3-turboas Selected; the download prompt and the CPU-slowness warning follow the same resolved name, so amediumconfig on a CPU-only build now gets the warninglarge-v3-turboalways had. Every row has a state badge: Installed, Not downloaded, or progress. The old dropdown showed no line for an installed selected model, and the table keeps that, adding no reassurance line under it; the per-row Installed state is what lets a user see what is on disk, which is the point of the table. Each refusal code maps to a sentence that says what to do, shown under the row it was for. When the selected model is not on disk yet, the download prompt is a row under that model, not a line below the table. A failed download says in plain words that it stopped and to choose Download now again; the gateway's reason rides in the agent hand-off. The row button reads Select, the same word as the Selected badge. The selected row never offers Remove and adds no standing line explaining why; trying to remove the configured model through the API returns thestt_model_selectedsentence. At most two buttons per row. The table uses the sharedtable-stripedclass, and each model's rows carry that model's stripe, so a failure or refusal row stays on its model's band instead of shifting the stripes below it. Belowsmeach row stacks its parts (name and size, then the status badges, then the buttons) and the column header is hidden: at 320px the pane is 288px wide, and in German the "Nicht heruntergeladen" badge beside a "Jetzt herunterladen" button pushed the buttons 74px past the edge. The new client call isapi.sttDeleteModelinwebsite/src/api/client/voice.ts.website/scripts/settingsExtract.tsindexes the table as thestt.modelsetting, so the settings registry and its deep link are unchanged.VoicePanelinwebsite/src/pages/settings/VoicePanel.tsxnow loadsSttSettingswithlazy()behind aSuspenseskeleton. The table pushed theSettingsPagechunk to 503.9 KB against the Bundle Size Gate's 500 KB default. With the split,SettingsPagebuilds at 492.25 kB and the speech-to-text card is its own 40.57 kB chunk, fetched only when the Voice tab opens. Settings deep links still reachstt.*controls becauseuseSettingHighlightwaits for late elements.Backwards compatibility
Compatible:
GET /api/stt/status,POST /api/stt/prepareand thestt.modelconfig key are unchanged; the new route only adds a way to delete a file the user could already delete by hand.Removes nothing: the Model dropdown is replaced by a table that writes the same
stt.modelkey, keeps the label, hint andconfigKey, and the registry entry forvoice.modelis byte-identical. The retiredmodel_optioncatalog key had no other reader.Tests
test/test_stt_model_delete.py, 68 tests: a model claimed by a batch transcription, or claimed during the release, is refusedstt_model_in_use, andModelStore.removerefuses a claimed model itself; the transcribe route and the local batch path hold the claim for the whole request and drop it after; a deselected model a live session still uses is refusedstt_model_in_usewithout being released, and removed once that session is cancelled; a session started during the release also refuses it; a finished or garbage-collected session does not pin its model; a deselected model still resident (the idle sweep has not run) is released and removed; one something put back during the release is refusedstt_model_in_use; one selected again during the release is refusedstt_model_selected; a non-resident model releases nothing;release_if_residentdrops only the named file and waits for a running decode; a selected, resident custom model atsub/ggml-small.binis neither released nor touched whensmallis removed, andrelease_if_residentleaves it loaded; removal of an installed unselected model and only its file; a second removal is a no-op; refusals for the configured model, a configured alias, the resident model, a model a load is reading (through its claim) or an overrun build is still reading (by path), and the downloading model; a load of another model does not block removal; a download of another model does not block; exact catalog names only, with alias, filename, traversal and case variants all 404 and untouched; an app claim is 403; the route is registered;WhisperEngine.loadingandWhisperEngine.building_pathfor an idle engine, a held load lock and a load past its timeout; a pending prewarm refuses removal of its model and a cancelled load releases its claim; the store resets a stalereadystatus and removes a symlink without its target; every catalog path is one file directly in the models directory.test/test_meetings_audio_import.py, 3 new tests: a local-provider import holds its model claim through the duration probe and the split, for a split that succeeds and one that fails, and drops it after; a cloud-provider import claims nothing. Both local cases fail without the route's claim.website/src/test/SttSettings.modelTable.test.tsx, 17 tests: the shared striped-table class, and a notice row on its model's stripe with the stripes below it unshifted; every row's state; an alias selects the resolved row; no Remove on the selected row and no standing hint; the selected row offers Download when its model is missing; a failed download renders on its own full-width row with a plain sentence and keeps Download; a refusal renders under its row; at most two buttons per row; Select writesstt.model; Download fetches without selecting; one transfer holds every Download; Remove confirms with the size, deletes, and re-reads status; cancel deletes nothing; each 409 code shows its sentence.SttSettings.modelDownloadDisclosure,SttSettings.surface,SttSettings.decoder.ApiClient.refactor.surfacepins the new client key;destructiveConfirmrecords why the two confirm keys need no quoting.test_a_resident_model_is_not_released_during_another_loadfails withnot engine.loadingremoved from the release guard incore_stt_status.py. While any load holds the load lock, a resident model is refusedstt_model_in_useat once instead of waiting on that lock for a whole download.Catalog keys under
pages.settings.sttSettings.model_*are translated in all 12 shipped languages inwebsite/src/i18n/locales/, withen-XA.jsonregenerated and a translator note for the Select button inwebsite/src/i18n/en.context.json.src/kiro_crew/docs/configuration.md,docs/system-specs/modules/stt-streaming.md,docs/system-specs/modules/learn-cron-dashboard.mdanddocs/feature-map/README.mddescribe the route and the table.Manual verification
End to end in a disposable pod on an earlier head (before the deselected-model release, which the unit tests above cover), with sparse files of the exact catalog sizes planted under the pod's
models/whisper(no real model downloaded),stt.model=base:DELETE /api/stt/models/smallremoved: true, file gone, status showssmallnot presentremoved: falseDELETE /api/stt/models/basestt_model_selected, file keptmedium,ggml-small.bin,..%2Fconfig.jsonNot exercised in the pod:
stt_model_in_use,stt_model_loadingandstt_model_downloading, which need a real whisper load or a live transfer; the unit tests above cover them. A browser pass against the pod stopped at its first-run onboarding, so the screenshots come fromwebsite/capture/voice-settings.tsx(shippedSttSettings, API stubbed) in Chromium.Screenshots / video
The Custom model row, added by the rebase onto #14918. These frames come from main's
website/scripts/capture-stt-custom-model.mjs, which serves the real built SPA from this head with the API stubbed. The Custom row is always the last row of the table. It has no size, and while it is not selected its only action is Select, with no Download or Remove.Custom selected while its file is missing from the speech models folder. The row has no actions, the status reads "Model file problem" and the reason shows under the file name field:
Custom selected with its file in place, shown as Selected and Installed:
The frames come from
website/capture/voice-settings.tsx(shippedSttSettingswith the API stubbed). The wide frames are from an earlier head, before the table was striped; this head changes nothing else in the wide layout. The 320px, 390px and German 820px frames are from this head and show the stripes. The two refused-Remove frames are from this head too:website/capture/voice-settings.tsxtakes&refuse=stt_model_in_useto stub the 409, and they show the current text, "Voice input is still using this model. Try again when it finishes."At 320px in German, before and after (the GPT narrow-viewport finding). A check in the capture script measured every table button ending at 394px in a 320px window before, and inside the window after:
Before, from an earlier head, with the model name broken at its hyphens and the button label wrapping:
After, on this head:
German 320px idle, before and after, and German at 820px
Before, from an earlier head:
After, on this head:
Before, dark (main's dropdown):
After, dark:
After, a transfer of an unselected model running (main showed nothing for it):
After, Remove confirmation:
After, a refused Remove (stubbed 409
stt_model_in_use), on a row under that model, with the Ask the agent hand-off:After, a failed download on its row, at 390px:
After, the selected model not yet downloaded, with the download prompt on the row under it (German, 820px):
Failed download at full width, narrow table, light theme, and main during the same transfer
Related Issues
Closes #17602
Review items deferred from this PR, one issue each:
release_if_resident, now that claims protect running work.stt_model_loading, and rewords its "few seconds" sentence.Checklist
feat|fix|docs|style|refactor|perf|test|chore|ci|build|revert: ...)Contribution License Agreement
Contributions are accepted under the project's Apache-2.0 license; see the Licensing section of CONTRIBUTING.md.