vocal_helper.models module

vocal_helper.models

Model registry + on-demand downloader for the diarization / speaker-embedding ONNX weights vocal-helper’s torch-free sherpa path needs.

Sourcing policy (sovereign, HuggingFace-free at runtime)

Weights are fetched on first use and cached on disk. The registry resolves each model from the shared ai-helpers mirror — the same host and cache the rest of the suite uses (video-helper’s face stack, etc.), so a weight downloaded once by any helper is reused by all:

  • AI_HELPERS_MODEL_BASE_URL (default https://harchaoui.org/warith/ai-helpers/models/) — the user’s own infrastructure. Never HuggingFace, no token, no gated repo.

If the mirror (and any HuggingFace-free upstream fallback) fails, the caller gets None and is expected to degrade gracefully — e.g. diar._SherpaEmbedder falls back to raising a clear “provide a model_path” error, and the existing env-override / diarization-engines-bundle resolution keeps working untouched.

Everything is logged through os_helper (osh.info/warning); files land under ~/.cache/ai-helpers/models/ (override with VOCAL_HELPER_MODEL_DIR) — the same shared cache directory the sibling helpers use.

class vocal_helper.models.ModelSpec(name, filename, sha256='', upstreams=<factory>, license='unknown')[source]

Bases: object

One downloadable weight file.

Parameters:

  • name (str) – Registry key (also the config-facing identifier).

  • filename (str) – On-disk basename under the cache dir and the path segment on the mirror.

  • sha256 (str) – Expected hex digest, or "" to skip integrity checking (used until the mirror is seeded with pinned digests).

  • upstreams (list[str]) – HuggingFace-free fallback URLs tried, in order, only if the mirror misses.

  • license (str) – SPDX-ish tag; a model whose license is not clearly permissive is gated by the caller (allow_noncommercial).

filename: str
license: str = 'unknown'
name: str
sha256: str = ''
upstreams: list[str]
vocal_helper.models.ensure_model(name, *, allow_noncommercial=False)[source]

Resolve a model to a local path, downloading + caching on first use.

Parameters:

  • name (str) – A key in REGISTRY.

  • allow_noncommercial (bool, optional) – Gate for research / non-commercial weights. A model whose license is not clearly permissive is refused unless this is set. Default False.

Returns:

Local filesystem path to the ready weight, or None if the model is gated-off or could not be fetched from any source (caller degrades).

Return type:

str or None

vocal_helper.models.model_dir()[source]

Return (creating if needed) the shared local model cache directory.

Defaults to ~/.cache/ai-helpers/models — the same location the other ai-helpers use, so a weight fetched by one is reused by all. Override with VOCAL_HELPER_MODEL_DIR.

Returns:

Absolute path to the (now existing) cache directory.

Return type:

str