video_helper.faces.models module

video_helper.faces.models

Model registry + on-demand downloader for the face stack (detection, recognition, active-speaker detection).

Sourcing policy (sovereign, HuggingFace-free at runtime)

Weights are fetched on first use and cached on disk. The registry resolves each model in this order:

  1. The user’s own mirror — AI_HELPERS_MODEL_BASE_URL (default https://harchaoui.org/warith/ai-helpers/models/). This is the preferred path once the mirror is seeded (see scripts/seed_model_mirror.py).

  2. A permissive, HuggingFace-free upstream (OpenCV Zoo / InsightFace GitHub releases) as a first-run convenience so the feature works before the mirror exists. Never HuggingFace.

If every source fails the caller gets None and is expected to degrade gracefully (e.g. the ASD stack falls back to the zero-weight lip-motion proxy).

Everything is logged through os_helper (osh.info/warning/error); files land under ~/.cache/ai-helpers/models/ (override with VIDEO_HELPER_MODEL_DIR).

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

Bases: object

One downloadable weight file.

Parameters:

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

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

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

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

  • license (str) – SPDX-ish tag; noncommercial models are gated by the caller.

filename: str
license: str = 'unknown'
name: str
sha256: str = ''
upstreams: list[str]
video_helper.faces.models.ensure_model(name)[source]

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

Parameters:

name (str) – A key in REGISTRY.

Returns:

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

Return type:

str or None

video_helper.faces.models.model_dir()[source]

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

Return type:

str