whisper-nvidia-cli 0.1.0

One-shot agent-native local NVIDIA GPU speech-to-text CLI powered by whisper.cpp
Documentation
//! Persisted model catalog. Official SHA-1 seeds are written once.

use std::path::Path;

use serde::{Deserialize, Serialize};

use crate::error::Error;
use crate::paths::AppPaths;

/// One catalog row. Digests are official SHA-1 (40 hex).
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct ModelEntry {
    /// Short model name accepted on argv.
    pub name: String,
    /// File name the weights are cached under.
    pub filename: String,
    /// Origin the weights are downloaded from.
    pub url: String,
    /// Expected size of the weights file, in bytes.
    pub size_bytes: u64,
    /// Official SHA-1 digest of the weights, 40 hex characters.
    pub sha1: String,
    /// Device memory the model needs to load, in bytes.
    pub vram_bytes: u64,
}

/// On-disk catalog.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct Catalog {
    /// Seed generation this file was written from.
    ///
    /// Absent in files written before reconciliation existed, which deserialize
    /// as 0 and are therefore always brought forward. Without it, a correction
    /// to the seeded facts reached only fresh installs: every machine that had
    /// already run the product kept the old row for ever, which is exactly how
    /// the wrong `size_bytes` would have survived being fixed.
    #[serde(default)]
    pub seed_version: u32,
    /// Every model row this installation knows about.
    pub models: Vec<ModelEntry>,
}

/// Current generation of the seeded facts.
///
/// Bump this whenever a measured value in `seeds` changes, so existing caches
/// adopt the correction on their next run.
pub const SEED_VERSION: u32 = 1;

impl Catalog {
    /// Official seeds. Digests come from the whisper.cpp model list; the byte
    /// counts were measured on 2026-08-18 with an HTTP HEAD against the
    /// published artefacts on huggingface.co.
    ///
    /// The counts had to be measured because the previous values were wrong for
    /// every single model, by 373 bytes on large-v3 and by 21 MB on small. That
    /// is not drift: `verify_file` rejects on size before it computes a digest,
    /// so `models download` could never complete for any model in the
    /// catalogue, and a model fetched by other means was reported absent
    /// because `is_present` compares the declared size too.
    ///
    /// The failure was invisible to the whole test suite because every download
    /// test exercises a refusal, and the broken gate runs after bytes land on
    /// disk. To re-measure:
    ///
    /// ```text
    /// curl -sIL https://huggingface.co/ggerganov/whisper.cpp/resolve/main/ggml-small.bin \
    ///   | rg -i '^x-linked-size:'
    /// ```
    ///
    /// Verified against the live origin on 2026-08-26: all five sizes and all
    /// five SHA-1 digests still match what is published, so the table below is
    /// current. The recipe itself did NOT survive that check, and it is fixed
    /// above.
    ///
    /// The old recipe read `content-length`, which `-L` makes ambiguous: the
    /// 302 that starts the chain carries its own `content-length: 1079` — the
    /// length of the redirect BODY — so the grep matched two lines and the
    /// first one was the wrong one. Anyone re-measuring with it would have
    /// written 1079 into this table for every model.
    ///
    /// Two more traps on this origin, both measured the same day:
    /// `x-linked-size` is the artefact's real size, while the CDN's `etag` on
    /// the 200 is a Xet hash and not a digest of the file. The upstream SHA-256
    /// lives in `x-linked-etag`; this product verifies the published SHA-1, and
    /// adding a second algorithm is explicitly out of MVP scope per the PRD.
    pub fn seeds(origin_base: &str) -> Self {
        let base = origin_base.trim_end_matches('/');
        Self {
            seed_version: SEED_VERSION,
            models: vec![
                entry(
                    "tiny",
                    "ggml-tiny.bin",
                    base,
                    77_691_713,
                    "bd577a113a864445d4c299885e0cb97d4ba92b5f",
                    400 * 1024 * 1024,
                ),
                entry(
                    "base",
                    "ggml-base.bin",
                    base,
                    147_951_465,
                    "465707469ff3a37a2b9b8d8f89f2f99de7299dac",
                    600 * 1024 * 1024,
                ),
                entry(
                    "small",
                    "ggml-small.bin",
                    base,
                    487_601_967,
                    "55356645c2b361a969dfd0ef2c5a50d530afd8d5",
                    1200 * 1024 * 1024,
                ),
                entry(
                    "medium",
                    "ggml-medium.bin",
                    base,
                    1_533_763_059,
                    "fd9727b6e1217c2f614f9b698455c4ffd82463b4",
                    2500 * 1024 * 1024,
                ),
                entry(
                    "large-v3",
                    "ggml-large-v3.bin",
                    base,
                    3_095_033_483,
                    "ad82bf6a9043ceed055076d0fd39f5f186ff8062",
                    3500 * 1024 * 1024,
                ),
            ],
        }
    }

    /// Load the catalog, bringing an older file forward to the current seeds.
    ///
    /// Reconciliation touches only the two fields that are facts about the
    /// published artefact — its byte count and its digest — and only for rows
    /// the seeds still know. Everything else is the operator's: a row they
    /// added stays, a `vram_bytes` they tuned stays, and a `url` they pointed
    /// at a mirror stays, because the origin is a documented knob.
    pub fn load_or_seed(paths: &AppPaths, origin_base: &str) -> Result<Self, Error> {
        let path = paths.catalog_file();
        if path.exists() {
            let raw = std::fs::read_to_string(&path)?;
            let mut disk: Self = toml::from_str(&raw).map_err(|e| Error::Config(e.to_string()))?;
            if disk.seed_version < SEED_VERSION {
                disk.reconcile_with_seeds(origin_base);
                // Best effort: a read-only cache still gets the corrected rows
                // in memory for this run, which is what the caller needs.
                let _ = disk.save(&path);
            }
            return Ok(disk);
        }
        let catalog = Self::seeds(origin_base);
        catalog.save(&path)?;
        Ok(catalog)
    }

    /// Adopt the measured facts from the current seeds, in place.
    fn reconcile_with_seeds(&mut self, origin_base: &str) {
        let seeds = Self::seeds(origin_base);
        for row in &mut self.models {
            let Some(seed) = seeds.models.iter().find(|s| s.name == row.name) else {
                continue;
            };
            row.size_bytes = seed.size_bytes;
            row.sha1 = seed.sha1.clone();
        }
        // Rows the seeds gained since this file was written.
        for seed in &seeds.models {
            if !self.models.iter().any(|r| r.name == seed.name) {
                self.models.push(seed.clone());
            }
        }
        self.seed_version = SEED_VERSION;
    }

    /// Persist the catalog.
    ///
    /// This used to hand-roll the temporary-plus-rename and skip
    /// `signal::register_temp`, which the config store next door did call. A
    /// forced exit during reconciliation therefore left `catalog.toml.tmp`
    /// behind, which is exactly the residue FR-039 says never happens.
    pub fn save(&self, path: &Path) -> Result<(), Error> {
        let body = toml::to_string_pretty(self).map_err(|e| Error::Config(e.to_string()))?;
        crate::paths::write_atomic(path, &body)
    }

    /// Lookup by name.
    pub fn get(&self, name: &str) -> Result<&ModelEntry, Error> {
        self.models
            .iter()
            .find(|m| m.name == name)
            .ok_or_else(|| Error::ModelNotFound {
                name: name.to_string(),
            })
    }
}

fn entry(
    name: &str,
    filename: &str,
    base: &str,
    size_bytes: u64,
    sha1: &str,
    vram_bytes: u64,
) -> ModelEntry {
    ModelEntry {
        name: name.into(),
        filename: filename.into(),
        url: format!("{base}/{filename}"),
        size_bytes,
        sha1: sha1.into(),
        vram_bytes,
    }
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn five_models_and_small_digest() {
        let c = Catalog::seeds(crate::config::DEFAULT_ORIGIN_BASE);
        assert_eq!(c.models.len(), 5);
        let small = c.get("small").unwrap();
        assert_eq!(small.sha1, "55356645c2b361a969dfd0ef2c5a50d530afd8d5");
        assert!(small.url.starts_with("https://"));
    }

    #[test]
    fn turbo_is_out_of_mvp() {
        let c = Catalog::seeds("https://example.invalid");
        assert!(c.get("large-v3-turbo").is_err());
    }
}