Lumotia/docs/architecture-map/05-core-storage-hotkey-build/core-model-registry.md

name, type, slice, last_verified

name	type	slice	last_verified
Core model registry	architecture-map-page	05-core-storage-hotkey-build	2026/05/09

Core model registry

Where you are: Architecture map → Core, Storage, Hotkey, Build → Core model registry

Plain English summary. The static catalogue of every speech-to-text model Lumotia ships or knows how to download. One Parakeet ONNX model and six Whisper GGML variants, each with pinned Hugging Face revisions and SHA256 digests so a downloaded file can be verified bit-for-bit against the registry. Pure data — the recommendation scoring lives in core-recommendation.md.

At a glance

• File: crates/core/src/model_registry.rs (247 LOC).
• External deps: standard library only (LazyLock).
• Public surface: Engine, SpeedTier, AccuracyTier, LanguageSupport, ModelFile, ModelEntry, all_models, find_model.
• Consumers: slice 2 model commands, the model manager, the recommendation engine (core-recommendation.md), the runtime-capabilities banner, the frontend model picker.

What's in here

Enums — crates/core/src/model_registry.rs:7-36

pub enum Engine          { Whisper, Parakeet, Moonshine }
pub enum SpeedTier       { Instant, Fast, Moderate, Slow }
pub enum AccuracyTier    { Excellent, Great, Good }
pub enum LanguageSupport { EnglishOnly, Multilingual(u16) }

Moonshine is reserved (no live entries today). LanguageSupport::Multilingual(u16) carries the count of supported languages but only the variant is used in scoring.

ModelFile — crates/core/src/model_registry.rs:39

pub struct ModelFile {
    pub filename: &'static str,
    pub url: &'static str,
    pub size: Megabytes,
    pub sha256: &'static str,  // hex, length 64
}

Every URL pins a specific Hugging Face revision SHA. The registry's test (model_registry.rs:222-246) asserts that no URL contains /resolve/main/ and that every digest is exactly 64 hex characters.

ModelEntry — crates/core/src/model_registry.rs:50

pub struct ModelEntry {
    pub id: ModelId,
    pub engine: Engine,
    pub display_name: &'static str,
    pub disk_size: Megabytes,
    pub ram_required: Megabytes,
    pub speed_tier: SpeedTier,
    pub accuracy_tier: AccuracyTier,
    pub languages: LanguageSupport,
    pub files: Vec<ModelFile>,
    pub description: &'static str,
}

ALL_MODELS — crates/core/src/model_registry.rs:63

A LazyLock<Vec<ModelEntry>>. Seven entries:

ID	Engine	Disk	RAM	Speed	Accuracy	Notes
parakeet-ctc-0.6b-int8	Parakeet	650 MB	700 MB	Instant	Great	Four ONNX shards. English only.
whisper-tiny-en	Whisper	75 MB	390 MB	Fast	Good	Bundled with the app.
whisper-base-en	Whisper	142 MB	500 MB	Fast	Good	Sweet spot for low-RAM.
whisper-small-en	Whisper	466 MB	1024 MB	Moderate	Great	Accuracy-first.
whisper-distil-small-en	Whisper	336 MB	900 MB	Fast	Great	Distilled, ~6× faster than small.
whisper-medium-en	Whisper	1500 MB	2600 MB	Slow	Excellent	Best Whisper accuracy.
whisper-distil-large-v3	Whisper	1550 MB	2800 MB	Moderate	Excellent	Near large-v3 accuracy.

All entries are English-only at present. Multilingual variants would slot into languages cleanly.

Public functions

pub fn all_models() -> &'static [ModelEntry];           // model_registry.rs:208
pub fn find_model(id: &ModelId) -> Option<&'static ModelEntry>;  // model_registry.rs:213

Both return references into the LazyLock. No allocation.

Data flow / contract

• Pure data. Lookups are read-only.
• The Parakeet entry's four files are fetched by the model downloader as a directory of <model_id>/ siblings (see core-paths.md). Whisper entries are single GGML files.
• The description field is user-facing copy. British-English spelling enforced.
• SHA256 verification happens in the model downloader (slice 3), not here.

Tests

crates/core/src/model_registry.rs:217-246:

• every_model_file_has_sha256_and_pinned_url — guard against accidental drift. SHA must be 64 hex chars; URL must not contain /resolve/main/.

Watch-outs

• Hugging Face revisions can be force-pushed. The pinned revision SHAs in the URLs are content addresses on HF's git LFS, but a maintainer with admin rights can in theory rewrite history. The local SHA256 verification at download time catches this. There is no automated CI check that re-fetches and verifies; verification happens lazily on user-facing downloads.
• description is &'static str. No i18n. If we localise the model picker we will need a key plus a separate string table.
• Adding a new model requires a recompile. No runtime registry override path. Conscious choice — keeps the surface area small and the SHA256 invariants meaningful.
• Moonshine is in the enum but no entries. Compiler does not complain because the enum is non_exhaustive-shaped via match arms inside scoring (see core-recommendation.md). When a Moonshine entry lands, the scoring path needs an explicit accelerator branch.

See also

• Public types and enums (Megabytes, ModelId)
• Recommendation scoring
• App paths (speech_model_dir)
• Slice 3 model manager