Model Utils

Generic download, verification, and cache helpers for model artifacts.

The helpers stream remote artifacts under a size limit, verify SHA-256 metadata, and publish persistent entries atomically under a lock. Model-family-specific catalogues and resolution policies belong in their own feature modules.

download_verified_bytes(spec, cancellation=None)

Download and verify one artifact into memory.

The download is aborted once it exceeds spec.max_size_bytes, or DEFAULT_MAX_DOWNLOAD_BYTES when the spec sets no limit.

Parameters:

Name	Type	Description	Default
spec	ModelWeight	Immutable URL, digest, and size-limit metadata.	required
cancellation	Event | None	Cooperative cancellation signal.	None

Returns:

Name	Type	Description
bytes	bytes	Verified artifact payload.

Raises:

Type	Description
InterruptedError	If cancellation is requested during the download.
ValueError	If the artifact exceeds its size limit or SHA-256 does not match spec.
OSError	If the HTTP request or response stream fails.

ensure_cached_weights(spec, cache_dir, *, namespace='models', cancellation=None)

Resolve a verified persistent cache entry under a per-artifact lock.

namespace keeps cache entries for different model families separate.

Parameters:

Name	Type	Description	Default
spec	ModelWeight	Immutable artifact metadata used for verification.	required
cache_dir	str | Path	Root directory for persistent artifacts.	required
namespace	str	Family namespace beneath cache_dir.	'models'
cancellation	Event | None	Cooperative cancellation signal.	None

Returns:

Name	Type	Description
Path	Path	Verified, atomically published artifact path.

Raises:

Type	Description
InterruptedError	If cancellation is requested during resolution.
ValueError	If downloaded bytes fail integrity verification.
OSError	If the cache cannot be created or written, or if the per-artifact lock is not acquired within LOCK_TIMEOUT_SECONDS.