feat: backend-agnostic HF download helper with byte progress

[wavekat-eason]

Summary

Adds a backend-agnostic helper for streaming HuggingFace files with byte-level progress, so any current or future backend whose model weights live on HF Hub can drive a download UI without reimplementing the protocol.

Structure:

• New wavekat_asr::download module (gated behind a new download Cargo feature):
  • pub struct DownloadProgress { file, file_index, file_count, bytes_done, bytes_total }
  • pub fn download_files_with_progress<F>(repo_id: &str, files: &[&str], dest_dir: &Path, on_progress: F) -> Result<(), AsrError> where F: FnMut(DownloadProgress)
• sherpa-onnx backend keeps a small convenience wrapper:
  • pub fn backends::sherpa_onnx::download_preset_with_progress(preset: ModelPreset, dest_dir, F) -> Result<(), AsrError> — 4-line shim over the generic helper
  • pub fn ModelPreset::files(&self) -> Vec<&'static str> — HF file list in download order
• Feature wiring: download = ["dep:hf-hub"], sherpa-onnx = ["dep:sherpa-onnx", "download"]. The download feature is independently usable, so a future Whisper or Qwen3-ASR backend can do whisper = ["dep:whisper-rs", "download"] without pulling in sherpa-onnx.

Why

A consumer driving a model-download UI needs byte progress to render a real progress bar. Without this helper they'd either shell out to hf-hub's CLI or reimplement HuggingFace's download protocol. The first version put the helper inside backends::sherpa_onnx, but the mechanics (hf-hub call, progress bridge, copy into dest_dir) are entirely generic — only the input shape (which files does this preset need?) is backend-specific. Splitting at that seam means a future Whisper / Qwen3-ASR local backend lands a thin wrapper, not a re-implementation.

Behavior

• Streams byte-level progress per file (file_index/file_count, bytes_done, bytes_total).
• Copies each file from hf-hub's cache blob into dest_dir (not just rename), so the cache stays consistent and the caller gets a dest_dir they can move / delete independently.
• Synthesizes a final 100% event in finish() if hf-hub's last update short-counted, so a UI progress bar can't stick at 99%.

Implementation note

hf-hub's Progress trait takes ownership of the reporter per download_with_progress call, so the bridge (CallbackProgress<'_, F>) borrows &mut F and is rebuilt per iteration. That lets one FnMut(DownloadProgress) closure span all files in a batch without Rc<RefCell<…>> or restricting the callback to Fn. Trade-off: the closure can't be Send across threads — fine for the synchronous download path.

Tests

All without network access:

• download::tests::callback_progress_reports_init_update_and_finish — init + 2 updates = 3 emissions reaching the user closure; finish() adds no extra event when bytes already match.
• download::tests::callback_progress_finish_synthesizes_completion — when hf-hub's last update short-counts, finish() emits the synthetic 100% event.
• backends::sherpa_onnx::tests::preset_files_transducer_includes_joiner — BILINGUAL_ZH_EN.files() returns 4 names in encoder/decoder/joiner/tokens order.
• backends::sherpa_onnx::tests::preset_files_paraformer_omits_joiner — PARAFORMER_ZH.files() returns 3 names with no joiner.

Verified locally on the branch:

• cargo fmt --all -- --check
• cargo clippy --workspace --all-features -- -D warnings
• cargo test --workspace --features sherpa-onnx — 7 unit tests + 1 doc-test pass
• cargo doc --no-deps -p wavekat-asr --all-features
• cargo check --workspace (default features), cargo check --workspace --features download (alone), and cargo check --workspace --features sherpa-onnx all build — confirming the download feature is independently usable and the cfg gates are correct.

Follow-up

Once this lands (#8 is already merged), release-plz will open a chore: release v0.0.5 PR; merging it publishes 0.0.5 to crates.io. Downstream consumers can then call download_preset_with_progress (for sherpa-onnx) or download_files_with_progress (generic) from their own model-download flow.

🤖 Generated with Claude Code