voxora_hf/lib.rs
1#![forbid(unsafe_code)]
2#![warn(missing_docs)]
3
4//! Hugging Face model source for voxora.
5//!
6//! This crate implements [`voxora_traits::ModelSource`] against the
7//! public Hugging Face Hub REST API. It turns a model identifier such
8//! as `"Qwen/Qwen3-ASR-0.6B"` into a [`voxora_traits::ModelDir`] on
9//! disk, downloading only what is missing and verifying integrity
10//! when the repo ships a sidecar checksum.
11//!
12//! # Example
13//!
14//! ```no_run
15//! use voxora_traits::{ModelSource, ResolveOptions};
16//! use voxora_hf::HuggingFaceSource;
17//!
18//! # async fn run() -> Result<(), voxora_traits::AsrError> {
19//! let source = HuggingFaceSource::new()?;
20//! let dir = source
21//! .resolve("Qwen/Qwen3-ASR-0.6B", &ResolveOptions::default())
22//! .await?;
23//! println!("model cached at {}", dir.path.display());
24//! # Ok(()) }
25//! ```
26//!
27//! # Caching
28//!
29//! Files land under
30//! `$XDG_CACHE_HOME/voxora/models/huggingface/<org>/<name>/<revision>/`
31//! with a `.complete` marker file written **last**. A second call to
32//! [`voxora_traits::ModelSource::resolve`] for the same `(model_id, revision)`
33//! returns immediately when the marker is present.
34//!
35//! # Auth
36//!
37//! Tokens are resolved in this order, the first non-empty wins:
38//!
39//! 1. [`voxora_traits::ResolveOptions::token`]
40//! 2. `HF_TOKEN` environment variable
41//! 3. `HUGGING_FACE_HUB_TOKEN` environment variable (legacy alias)
42//! 4. Anonymous
43//!
44//! # Quantization
45//!
46//! The crate detects the dtype from the model's `config.json`
47//! (`torch_dtype` field) and from the file name for GGUF repositories
48//! (e.g. `ggml-base.bin.q4_K_M`). The caller's
49//! [`voxora_traits::QuantizationPreference`] is consulted only when the
50//! repo offers a choice.
51//!
52//! # Configuration cascade
53//!
54//! By default this crate pulls in `voxora-config` and uses it to
55//! resolve the cache directory and the HF token. Disable the default
56//! `config` feature (`default-features = false`) to fall back to the
57//! inline legacy cascade — only `VOXORA_CACHE_DIR`, `HF_TOKEN`, and
58//! `HUGGING_FACE_HUB_TOKEN` are read, with no `voxora.toml` support.
59//! See `voxora_config::VoxoraConfig` for the full cascade.
60
61mod api;
62pub mod cache;
63mod capabilities;
64mod client;
65pub mod error;
66mod known_models;
67mod quantization;
68mod source;
69
70pub use error::HfError;
71pub use source::{HuggingFaceSource, HuggingFaceSourceBuilder};