Skip to content

armgit / Handy

Public Imported from GitHub
0

A free, open source, and extensible speech-to-text application that works completely offline.

10.3 KB
Raw Blame
//! Model capability probing — the seam between Handy's model UI and "what can
//! this GGUF actually do".
//!
//! Capabilities are canonical *in the GGUF itself*: transcribe-cpp reads them
//! from the model's metadata at load time, and the runtime reconciles the
//! registry against that ground truth once a model is loaded — streaming,
//! translation, language detection, and the supported-language set (see
//! [`crate::managers::model::ModelManager::set_runtime_capabilities`]). This
//! module covers the other half — reading the same values from the GGUF header
//! *before* download, so search/listing can show them honestly ahead of a load.
//!
//! Everything goes through the [`CapabilityProber`] trait. Today the only
//! implementation, [`GgufHeaderProber`], parses a local GGUF's header directly
//! via [`crate::managers::gguf_meta`]. If transcribe-cpp later exposes a
//! metadata-only probe (covering parakeet-style *inferred* streaming and legacy
//! `.bin`), a `TranscribeCppProber` can be dropped in behind this same trait
//! without touching any caller.

use serde::{Deserialize, Serialize};
use specta::Type;
use std::path::Path;

use super::gguf_meta::{self, GgufError, GgufMetadata};

/// Architecture strings transcribe-cpp can load — the `.name` of each arch under
/// its `src/arch/`, which is exactly the value stored in `general.architecture`.
/// Keep this in sync with transcribe-cpp; an arch absent here still parses, it's
/// just surfaced as [`Compatibility::MaybeIncompatible`] rather than promised.
pub const KNOWN_ARCHES: &[&str] = &[
    "whisper",
    "parakeet",
    "qwen3_asr",
    "voxtral",
    "voxtral_realtime",
    "cohere",
    "cohere_asr",
    "canary",
    "canary_qwen",
    "moonshine",
    "moonshine_streaming",
    "sensevoice",
    "gigaam",
    "granite",
    "granite_speech",
    "granite_nar",
    "granite_speech_nar",
    "funasr_nano",
    "granite5_ctc",
    "medasr",
    "moss",
    "sortformer",
];

// GGUF metadata keys transcribe-cpp writes for ASR models.
const KEY_ARCH: &str = "general.architecture";
const KEY_NAME: &str = "general.name";
const KEY_VARIANT: &str = "stt.variant";
const KEY_LANGUAGES: &str = "general.languages";
const KEY_CAP_STREAMING: &str = "stt.capability.streaming";
const KEY_CAP_TRANSLATE: &str = "stt.capability.translate";
const KEY_CAP_LANG_DETECT: &str = "stt.capability.lang_detect";
const PROBE_KEYS: &[&str] = &[
    KEY_ARCH,
    KEY_NAME,
    KEY_VARIANT,
    KEY_LANGUAGES,
    KEY_CAP_STREAMING,
    KEY_CAP_TRANSLATE,
    KEY_CAP_LANG_DETECT,
];

/// How confident we are that Handy can run a given model, judged from its GGUF
/// header alone (pre-download).
#[derive(Debug, Clone, Copy, PartialEq, Eq, Default, Serialize, Deserialize, Type)]
#[serde(rename_all = "snake_case")]
pub enum Compatibility {
    /// Parsed as GGUF and the architecture is one transcribe-cpp ships.
    Compatible,
    /// Parsed as GGUF, but the architecture is unknown to us — might work.
    MaybeIncompatible,
    /// Not a GGUF we can use (bad magic, unsupported version, malformed).
    Unsupported,
    /// We haven't looked yet.
    #[default]
    Unknown,
}

/// Capabilities surfaced in the model UI. Every field is optional on purpose:
/// `None` means "not known yet" — a community model whose header omits the key,
/// or a field (parakeet streaming) the header parse can't determine. The UI
/// renders that honestly as unknown, and the runtime fills it in for real once
/// the model is loaded.
#[derive(Debug, Clone, Default, Serialize, Deserialize, Type)]
pub struct CapabilityProbe {
    pub verdict: Compatibility,
    /// `general.name`, when present.
    pub display_name: Option<String>,
    /// `general.architecture`, when present.
    pub architecture: Option<String>,
    /// `stt.variant`, when present.
    pub variant: Option<String>,
    /// `general.languages` — transcribable language codes.
    pub languages: Option<Vec<String>>,
    /// `stt.capability.streaming` — native live-streaming support.
    pub supports_streaming: Option<bool>,
    /// `stt.capability.translate` — translation to English.
    pub supports_translation: Option<bool>,
    /// `stt.capability.lang_detect` — automatic language detection.
    pub supports_language_detect: Option<bool>,
}

impl CapabilityProbe {
    /// A probe for something we definitively could not read as a usable GGUF.
    pub fn unsupported() -> Self {
        CapabilityProbe {
            verdict: Compatibility::Unsupported,
            ..Default::default()
        }
    }

    /// Build a probe from parsed GGUF metadata.
    ///
    /// Streaming for the parakeet family is *inferred* by transcribe-cpp's
    /// native loader from encoder hparams rather than a flat bool, so when the
    /// explicit `stt.capability.streaming` key is absent we leave it `None`
    /// (unknown) and let post-load reconciliation settle it — we never guess.
    pub fn from_metadata(meta: &GgufMetadata) -> Self {
        let architecture = meta.get_str(KEY_ARCH).map(str::to_string);
        let verdict = match architecture.as_deref() {
            Some(arch) if KNOWN_ARCHES.contains(&arch) => Compatibility::Compatible,
            _ => Compatibility::MaybeIncompatible,
        };
        CapabilityProbe {
            verdict,
            display_name: meta.get_str(KEY_NAME).map(str::to_string),
            architecture,
            variant: meta.get_str(KEY_VARIANT).map(str::to_string),
            languages: meta.get_string_array(KEY_LANGUAGES),
            supports_streaming: meta.get_bool(KEY_CAP_STREAMING),
            supports_translation: meta.get_bool(KEY_CAP_TRANSLATE),
            supports_language_detect: meta.get_bool(KEY_CAP_LANG_DETECT),
        }
    }
}

/// Reads model capabilities from a local GGUF's header. See the module docs for
/// the substitution story (`GgufHeaderProber` now, a transcribe-cpp-backed
/// prober later).
pub trait CapabilityProber: Send + Sync {
    /// Probe a GGUF already on disk (custom-dir + HF-cache scans, post-download).
    fn probe_file(&self, path: &Path) -> CapabilityProbe;
}

/// Pure-Rust prober backed by [`crate::managers::gguf_meta`]. The default and,
/// for the foreseeable future, only implementation.
pub struct GgufHeaderProber;

impl CapabilityProber for GgufHeaderProber {
    fn probe_file(&self, path: &Path) -> CapabilityProbe {
        match read_header_metadata(path) {
            Ok(meta) => CapabilityProbe::from_metadata(&meta),
            Err(_) => CapabilityProbe::unsupported(),
        }
    }
}

/// Read just enough of `path` to parse its GGUF metadata header, without ever
/// loading the (potentially multi-GB) tensor data. Grows the prefix
/// geometrically if a header is unusually large.
fn read_header_metadata(path: &Path) -> Result<GgufMetadata, GgufError> {
    // The KV metadata block precedes the tensor-info table. Shipping ASR models
    // place all of it well within the first 64 KiB, so that's the common-case
    // read. Older / community GGUFs may carry it deeper, so the loop grows the
    // prefix geometrically (jumping straight to the size the parser reports it
    // needs) up to a hard cap.
    const INITIAL_PREFIX: usize = 64 << 10; // 64 KiB
    const MAX_PREFIX: usize = 16 << 20; // 16 MiB

    /// Read up to `size` bytes from the start of `path`, tolerating short reads.
    fn read_prefix(path: &Path, size: usize) -> std::io::Result<Vec<u8>> {
        use std::io::Read;
        let mut file = std::fs::File::open(path)?;
        let mut buf = vec![0u8; size];
        let mut filled = 0;
        while filled < buf.len() {
            match file.read(&mut buf[filled..]) {
                Ok(0) => break,
                Ok(n) => filled += n,
                Err(ref e) if e.kind() == std::io::ErrorKind::Interrupted => continue,
                Err(e) => return Err(e),
            }
        }
        buf.truncate(filled);
        Ok(buf)
    }

    let mut size = INITIAL_PREFIX;
    loop {
        let buf = read_prefix(path, size).map_err(|_| GgufError::Malformed("cannot read file"))?;
        let read_len = buf.len();
        match gguf_meta::parse_header(&buf, PROBE_KEYS) {
            Ok(meta) => return Ok(meta),
            Err(GgufError::Truncated { needed }) => {
                if read_len < size {
                    // Hit EOF and still truncated → file shorter than its header.
                    return Err(GgufError::Malformed("file shorter than its header"));
                }
                let next = needed.max(size.saturating_mul(2)).min(MAX_PREFIX);
                if next <= size {
                    return Err(GgufError::Truncated { needed });
                }
                size = next;
            }
            Err(e) => return Err(e),
        }
    }
}

#[cfg(test)]
mod tests {
    use super::super::gguf_meta::{GgufMetadata, GgufValue};
    use super::*;
    use std::collections::HashMap;

    fn meta_with(kvs: Vec<(&str, GgufValue)>) -> GgufMetadata {
        let mut kv = HashMap::new();
        for (k, v) in kvs {
            kv.insert(k.to_string(), v);
        }
        GgufMetadata { kv }
    }

    #[test]
    fn known_arch_is_compatible_and_reads_caps() {
        let meta = meta_with(vec![
            ("general.architecture", GgufValue::String("parakeet".into())),
            (
                "general.name",
                GgufValue::String("Parakeet Unified EN 0.6B".into()),
            ),
            ("stt.capability.streaming", GgufValue::Bool(true)),
            (
                "general.languages",
                GgufValue::Array(vec![GgufValue::String("en".into())]),
            ),
        ]);
        let probe = CapabilityProbe::from_metadata(&meta);
        assert_eq!(probe.verdict, Compatibility::Compatible);
        assert_eq!(
            probe.display_name.as_deref(),
            Some("Parakeet Unified EN 0.6B")
        );
        assert_eq!(probe.architecture.as_deref(), Some("parakeet"));
        assert_eq!(probe.supports_streaming, Some(true));
        assert_eq!(probe.languages, Some(vec!["en".to_string()]));
        // Absent key stays unknown rather than defaulting to false.
        assert_eq!(probe.supports_translation, None);
    }

    #[test]
    fn unknown_arch_is_maybe_incompatible() {
        let meta = meta_with(vec![(
            "general.architecture",
            GgufValue::String("llama".into()),
        )]);
        assert_eq!(
            CapabilityProbe::from_metadata(&meta).verdict,
            Compatibility::MaybeIncompatible
        );
    }
}