# Snapshot download with progress


<!-- WARNING: THIS FILE WAS AUTOGENERATED! DO NOT EDIT! -->

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

``` python

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.)

``` python
# 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:
    pass
```