openspeechapi 0.2.10__tar.gz → 0.2.11__tar.gz

{openspeechapi-0.2.10 → openspeechapi-0.2.11}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: openspeechapi
-Version: 0.2.10
+Version: 0.2.11
 Summary: Unified speech interface for STT/TTS providers
 Requires-Python: >=3.11
 Requires-Dist: httpx>=0.27
@@ -70,7 +70,11 @@ Requires-Dist: funasr>=1.1.0; extra == 'funasr-stt'
 Requires-Dist: torch; extra == 'funasr-stt'
 Requires-Dist: torchaudio; extra == 'funasr-stt'
 Provides-Extra: gemma4-stt
+Requires-Dist: accelerate; (sys_platform != 'darwin') and extra == 'gemma4-stt'
+Requires-Dist: librosa; (sys_platform != 'darwin') and extra == 'gemma4-stt'
 Requires-Dist: mlx-vlm<0.6.2,>=0.6.1; (sys_platform == 'darwin') and extra == 'gemma4-stt'
+Requires-Dist: torch; (sys_platform != 'darwin') and extra == 'gemma4-stt'
+Requires-Dist: transformers; (sys_platform != 'darwin') and extra == 'gemma4-stt'
 Provides-Extra: google
 Provides-Extra: google-stt
 Provides-Extra: google-tts

{openspeechapi-0.2.10 → openspeechapi-0.2.11}/openspeechapi/config.py

@@ -99,6 +99,13 @@ class ServerConfig:
     # Root dir for non-aim model downloads. "" → ~/.openspeechapi/models. When aim
     # is installed it manages its own ~/AI store and this is unused.
     model_storage_root: str = ""
+    # Robust download: HF mirror endpoints tried (in order) when huggingface.co is
+    # unreachable — model_hub auto-routes HF downloads here so HF-blocked boxes work
+    # without per-box hf_endpoint config. Exports OSA_HF_MIRRORS for workers.
+    hf_mirrors: list[str] = field(default_factory=lambda: ["https://hf-mirror.com"])
+    # Per-source download attempts (huggingface_hub resumes between attempts) before
+    # switching source. Exports OSA_MODEL_DOWNLOAD_RETRIES for workers.
+    model_download_retries: int = 3
 
 
 @dataclass
@@ -220,6 +227,14 @@ def load_config(path: Path) -> OpenSpeechConfig:
         server_cfg.hf_endpoint = srv.get("hf_endpoint", server_cfg.hf_endpoint)
         server_cfg.prefer_modelscope = bool(srv.get("prefer_modelscope", server_cfg.prefer_modelscope))
         server_cfg.model_storage_root = srv.get("model_storage_root", server_cfg.model_storage_root)
+        mirrors = srv.get("hf_mirrors")
+        if isinstance(mirrors, list) and mirrors:
+            server_cfg.hf_mirrors = [str(m).strip() for m in mirrors if str(m).strip()]
+        try:
+            server_cfg.model_download_retries = max(
+                1, int(srv.get("model_download_retries", server_cfg.model_download_retries)))
+        except (TypeError, ValueError):
+            pass
         # explicit default_model_source wins; else legacy prefer_modelscope → ms
         src = str(srv.get("default_model_source", "")).strip().lower()
         if src in ("hf", "ms"):

{openspeechapi-0.2.10 → openspeechapi-0.2.11}/openspeechapi/core/base.py

@@ -68,6 +68,11 @@ class SpeechProvider(ABC):
     settings_cls: type[BaseSettings] = BaseSettings  # Override in subclass
     capabilities: set[Capability]
     field_options: dict[str, list] = {}  # Dropdown choices per setting key (override in subclass)
+    # Languages this engine supports, for the Engines/Catalog language-filter tags ONLY
+    # (canonical ISO codes, e.g. ["zh","en","ja"]). Use this for multilingual engines that
+    # don't enumerate languages in field_options.language (gemma4/phi4/qwen3-omni/whisper…).
+    # The backend merges it with field_options.language when deriving the `languages` shown.
+    supported_languages: list[str] = []
     # UI category: "cloud" | "local" | "native". Leave None to auto-derive from
     # ``execution_mode`` (remote→cloud, subprocess/local/in_process→local) and
     # the OS-native provider set. Only set explicitly to override that default.

openspeechapi-0.2.11/openspeechapi/core/model_hub.py

@@ -0,0 +1,488 @@
+"""Resolve a model reference (local path or repo id) for transformers/mlx loaders,
+with optional ModelScope acceleration (hub=ms) for HF-blocked / slow networks.
+
+On the China deploy box ModelScope is ~9× faster than hf-mirror and sidesteps HF's
+Xet CAS (unreachable there). See docs/architecture/modelscope-hub.md.
+"""
+from __future__ import annotations
+
+import os
+import time
+from collections.abc import Mapping
+from typing import Any
+
+from openspeechapi.core.base import AimModelSpec, aim_local_path_or, aim_model_id
+from openspeechapi.logging_config import logger
+
+
+def _prefer_ms_env() -> bool:
+    """True when the server-level prefer_modelscope switch is on. ``create_app``
+    exports ``OSA_PREFER_MODELSCOPE=1`` from ``server.prefer_modelscope``; subprocess
+    workers inherit it (same mechanism as ``HF_ENDPOINT``)."""
+    return os.environ.get("OSA_PREFER_MODELSCOPE", "").strip().lower() in ("1", "true", "yes", "on")
+
+
+# ── network reachability + retry policy (robust model download) ──────────────────
+# Downloads fail on HF-blocked / flaky nets in two ways diagnosed in the field:
+#   (1) HF unreachable → loaders that hit huggingface.co hang then "model not found";
+#   (2) a reachable source's large file (e.g. SenseVoice's 893MB model.pt) breaks
+#       mid-transfer and the SDK doesn't resume → total failure.
+# The helpers below add: a cached reachability probe, an auto HF-mirror, and retrying
+# snapshot downloads with cross-source fallback. Used by resolve_model_source /
+# resolve_hub_model so every provider that downloads through model_hub benefits.
+
+_DEFAULT_HF_MIRRORS = ("https://hf-mirror.com",)
+_REACH_TTL_S = 300.0          # cache reachability for 5 min (avoid re-probing per load)
+_REACH_PROBE_TIMEOUT_S = 4.0
+_reach_cache: dict[str, tuple[bool, float]] = {}
+
+
+def _hf_mirrors() -> list[str]:
+    """HF mirror endpoints to try when huggingface.co is unreachable. Override via
+    OSA_HF_MIRRORS (comma-separated); exported from server.hf_mirrors."""
+    raw = os.environ.get("OSA_HF_MIRRORS", "").strip()
+    if raw:
+        return [m.strip() for m in raw.split(",") if m.strip()]
+    return list(_DEFAULT_HF_MIRRORS)
+
+
+def _download_retries() -> int:
+    """Per-source download attempts (resume between attempts). Override via
+    OSA_MODEL_DOWNLOAD_RETRIES; exported from server.model_download_retries."""
+    try:
+        return max(1, int(os.environ.get("OSA_MODEL_DOWNLOAD_RETRIES", "3")))
+    except ValueError:
+        return 3
+
+
+def _probe(url: str, timeout: float) -> bool:
+    """True if `url` answers (any non-5xx) within `timeout`s. httpx is a core dep;
+    import lazily so local-path-only resolves pay nothing."""
+    try:
+        import httpx
+        return httpx.get(url, timeout=timeout, follow_redirects=True).status_code < 500
+    except Exception:
+        return False
+
+
+def _reachable(url: str, *, ttl: float = _REACH_TTL_S,
+               timeout: float = _REACH_PROBE_TIMEOUT_S) -> bool:
+    """Cached reachability for `url` (TTL-bounded so flapping nets re-probe)."""
+    now = time.monotonic()
+    hit = _reach_cache.get(url)
+    if hit is not None and (now - hit[1]) < ttl:
+        return hit[0]
+    ok = _probe(url, timeout)
+    _reach_cache[url] = (ok, now)
+    return ok
+
+
+def reachable_sources() -> dict[str, bool]:
+    """Which model sources are reachable right now (cached): real HF, any HF mirror,
+    ModelScope. Drives reachability-aware source ordering."""
+    return {
+        "hf": _reachable("https://huggingface.co"),
+        "hf_mirror": any(_reachable(m) for m in _hf_mirrors()),
+        "ms": _reachable("https://www.modelscope.cn"),
+    }
+
+
+def ensure_reachable_download_env() -> None:
+    """Point HF downloads at a reachable endpoint so a loader's OWN sub-downloads
+    (e.g. funasr's VAD model) also succeed on HF-blocked nets — not just the main
+    weights we materialise ourselves.
+
+    Respects an existing HF_ENDPOINT (operator/config override). Otherwise, when
+    huggingface.co is unreachable but a known mirror is up, exports the mirror and
+    disables Xet (mirrors don't proxy HF's Xet CAS → classic LFS). Idempotent."""
+    if os.environ.get("HF_ENDPOINT", "").strip():
+        return
+    if _reachable("https://huggingface.co"):
+        return
+    for m in _hf_mirrors():
+        if _reachable(m):
+            os.environ["HF_ENDPOINT"] = m
+            os.environ.setdefault("HF_HUB_DISABLE_XET", "1")
+            logger.info("huggingface.co unreachable → auto-routing HF downloads via "
+                        "mirror {} (Xet disabled)", m)
+            return
+
+
+def effective_source(hub: str) -> str:
+    """Effective download source for a model: 'hf' or 'ms'.
+
+    - explicit engine hub 'ms'/'hf' wins
+    - ``'auto'`` → reachability-aware: the operator default (OSA_DEFAULT_MODEL_SOURCE) when
+      its source is reachable; else ModelScope if reachable (funasr-native, works on
+      HF-blocked nets); else HuggingFace (direct or via auto-mirror). This only decides a
+      *fresh* download's source — _materialise reuses any already-downloaded copy first.
+    - hub '' → global OSA_DEFAULT_MODEL_SOURCE (default 'hf')
+    - back-compat: OSA_PREFER_MODELSCOPE=1 with no explicit default → 'ms'
+    """
+    h = (hub or "").strip().lower()
+    if h in ("hf", "ms"):
+        return h
+    glob = os.environ.get("OSA_DEFAULT_MODEL_SOURCE", "").strip().lower()
+    if h == "auto":
+        reach = reachable_sources()
+        if glob == "hf" and (reach["hf"] or reach["hf_mirror"]):
+            return "hf"
+        if glob == "ms" and reach["ms"]:
+            return "ms"
+        if reach["ms"]:
+            return "ms"          # ModelScope reachable → prefer it (HF-block-proof)
+        return "hf"              # HF direct, or auto-mirror via ensure_reachable_download_env
+    if glob in ("hf", "ms"):
+        return glob
+    if _prefer_ms_env():
+        return "ms"
+    return "hf"
+
+
+def default_storage_root() -> str:
+    """Root dir for non-aim downloads. OSA_MODEL_ROOT if set, else
+    ~/.openspeechapi/models. (When aim manages models this is unused.)"""
+    root = os.environ.get("OSA_MODEL_ROOT", "").strip()
+    if root:
+        return os.path.expanduser(root)
+    return os.path.expanduser("~/.openspeechapi/models")
+
+
+def _ensure_symlink(link: str, target: str) -> str:
+    """Make `link` point at `target` (for loaders that require a fixed path).
+    Idempotent: repoints a stale symlink; NEVER clobbers a real file/dir
+    (logs and returns it as-is — see the safety rule). Returns the path to use."""
+    link = os.path.expanduser(link)
+    target = os.path.expanduser(target)
+    if os.path.islink(link):
+        if os.path.realpath(link) == os.path.realpath(target):
+            return link
+        os.unlink(link)  # stale symlink → repoint
+    elif os.path.exists(link):
+        logger.warning("symlink: {} is a real path (not a symlink); using as-is, "
+                       "not linking to {}", link, target)
+        return link
+    parent = os.path.dirname(link)
+    if parent:
+        os.makedirs(parent, exist_ok=True)
+    os.symlink(target, link)
+    return link
+
+
+def _maybe_symlink(fixed_path: str, resolved: str) -> str:
+    """If a loader requires a fixed path, symlink it to the resolved dir; else
+    return the resolved dir unchanged."""
+    return _ensure_symlink(fixed_path, resolved) if fixed_path else resolved
+
+
+def _aim_ensure(aim_spec: Any) -> str | None:
+    """Thin seam over aim_ensure_model (kept separate so tests can monkeypatch)."""
+    if aim_spec is None:
+        return None
+    try:
+        from openspeechapi.local_engines.aim_resolver import aim_ensure_model
+        return aim_ensure_model(aim_spec)
+    except Exception as exc:  # noqa: BLE001 - aim missing/broken → fall through
+        logger.warning("aim resolve failed ({}); falling back to source download", exc)
+        return None
+
+
+def _ms_snapshot(repo: str, *, retries: int = 1) -> str | None:
+    """modelscope.snapshot_download(repo) into the storage root, retried; None on
+    failure. ModelScope's SDK doesn't resume reliably, so a broken large file restarts
+    — the cross-source fallback in _materialise (→ hf-mirror) is the real safety net."""
+    try:
+        from modelscope import snapshot_download
+    except ImportError:
+        return None
+    cache = os.path.join(default_storage_root(), "modelscope")
+    os.makedirs(cache, exist_ok=True)
+    last: Exception | None = None
+    for attempt in range(1, retries + 1):
+        try:
+            return snapshot_download(repo, cache_dir=cache)
+        except Exception as exc:  # noqa: BLE001 - no ms mirror / network
+            last = exc
+            logger.warning("ModelScope snapshot {} attempt {}/{} failed ({})",
+                           repo, attempt, retries, exc)
+    logger.warning("ModelScope snapshot failed for {} after {} attempt(s) ({})",
+                   repo, retries, last)
+    return None
+
+
+def _hf_snapshot(repo: str, *, endpoint: str | None = None, retries: int = 1) -> str | None:
+    """huggingface_hub.snapshot_download(repo) into the storage root, retried; None on
+    failure. huggingface_hub resumes partially-downloaded files between attempts, so
+    retrying recovers from broken large transfers (the SenseVoice model.pt case).
+
+    ``endpoint`` overrides HF_ENDPOINT for this call (e.g. an auto-selected mirror);
+    a mirror endpoint also disables Xet (mirrors don't proxy HF's Xet CAS). Runs in the
+    provider's worker (one model at a time) so the env save/restore can't race."""
+    try:
+        from huggingface_hub import snapshot_download
+    except ImportError:
+        return None
+    cache = os.path.join(default_storage_root(), "huggingface")
+    os.makedirs(cache, exist_ok=True)
+    saved = {k: os.environ.get(k) for k in ("HF_ENDPOINT", "HF_HUB_DISABLE_XET")}
+    if endpoint:
+        os.environ["HF_ENDPOINT"] = endpoint
+        if "huggingface.co" not in endpoint:
+            os.environ["HF_HUB_DISABLE_XET"] = "1"
+    last: Exception | None = None
+    try:
+        for attempt in range(1, retries + 1):
+            try:
+                return snapshot_download(repo, cache_dir=cache)
+            except Exception as exc:  # noqa: BLE001 - network/not found → caller falls back
+                last = exc
+                logger.warning("HF snapshot {} attempt {}/{} failed ({})",
+                               repo, attempt, retries, exc)
+        logger.warning("HF snapshot failed for {} after {} attempt(s) ({})",
+                       repo, retries, last)
+        return None
+    finally:
+        for k, v in saved.items():
+            if v is None:
+                os.environ.pop(k, None)
+            else:
+                os.environ[k] = v
+
+
+def _download_archive(url: str, model_id: str) -> str | None:
+    """Download an archive (zip/tar) from a custom URL into <root>/url/<id> and
+    unpack it; return the dir. None on failure. (Engines without an HF/ms source.)"""
+    import shutil
+    import tempfile
+    import urllib.request
+    dest = os.path.join(default_storage_root(), "url", model_id)
+    marker = os.path.join(dest, ".download_complete")
+    if os.path.isfile(marker):
+        return dest
+    try:
+        os.makedirs(dest, exist_ok=True)
+        with tempfile.NamedTemporaryFile(delete=False) as tf:
+            with urllib.request.urlopen(url) as resp:  # noqa: S310 - operator-configured URL
+                shutil.copyfileobj(resp, tf)
+            tmp = tf.name
+        try:
+            shutil.unpack_archive(tmp, dest)
+        finally:
+            os.unlink(tmp)
+        open(marker, "w").close()  # noqa: WPS515 - sentinel written only on success
+        return dest
+    except Exception as exc:  # noqa: BLE001
+        logger.warning("custom-url download failed for {} ({})", url, exc)
+        return None
+
+
+def _download_candidates(
+    repo: str, hub: str, ms_repo_map: Mapping[str, str] | None,
+) -> list[tuple[str, str, str | None]]:
+    """Ordered ``(kind, repo_id, endpoint)`` download attempts for ``repo``, by hub
+    preference and current reachability.
+
+    - ms candidate only when an ms repo id is known (explicit map, or hub=ms so the
+      configured id *is* the ms id) AND ModelScope is reachable — never guess an HF org
+      onto ModelScope (the "FunAudioLLM/… not exists on ms" failure mode).
+    - hf candidate endpoint: operator HF_ENDPOINT > real HF (if up) > reachable mirror.
+    """
+    reach = reachable_sources()
+    ms_map = ms_repo_map or {}
+    pref = effective_source(hub)
+    explicit_endpoint = os.environ.get("HF_ENDPOINT", "").strip() or None
+
+    def hf_cand() -> tuple[str, str, str | None] | None:
+        if explicit_endpoint:
+            return ("hf", repo, explicit_endpoint)
+        if reach["hf"]:
+            return ("hf", repo, None)
+        for m in _hf_mirrors():
+            if _reachable(m):
+                return ("hf", repo, m)
+        return None
+
+    def ms_cand() -> tuple[str, str, str | None] | None:
+        rid = ms_map.get(repo) or (repo if (hub or "").strip().lower() == "ms" else None)
+        return ("ms", rid, None) if (rid and reach["ms"]) else None
+
+    ordered = [ms_cand(), hf_cand()] if pref == "ms" else [hf_cand(), ms_cand()]
+    return [c for c in ordered if c is not None]
+
+
+def _hf_local(repo: str) -> str | None:
+    """Path to an already-downloaded HF snapshot of ``repo`` (no network), or None.
+    Checks both the default HF cache (where funasr/transformers download) and our storage
+    root, so an existing copy is reused no matter which path originally fetched it."""
+    try:
+        from huggingface_hub import snapshot_download
+    except ImportError:
+        return None
+    for cache_dir in (None, os.path.join(default_storage_root(), "huggingface")):
+        try:
+            return snapshot_download(repo, cache_dir=cache_dir, local_files_only=True)
+        except Exception:  # noqa: BLE001 - not in this cache → try the next / give up
+            continue
+    return None
+
+
+def _ms_local(repo: str) -> str | None:
+    """Path to an already-downloaded ModelScope snapshot of ``repo`` (no network), or None.
+    Checks our storage root and the default modelscope cache."""
+    for base in (os.path.join(default_storage_root(), "modelscope"),
+                 os.path.expanduser("~/.cache/modelscope/hub")):
+        d = os.path.join(base, *repo.split("/"))
+        if os.path.isdir(d) and os.listdir(d):
+            return d
+    return None
+
+
+def _local_hit(kind: str, rid: str) -> str | None:
+    """An already-downloaded local copy for this candidate (no network), or None."""
+    return _ms_local(rid) if kind == "ms" else _hf_local(rid)
+
+
+def _materialise(repo: str, hub: str, ms_repo_map: Mapping[str, str] | None) -> str | None:
+    """Resolve ``repo`` to a local dir. **Existing copy first**: reuse an already-downloaded
+    copy from ANY candidate platform (local, no network, no re-download) before fetching —
+    so a model already present via one hub is NOT re-downloaded just because the other hub
+    is preferred (e.g. ms-preferred but the hf copy already exists). Only when nothing is
+    local does it download from the preferred reachable source, switching sources on
+    failure. None if all candidates fail."""
+    cands = _download_candidates(repo, hub, ms_repo_map)
+    # Pass 1: reuse any already-downloaded copy (any candidate platform).
+    for kind, rid, _endpoint in cands:
+        hit = _local_hit(kind, rid)
+        if hit:
+            logger.info("model download: reusing local {} copy of {} ({})", kind, rid, hit)
+            return hit
+    # Pass 2: nothing local → download from the preferred reachable source.
+    retries = _download_retries()
+    for kind, rid, endpoint in cands:
+        logger.info("model download: {} ← {} source {} (endpoint={})",
+                    repo, kind, rid, endpoint or "default")
+        got = (_ms_snapshot(rid, retries=retries) if kind == "ms"
+               else _hf_snapshot(rid, endpoint=endpoint, retries=retries))
+        if got:
+            logger.info("model download: {} ready at {} (via {})", repo, got, kind)
+            return got
+        logger.warning("model download: {} source {} failed; switching source", kind, rid)
+    return None
+
+
+def local_model_path(repo: str, ms_repo_map: Mapping[str, str] | None = None) -> str | None:
+    """An already-downloaded local copy of ``repo`` from EITHER platform (HF cache or
+    ModelScope cache), or None. Lets a caller skip a re-download when a copy already exists
+    under the other hub's id/cache — e.g. so `hub=auto` preferring ModelScope won't refetch
+    a model that's already present from a prior HuggingFace download."""
+    ms_repo = (ms_repo_map or {}).get(repo, repo)
+    return _hf_local(repo) or _ms_local(ms_repo)
+
+
+def build_aim_spec(model: str, hub: str, ms_repo_map: Mapping[str, str] | None = None,
+                   category: str = "asr/model") -> AimModelSpec | None:
+    """Shared ``aim_model_spec`` body for HF⇄ModelScope-mirrored models.
+
+    Returns None when a copy is already downloaded on EITHER platform — so the worker's
+    existing-copy-first resolve reuses it instead of aim re-downloading from the (possibly
+    different) preferred hub. Otherwise resolves ``hub`` ('auto' → a reachable platform) to a
+    concrete source and builds the spec with the matching repo id (``<scheme>-<org>-<repo>``,
+    so `aim scan`-adopted weights resolve). aim-store copies are found via `aim resolve`, so
+    those are still reused even though local_model_path doesn't see the store."""
+    if local_model_path(model, ms_repo_map):
+        return None
+    scheme = "ms" if effective_source(hub) == "ms" else "hf"
+    repo = (ms_repo_map or {}).get(model, model) if scheme == "ms" else model
+    return AimModelSpec(source=f"{scheme}:{repo}",
+                        model_id=aim_model_id(repo, scheme), category=category)
+
+
+def resolve_model_source(
+    repo: str,
+    *,
+    hub: str = "",
+    model_path: str = "",
+    aim_spec: Any = None,
+    ms_repo_map: Mapping[str, str] | None = None,
+    custom_url: str = "",
+    fixed_path: str = "",
+    category: str = "asr/model",  # noqa: ARG001 - reserved; aim_spec already carries it
+    snapshot: bool = False,
+) -> str:
+    """Return a loadable local path (or a repo id for HF loaders). See
+    docs/architecture/unified-model-download.md §2 for the priority chain.
+
+    When ``snapshot=True`` and the source falls through to HF, the function
+    calls ``_hf_snapshot`` to materialise a real local directory (honoring
+    ``HF_ENDPOINT``). Loaders that require a local dir (dolphin, etc.) use this
+    instead of receiving a bare repo id. On failure it falls back to the repo id
+    so callers are never broken."""
+    # 1. explicit local path wins.
+    local = aim_local_path_or(model_path, "")
+    if local:
+        return _maybe_symlink(fixed_path, local)
+    # 2. aim (when available + opted in). None → native-CAS already in aim cache OR
+    #    aim absent → fall through (the hf branch returns the repo id).
+    aim_path = _aim_ensure(aim_spec)
+    if aim_path:
+        return _maybe_symlink(fixed_path, aim_path)
+    # 3. engine custom url (engines with no HF/ms repo-id load path).
+    if custom_url:
+        url_dir = _download_archive(custom_url, repo.replace("/", "-"))
+        if url_dir:
+            return _maybe_symlink(fixed_path, url_dir)
+    # 4. make a loader's OWN sub-downloads (e.g. funasr's VAD) reach HF on blocked nets.
+    ensure_reachable_download_env()
+    # 5. robust download → local dir, when one is needed: the loader wants a local dir
+    #    (snapshot), ModelScope is the source (loaders take a dir there), or HF is
+    #    unreachable (handing back a bare repo id would dead-end). Reachability-aware,
+    #    retrying, cross-source. Otherwise (HF reachable, hf loader) return the repo id
+    #    so the loader fetches directly — the long-standing fast path.
+    if (snapshot or (hub or "").strip().lower() == "auto"
+            or effective_source(hub) == "ms" or not reachable_sources()["hf"]):
+        got = _materialise(repo, hub, ms_repo_map)
+        if got:
+            return _maybe_symlink(fixed_path, got)
+        logger.warning("model download: all sources failed for {}; returning repo id "
+                       "(loader will try directly)", repo)
+    return repo
+
+
+def effective_hub(hub: str) -> str:
+    """Effective download hub for a model.
+
+    - explicit ``ms`` → ``ms``
+    - ``""`` / ``hf`` while the global ``OSA_PREFER_MODELSCOPE`` switch is on → ``ms``
+    - else → ``hf``
+    """
+    h = (hub or "").strip().lower()
+    if h == "ms":
+        return "ms"
+    if h in ("", "hf") and _prefer_ms_env():
+        return "ms"
+    return "hf"
+
+
+def resolve_hub_model(
+    model: str,
+    hub: str = "hf",
+    *,
+    model_path: str = "",
+    ms_repo_map: Mapping[str, str] | None = None,
+) -> str:
+    """Resolve a ``from_pretrained``-style model ref (funasr / transformers loaders) to
+    a loadable local dir or a repo id, with reachability-aware, retrying, cross-source
+    download (auto HF mirror on blocked nets, ModelScope ↔ HF fallback). Returns a bare
+    repo id only when HF is reachable and the loader can fetch it itself (fast path).
+
+    No aim trigger here — callers aim-provision ``model_path`` out of band (main
+    process); an aim-provisioned local path wins and survives aim uninstall (no
+    re-download). Missing ``modelscope`` no longer raises: the cross-source fallback
+    routes to HF / a mirror instead of breaking the load."""
+    local = aim_local_path_or(model_path, "")
+    if local:
+        return local
+    return resolve_model_source(
+        model, hub=hub, model_path=model_path, ms_repo_map=ms_repo_map,
+        aim_spec=None, snapshot=False,
+    )

{openspeechapi-0.2.10 → openspeechapi-0.2.11}/openspeechapi/dispatch/dispatcher.py

@@ -397,13 +397,16 @@ class ServiceDispatcher:
                 c.value if hasattr(c, "value") else str(c) for c in caps
             )
 
-            # Supported languages from field_options (for the Engines tag filter).
-            # Drop the auto-detect / non-speech sentinels — they aren't languages.
+            # Supported languages for the Engines tag filter: field_options.language plus the
+            # provider's `supported_languages` (multilingual engines that don't enumerate a
+            # language setting). Drop the auto-detect / non-speech sentinels — not languages.
             field_opts = getattr(provider_cls, "field_options", {}) or {}
-            languages = [
-                str(x) for x in (field_opts.get("language") or [])
-                if str(x).lower() not in ("auto", "nospeech")
-            ]
+            _langs = list(field_opts.get("language") or []) + list(
+                getattr(provider_cls, "supported_languages", []) or []
+            )
+            languages = list(dict.fromkeys(
+                str(x) for x in _langs if str(x).lower() not in ("auto", "nospeech")
+            ))
 
             # Pick display-friendly settings
             display_info = {}

{openspeechapi-0.2.10 → openspeechapi-0.2.11}/openspeechapi/local_engines/aim_resolver.py

@@ -8,6 +8,8 @@ import shutil
 import subprocess
 from typing import Any
 
+from openspeechapi.logging_config import logger
+
 # Resolve is a quick registry lookup; downloads can be large. Both are bounded so
 # a stalled aim CLI (e.g. a blocked network) can't hang forever — on timeout the
 # caller falls back to the provider's own download.
@@ -147,13 +149,23 @@ def _aim_download(source: str, model_id: str, category: str) -> bool:
 
     Bounded by ``OSA_AIM_DOWNLOAD_TIMEOUT_S`` (default 1800s); on timeout/failure
     returns False so the caller falls back to the provider's own download."""
-    args = ["download", source, "--name", model_id]
+    # ``-y`` auto-confirms installing aim's missing backend tools (modelscope /
+    # huggingface_hub) so a server-driven (no-stdin) ``aim download`` never blocks on the
+    # interactive "Install backend? [y/N]" prompt and aborts — aim >= 0.2.0. (Equivalent:
+    # AIM_ASSUME_YES=1 env or defaults.auto_install_backend in aim's config.)
+    args = ["download", source, "--name", model_id, "-y"]
     if category:
         args += ["--category", category]
     try:
         _run_aim(args, timeout=_download_timeout_s())
         return True
-    except Exception:
+    except Exception as exc:  # noqa: BLE001 - any failure → provider falls back, but log why
+        # Don't fail silently — surface the reason (network down, backend install failed, …)
+        # so it's diagnosable; the provider then falls back to its own robust download.
+        logger.warning(
+            "aim download failed for {} (name={}): {} — falling back to the provider's "
+            "own download.", source, model_id, str(exc)[:300],
+        )
         return False