# local_files_only=True on a not-cached repo fails fast without network, proving
# our kwargs forward through to snapshot_download.
_BOGUS = "cjm-nonexistent-org/definitely-not-a-real-repo-xyz"
_raised = False
try:
snapshot_download_with_progress(_BOGUS, local_files_only=True)
except Exception:
_raised = True
assert _raised, "expected a local-cache-miss error with local_files_only=True"
# Passing a report_progress callback is accepted (the tqdm subclass builds cleanly);
# same fast-fail path, no crash constructing the reporting tqdm.
_calls = []
try:
snapshot_download_with_progress(
_BOGUS, local_files_only=True,
report_progress=lambda f, m: _calls.append((f, m)),
)
except Exception:
passSnapshot download with progress
Wrap
huggingface_hub.snapshot_download so per-file progress flows to the capability’s report_progress, defeating the substrate’s stall detector during downloads.
The download phase is where HF Hub capabilities spend their cold-start time, and it is silent enough to trip the substrate’s prefetch stall detector. This helper hooks snapshot_download’s tqdm_class so each progress tick calls report_progress(fraction, "downloading <file>"), advancing the (progress, message) tuple the substrate polls.
Wrap BOTH this download AND the subsequent from_pretrained(..., local_files_only=True) in one with self.heartbeat(...) block. The per-file tqdm callback is real progress but not a reliable stall-detector floor on its own (it can be sparse, and one large file reports no advance for a long stretch); the heartbeat is the floor and this helper’s download % layers on top when available.
Returns the local snapshot directory. LavaSR-style constructors that take a path can pass the returned Path to bypass their internal (progress-less) download.
snapshot_download_with_progress
def snapshot_download_with_progress(
repo_id:str, # HF Hub repo id, e.g. "mistralai/Voxtral-Mini-3B-2507"
report_progress:Optional=None, # Capability's report_progress(fraction, message)
cache_dir:Optional=None, # HF cache override (HFCacheConfig.cache_dir)
revision:Optional=None, # Git rev / tag / commit to pin
local_files_only:bool=False, # Use cached files only; no network
kwargs:VAR_KEYWORD
)->Path: # Local path to the downloaded snapshot
Download an HF Hub snapshot, streaming per-file progress to report_progress.
When report_progress is given, a tqdm_class subclass forwards each update as report_progress(downloaded / total, "downloading <file>"). When it is None, the default HF Hub progress bars are used unchanged.
Returns the local snapshot directory; subsequent from_pretrained calls with the same cache_dir + local_files_only=True hit the populated cache.
Adoption: the per-file tqdm callback is real progress but NOT a reliable stall-detector floor on its own (it can be sparse / silent on one large file). Wrap BOTH this call and the subsequent from_pretrained in a single with self.heartbeat(...) block so the substrate always sees the tuple advance.
Tests. (Network-free: local_files_only=True on an uncached repo fails fast.)