Crate voxora_hf 

Hugging Face model source for voxora.

This crate implements voxora_traits::ModelSource against the public Hugging Face Hub REST API. It turns a model identifier such as "Qwen/Qwen3-ASR-0.6B" into a voxora_traits::ModelDir on disk, downloading only what is missing and verifying integrity when the repo ships a sidecar checksum.

Example

use voxora_traits::{ModelSource, ResolveOptions};
use voxora_hf::HuggingFaceSource;

let source = HuggingFaceSource::new()?;
let dir = source
    .resolve("Qwen/Qwen3-ASR-0.6B", &ResolveOptions::default())
    .await?;
println!("model cached at {}", dir.path.display());

Caching

Files land under $XDG_CACHE_HOME/voxora/models/huggingface/<org>/<name>/<revision>/ with a .complete marker file written last. A second call to voxora_traits::ModelSource::resolve for the same (model_id, revision) returns immediately when the marker is present.

Auth

Tokens are resolved in this order, the first non-empty wins:

1. voxora_traits::ResolveOptions::token
2. HF_TOKEN environment variable
3. HUGGING_FACE_HUB_TOKEN environment variable (legacy alias)
4. Anonymous

Quantization

The crate detects the dtype from the model’s config.json (torch_dtype field) and from the file name for GGUF repositories (e.g. ggml-base.bin.q4_K_M). The caller’s voxora_traits::QuantizationPreference is consulted only when the repo offers a choice.

Configuration cascade

By default this crate pulls in voxora-config and uses it to resolve the cache directory and the HF token. Disable the default config feature (default-features = false) to fall back to the inline legacy cascade — only VOXORA_CACHE_DIR, HF_TOKEN, and HUGGING_FACE_HUB_TOKEN are read, with no voxora.toml support. See voxora_config::VoxoraConfig for the full cascade.

Re-exports

pub use error::HfError;

Modules

cache

Filesystem layout for the on-disk model cache.

error

Error type used inside voxora-hf.

Structs

HuggingFaceSource

Hugging Face implementation of voxora_traits::ModelSource.

HuggingFaceSourceBuilder

Builder for HuggingFaceSource.