Local UI to run and train LLMs and diffusion models. Supports GGUF, MLX, Qwen3.8, DeepSeek-V4.1, MiniMax-H3, Gemma 4, FLUX and more.
Python agentaichatgptdeepseekfine-tuninggemmaimage-generationllamallmllmsopenaipythonqwenreinforcement-learningself-hostedstable-diffusiontext-to-speechttsuiunsloth
#!/usr/bin/env python3
# SPDX-License-Identifier: AGPL-3.0-only
# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
"""Installs whisper-server from unslothai/whisper.cpp into <UNSLOTH_HOME>/whisper.cpp/build/bin,
never a system copy; assets missing from whisper-prebuilt-sha256.json fail closed; re-runs that
log already matches return 0; failed lookup with intact install returns 0 (setup scripts grep
both logs)."""
from __future__ import annotations
import argparse
import json
import os
import re
import shutil
import subprocess
import sys
from dataclasses import dataclass, replace
from pathlib import Path
from typing import Any, Iterable
_STUDIO_DIR = os.path.dirname(os.path.abspath(__file__))
if _STUDIO_DIR not in sys.path:
sys.path.insert(0, _STUDIO_DIR)
import install_llama_prebuilt as llama # noqa: E402
import prebuilt_core as core # noqa: E402
# Re-exported as globals so tests can monkeypatch them here.
PrebuiltFallback = core.PrebuiltFallback
BusyInstallConflict = core.BusyInstallConflict
auth_headers = llama.auth_headers
download_bytes = llama.download_bytes
download_file = llama.download_file
fetch_json = llama.fetch_json
sha256_file = core.sha256_file
_URL_OPENER = core._URL_OPENER
install_lock = core.install_lock
install_lock_path = core.install_lock_path
parse_macos_version = core.parse_macos_version
release_asset_map = core.release_asset_map
release_asset_download_url = core.release_asset_download_url
compute_install_fingerprint = core.compute_install_fingerprint
artifact_coverage = core.artifact_coverage
emit_resolver_output = core.emit_resolver_output
_valid_sha256 = core.valid_sha256
_swap_into_place = core.swap_into_place
InstallSelection = core.InstallSelection
ReleaseBundle = core.ReleaseBundle
llama_detect_host = llama.detect_host
installed_llama_runtime = llama.installed_llama_runtime
installed_llama_ggml_tree = llama.installed_llama_ggml_tree
_OPS = core.ModuleOps(globals())
# Resolver mode keeps stdout JSON-only (setup.sh parses it).
_LOG_TO_STDOUT = False
ReleaseIntegrityError = core.ReleaseIntegrityError
class ReleaseCompatibilityError(PrebuiltFallback):
"""A valid slim release cannot pair with this host's installed runtime."""
class LlamaPairingGapError(ReleaseCompatibilityError):
"""The release's slim bundles pair with no llama.cpp build tree the host has installed."""
_PAIRING_GAP_PREFIX = "slim bundle requires llama.cpp "
def log(message: str) -> None:
print(f"[whisper-prebuilt] {message}", file = sys.stdout if _LOG_TO_STDOUT else sys.stderr)
def log_lines(lines: Iterable[str]) -> None:
for line in lines:
log(line)
EXIT_SUCCESS = 0
EXIT_ERROR = 1
EXIT_INCOMPATIBLE = 2
EXIT_BUSY = 3
COMPONENT = "whisper.cpp"
SCHEMA_VERSION = 1
USER_AGENT = "unsloth-studio-whisper-prebuilt"
DEFAULT_PUBLISHED_REPO = "unslothai/whisper.cpp"
MANIFEST_ASSET_NAME = "whisper-prebuilt-manifest.json"
SHA256_ASSET_NAME = "whisper-prebuilt-sha256.json"
METADATA_FILENAME = "UNSLOTH_WHISPER_PREBUILT_INFO.json"
# Only "cpu" can match a fat artifact (the pinned escape hatch).
SUPPORTED_BACKENDS = ("cpu", "cuda", "metal", "vulkan", "rocm")
FALLBACK_BACKEND = "cpu"
SLIM_ELIGIBLE_BACKENDS = ("cpu", "cuda", "metal", "rocm", "vulkan")
# ggml backend module the llama bin dir must provide per accelerator.
SLIM_BACKEND_MODULE_GLOBS = {
"cpu": {
"linux": "libggml-cpu*.so*",
"windows": "ggml-cpu*.dll",
"macos": "libggml-cpu*.dylib",
},
"cuda": {"linux": "libggml-cuda.so*", "windows": "ggml-cuda.dll"},
"metal": {"macos": "libggml-metal*.dylib"},
# Windows rocm must name the ggml module: the bundles also ship amdhip64
"rocm": {"linux": "libggml-hip.so*", "windows": "ggml-hip*.dll"},
"vulkan": {"linux": "libggml-vulkan.so*", "windows": "ggml-vulkan.dll"},
}
# libomp*: llama's clang-built slices link ggml against bundled LLVM OpenMP.
SLIM_GGML_LIBRARY_GLOBS = (
"libggml*",
"ggml*.dll",
"libomp*.dll",
"libomp*.so*",
"libomp*.dylib",
)
SLIM_ROCM_LIBRARY_GLOBS = (
"libamd*.so*",
"libhip*.so*",
"libhsa*.so*",
"libroc*.so*",
)
SLIM_ROCM_RUNTIME_DIRS = ("hipblaslt", "rocblas")
SLIM_ROCM_REQUIRED_RUNTIME_DIRS = ("rocblas",)
# Bump when the wiring set changes.
SLIM_RUNTIME_WIRING_VERSION = 3
INSTALL_STAGING_ROOT_NAME = ".staging"
# Off by default: GPU kernel JIT on the first forward pass stalls installs.
_RUN_STAGED_PREBUILT_VALIDATION = False
# ── Host detection (probes shared with install_llama_prebuilt) ──
@dataclass(frozen = True)
class HostInfo:
system: str
machine: str
whisper_os: str
whisper_arch: str # asset token: x64 | arm64
archive_ext: str
is_windows: bool
is_macos: bool
is_apple_silicon: bool
has_usable_nvidia: bool = False
has_rocm: bool = False
rocm_gfx: str | None = None
# Enforces a macOS artifact's min_os.
macos_version: tuple[int, int] | None = None
def host_from_llama(base: Any) -> HostInfo:
"""Map install_llama_prebuilt's detected host onto the whisper asset tokens.
Raises PrebuiltFallback on an unsupported OS/arch."""
system = base.system
machine = base.machine.lower()
if system == "Linux":
whisper_os = "linux"
elif system == "Darwin":
whisper_os = "macos"
elif system == "Windows":
whisper_os = "windows"
else:
raise PrebuiltFallback(f"unsupported operating system for whisper.cpp prebuilt: {system}")
if machine in {"x86_64", "amd64", "x64"}:
whisper_arch = "x64"
elif machine in {"arm64", "aarch64"}:
whisper_arch = "arm64"
else:
raise PrebuiltFallback(f"unsupported CPU architecture for whisper.cpp prebuilt: {machine}")
return HostInfo(
system = system,
machine = machine,
whisper_os = whisper_os,
whisper_arch = whisper_arch,
archive_ext = ".zip" if base.is_windows else ".tar.gz",
is_windows = base.is_windows,
is_macos = base.is_macos,
is_apple_silicon = base.is_macos and whisper_arch == "arm64",
has_usable_nvidia = base.has_usable_nvidia,
has_rocm = base.has_rocm,
rocm_gfx = base.rocm_gfx_target,
macos_version = base.macos_version,
)
def detect_host() -> HostInfo:
return host_from_llama(llama_detect_host())
def apply_host_overrides(
host: HostInfo,
*,
has_rocm: bool = False,
rocm_gfx: str | None = None,
force_cpu: bool = False,
) -> HostInfo:
"""Apply CLI overrides (setup forwards hardware hints) onto a detected host."""
if force_cpu:
return replace(
host,
has_usable_nvidia = False,
has_rocm = False,
rocm_gfx = None,
is_apple_silicon = False,
)
updates: dict[str, Any] = {}
if has_rocm or rocm_gfx:
# --rocm-gfx implies --has-rocm (llama parity) and drops CUDA detection.
updates["has_rocm"] = True
updates["has_usable_nvidia"] = False
if rocm_gfx:
updates["rocm_gfx"] = rocm_gfx
return replace(host, **updates) if updates else host
def host_platform_tokens(host: HostInfo) -> tuple[str, str]:
"""Canonical (os, arch) asset tokens the core uses for matching/reporting."""
return host.whisper_os, host.whisper_arch
# ── Backend selection ──
def auto_detect_backend(host: HostInfo) -> str:
return core.auto_detect_backend(_OPS, host)
def resolve_backend(host: HostInfo, requested: str | None, *, cpu_fallback: bool) -> str:
return core.resolve_backend(_OPS, host, requested, cpu_fallback = cpu_fallback)
# ── Asset naming (pure, unit tested) ──
def whisper_asset_name(release_tag: str, host: HostInfo, accel: str) -> str:
"""e.g. whisper-v1.9.1-unsloth.1-linux-x64-cpu.tar.gz.
`accel` is the asset-filename accelerator token (cpu, metal, cuda12, ...),
finer-grained than the coarse backend. An install's authoritative asset name
comes from the release manifest; this constructor is for defaults/diagnostics.
"""
tag = release_tag if release_tag.startswith("v") else f"v{release_tag}"
return f"whisper-{tag}-{host.whisper_os}-{host.whisper_arch}-{accel}{host.archive_ext}"
# ── Manifest (release-side artifact catalogue; generic parser in the core) ──
def validate_schema_version(payload: dict[str, Any], *, label: str) -> None:
core.validate_schema_version(
payload, label = label, schema_version = SCHEMA_VERSION, error = PrebuiltFallback
)
def parse_manifest(payload: Any, *, label: str = MANIFEST_ASSET_NAME) -> dict[str, Any]:
return core.parse_manifest(_OPS, payload, label = label)
def _macos_min_os_ok(host: HostInfo, min_os: Any) -> bool:
return core.macos_min_os_ok(_OPS, host, min_os)
def macos_min_os_ok(host: HostInfo, min_os: Any) -> bool:
return _macos_min_os_ok(host, min_os)
def _artifacts_for_host(
manifest: dict[str, Any], host: HostInfo, backend: str
) -> list[dict[str, Any]]:
return core.artifacts_for_host(_OPS, manifest, host, backend)
def artifacts_for_host(
manifest: dict[str, Any], host: HostInfo, backend: str
) -> list[dict[str, Any]]:
return _artifacts_for_host(manifest, host, backend)
# ── Slim selection (paired with the installed llama.cpp ggml runtime) ──
def _llama_ggml_commit(tag: str) -> str | None:
"""The "-mix-" suffix of a fork tag "b<upstream_build>-mix-<suffix>".
Despite the name this is NOT a ggml commit: it hashes the pinned PR set and
stays constant while the base tag, and ggml with it, moves (one value covered
b9909..b10001, whose ggml trees differ). Fallback for releases predating
ggml_tree."""
marker = "-mix-"
idx = tag.rfind(marker)
end = idx + len(marker)
return tag[end:] if idx >= 0 and end < len(tag) else None
_PUBLISHED_GGML_TREE_CACHE: dict[tuple[str, str], str | None] = {}
def published_llama_ggml_tree(tag: Any, repo: Any = None) -> str | None:
"""Reads the ggml tree from the published release manifest, not the -mix- suffix; fetches once
with no retries, since an unreachable host would stall every tag; failures return None so the
caller falls back rather than refusing a valid install."""
if not isinstance(tag, str) or not tag:
return None
if not (isinstance(repo, str) and repo):
repo = llama.DEFAULT_PUBLISHED_REPO
key = (repo, tag)
if key in _PUBLISHED_GGML_TREE_CACHE:
return _PUBLISHED_GGML_TREE_CACHE[key]
tree = None
try:
payload = _download_host_json_once(
release_asset_download_url(repo, tag, llama.DEFAULT_PUBLISHED_MANIFEST_ASSET)
)
if isinstance(payload, dict):
candidate = payload.get("ggml_tree")
if isinstance(candidate, str) and candidate:
tree = candidate
except Exception as exc:
log(f"slim_selection: could not read ggml_tree for llama {tag}: {exc}")
_PUBLISHED_GGML_TREE_CACHE[key] = tree
return tree
def installed_llama_tree_repo() -> str | None:
"""Repo that published the installed llama binaries, or None; a fork tree is never inferred."""
metadata = llama.load_prebuilt_metadata(llama.default_managed_llama_dir())
if metadata is None:
return None
published = metadata.get("published_repo")
if not isinstance(published, str) or not published:
return None
binary = metadata.get("binary_repo")
if isinstance(binary, str) and binary and binary != published:
return None
return published
def llama_runtime_pairs(
installed_tag: str,
required_tag: Any,
*,
installed_ggml_tree: Any = None,
required_ggml_tree: Any = None,
installed_repo: Any = None,
) -> bool:
"""Whether an installed llama tag can back a slim bundle needing required_tag.
An exact tag always pairs; otherwise the ggml tree ids decide, since they
change exactly when ggml does. The "-mix-" suffix does not track ggml at all
(see _llama_ggml_commit) and is only used when either tree is missing.
requires_ggml_sonames stays the per-file ABI gate.
installed_repo is the repo that published the installed runtime (from
installed_llama_tree_repo()); without it the installed tag's tree is not
inferred, since only the caller knows the binaries came from that release."""
if not isinstance(required_tag, str):
return False
if installed_tag == required_tag:
return True
# Pre-ggml_tree install: read the tree from that tag's published release.
if not (isinstance(installed_ggml_tree, str) and installed_ggml_tree):
if isinstance(installed_repo, str) and installed_repo:
installed_ggml_tree = published_llama_ggml_tree(installed_tag, installed_repo)
if installed_ggml_tree and not (isinstance(required_ggml_tree, str) and required_ggml_tree):
required_ggml_tree = published_llama_ggml_tree(required_tag)
if installed_ggml_tree and required_ggml_tree:
return installed_ggml_tree == required_ggml_tree
commit = _llama_ggml_commit(installed_tag)
return commit is not None and commit == _llama_ggml_commit(required_tag)
def _ships_gpu_ggml_module(llama_bin_dir: Path, os_key: str) -> bool:
"""Whether a paired llama runtime carries a GPU ggml backend module.
Only the cpu bundle links ggml against libomp, and bundle_profile cannot tell
the two apart: it is absent on both the published rocm artifacts and every
upstream-sourced install, so the files on disk decide."""
for backend, per_os in SLIM_BACKEND_MODULE_GLOBS.items():
glob = per_os.get(os_key)
# is_file(): a versioned alias counts, a directory or dangling link does not.
if backend != "cpu" and glob and any(path.is_file() for path in llama_bin_dir.glob(glob)):
return True
return False
def _ships_windows_gpu_ggml_module(llama_bin_dir: Path) -> bool:
"""Windows spelling of _ships_gpu_ggml_module; kept for call-site clarity."""
return _ships_gpu_ggml_module(llama_bin_dir, "windows")
def _is_linux_libomp_soname(name: str) -> bool:
"""LLVM's OpenMP runtime: bundled, so it can go missing. Not host-provided libgomp,
and not libomptarget, which a prefix match would sweep up."""
lowered = name.lower()
return lowered == "libomp.so" or lowered.startswith("libomp.so.")
def _ggml_stack_imports_libomp(llama_bin_dir: Path, backend: str) -> bool | None:
"""Whether ggml libs or the late-dlopen'd backend import libomp; None if any could not be inspected."""
patterns = ["libggml-base.so*", "libggml.so*"]
module_glob = SLIM_BACKEND_MODULE_GLOBS.get(backend, {}).get("linux")
if module_glob:
patterns.append(module_glob)
inspected_any = False
inspected_all = True
for pattern in patterns:
for path in sorted(llama_bin_dir.glob(pattern)):
if not path.is_file():
continue
needed = _elf_needed(path)
if needed is None:
inspected_all = False
continue
inspected_any = True
if any(_is_linux_libomp_soname(dep) for dep in needed):
return True
return False if inspected_any and inspected_all else None
def slim_pairing_for_artifact(
artifact: dict[str, Any], host: HostInfo, backend: str
) -> tuple[Path, str] | None:
"""Returns (llama bin dir, release tag) if the installed runtime can back this artifact; else None."""
asset = artifact.get("asset")
runtime = installed_llama_runtime()
if runtime is None:
log(f"slim_selection: {asset} skipped: no managed llama.cpp prebuilt install")
return None
llama_bin_dir, llama_tag, _profile = runtime
requires_tag = artifact.get("requires_llama_tag")
if not llama_runtime_pairs(
llama_tag,
requires_tag,
installed_ggml_tree = installed_llama_ggml_tree(),
required_ggml_tree = artifact.get("requires_ggml_tree"),
installed_repo = installed_llama_tree_repo(),
):
log(
f"slim_selection: {asset} skipped: installed llama tag {llama_tag!r} "
f"does not pair with required {requires_tag!r}"
)
return None
sonames = artifact.get("requires_ggml_sonames")
if not isinstance(sonames, list) or not sonames:
log(f"slim_selection: {asset} skipped: manifest lists no requires_ggml_sonames")
return None
required_sonames = [str(name) for name in sonames]
if host.is_windows and _ships_windows_gpu_ggml_module(llama_bin_dir):
# libomp is only needed by the cpu bundle (arm64 Vulkan builds GGML_OPENMP=OFF); re-check if an
# arm64 GPU bundle ever builds with OpenMP.
required_sonames = [
name
for name in required_sonames
if not (name.lower().startswith("libomp") and name.lower().endswith(".dll"))
]
if (
host.whisper_os == "linux"
and host.whisper_arch == "arm64"
and _ships_gpu_ggml_module(llama_bin_dir, "linux")
and _ggml_stack_imports_libomp(llama_bin_dir, backend) is False
):
# Drop libomp only on evidence it is unneeded; the arm64 Vulkan bundle really imports it.
required_sonames = [name for name in required_sonames if not _is_linux_libomp_soname(name)]
missing = [name for name in required_sonames if not (llama_bin_dir / name).is_file()]
if missing:
log(f"slim_selection: {asset} skipped: llama runtime missing {', '.join(missing)}")
return None
module_glob = SLIM_BACKEND_MODULE_GLOBS.get(backend, {}).get(host.whisper_os)
if module_glob is None:
log(f"slim_selection: {asset} skipped: no {backend} ggml module on {host.whisper_os}")
return None
if not any(path.is_file() for path in llama_bin_dir.glob(module_glob)):
log(f"slim_selection: {asset} skipped: llama runtime has no {module_glob} module")
return None
log(f"slim_selection: selected {asset} paired with llama {llama_tag} at {llama_bin_dir}")
return llama_bin_dir, llama_tag
def select_slim_artifact(
manifest: dict[str, Any], host: HostInfo, backend: str
) -> dict[str, Any] | None:
"""Paired slim artifact for any backend, or None; slim assets skip fat matching; when slim
candidates exist but none pair, log the actionable reason: setup then reports the prebuilt
unavailable and dictation stays on Transformers STT."""
if backend not in SLIM_ELIGIBLE_BACKENDS:
return None
os_token, arch_token = host_platform_tokens(host)
candidates = [
artifact
for artifact in manifest.get("artifacts", [])
if artifact.get("os") == os_token
and artifact.get("arch") == arch_token
and artifact.get("backend") == "slim"
and artifact.get("install_kind") == "slim"
and (not host.is_macos or _macos_min_os_ok(host, artifact.get("min_os")))
]
for artifact in candidates:
if slim_pairing_for_artifact(artifact, host, backend) is not None:
return artifact
if candidates:
required_tag = candidates[0].get("requires_llama_tag")
log(f"slim bundle requires llama.cpp {required_tag}; install or update llama.cpp first")
return None
def select_artifact(
manifest: dict[str, Any], host: HostInfo, backend: str
) -> dict[str, Any] | None:
"""Slim-only, except a pinned pre-slim release's fat CPU bundle, reached via the CPU fallback retry."""
slim = select_slim_artifact(manifest, host, backend)
if slim is not None:
return slim
if backend != "cpu":
return None
candidates = _artifacts_for_host(manifest, host, "cpu")
return candidates[0] if candidates else None
def select_artifact_with_cpu_fallback(
manifest: dict[str, Any], host: HostInfo, backend: str
) -> tuple[dict[str, Any], str, bool]:
try:
return core.select_artifact_with_fallback(_OPS, manifest, host, backend)
except PrebuiltFallback as exc:
reason = _slim_release_incompatibility(manifest, host)
if reason is not None:
gap = reason.startswith(_PAIRING_GAP_PREFIX)
raise (LlamaPairingGapError if gap else ReleaseCompatibilityError)(reason) from exc
raise
_LLAMA_BUILD = re.compile(r"^b(\d+)(?:-|$)")
def _llama_build(tag: Any) -> int | None:
match = _LLAMA_BUILD.match(tag) if isinstance(tag, str) else None
return int(match.group(1)) if match else None
def _installed_llama_is_ahead(manifest: dict[str, Any], host: HostInfo) -> bool:
"""Whether every slim bundle this host can run needs an older llama.cpp build than the installed one."""
os_token, arch_token = host_platform_tokens(host)
required = [
_llama_build(artifact.get("requires_llama_tag"))
for artifact in manifest.get("artifacts", [])
if artifact.get("os") == os_token
and artifact.get("arch") == arch_token
and artifact.get("backend") == "slim"
and artifact.get("install_kind") == "slim"
and (not host.is_macos or _macos_min_os_ok(host, artifact.get("min_os")))
]
runtime = installed_llama_runtime()
installed = _llama_build(runtime[1]) if runtime is not None else None
return (
bool(required)
and installed is not None
and all(build is not None and build < installed for build in required)
)
def _slim_release_incompatibility(manifest: dict[str, Any], host: HostInfo) -> str | None:
"""Explains only a valid slim release this runtime cannot pair; missing files, bad manifests,
checksum failures and unsupported platforms are excluded and must never count as
kept-existing success."""
os_token, arch_token = host_platform_tokens(host)
candidates = [
artifact
for artifact in manifest.get("artifacts", [])
if artifact.get("os") == os_token
and artifact.get("arch") == arch_token
and artifact.get("backend") == "slim"
and artifact.get("install_kind") == "slim"
]
if not candidates:
return None
os_compatible = [
artifact
for artifact in candidates
if not host.is_macos or _macos_min_os_ok(host, artifact.get("min_os"))
]
if not os_compatible:
required = candidates[0].get("min_os")
return f"slim bundle requires macOS {required}; this host is older"
runtime = installed_llama_runtime()
if runtime is None:
return None
installed_tag = runtime[1]
installed_tree = installed_llama_ggml_tree()
installed_repo = installed_llama_tree_repo()
# Unhashable tree values (list/dict) would break the set.
required_pairs = {
(
artifact.get("requires_llama_tag"),
artifact["requires_ggml_tree"]
if isinstance(artifact.get("requires_ggml_tree"), str)
else None,
)
for artifact in os_compatible
if isinstance(artifact.get("requires_llama_tag"), str)
}
required_tags = {tag for tag, _tree in required_pairs}
if required_tags and not any(
llama_runtime_pairs(
installed_tag,
tag,
installed_ggml_tree = installed_tree,
required_ggml_tree = tree,
installed_repo = installed_repo,
)
for tag, tree in required_pairs
):
required_tag = sorted(required_tags)[0]
return f"{_PAIRING_GAP_PREFIX}{required_tag}; installed llama.cpp is {installed_tag}"
return None
def select_artifact_with_fallback(
manifest: dict[str, Any], host: HostInfo, backend: str
) -> tuple[dict[str, Any], str, bool]:
return select_artifact_with_cpu_fallback(manifest, host, backend)
# ── Release checksum index (trust anchor: the release's own sha256 asset) ──
def parse_release_checksums(repo: str, release_tag: str, payload: Any) -> dict[str, str]:
return core.parse_release_checksums(_OPS, repo, release_tag, payload)
def fetch_release_checksums(bundle: ReleaseBundle) -> dict[str, str]:
return core.fetch_release_checksums(_OPS, bundle)
def expected_sha256_for(
checksums: dict[str, str],
asset_name: str,
*,
manifest_sha256: str | None = None,
) -> str:
return core.expected_sha256_for(_OPS, checksums, asset_name, manifest_sha256 = manifest_sha256)
# ── Verified download (retries once on checksum mismatch) ──
def download_file_verified(
url: str, destination: Path, *, expected_sha256: str, label: str
) -> None:
core.download_file_verified_strict(
_OPS, url, destination, expected_sha256 = expected_sha256, label = label
)
# ── GitHub release resolution ──
def github_release(repo: str, tag: str) -> dict[str, Any]:
return core.github_release(_OPS, repo, tag, error = PrebuiltFallback)
def fetch_release_bundle(repo: str, release_tag: str) -> ReleaseBundle:
return core.fetch_release_bundle(_OPS, repo, release_tag)
def asset_download_url(bundle: ReleaseBundle, asset_name: str) -> str:
return core.asset_download_url(_OPS, bundle, asset_name)
# ── Download-host fast path (resolve + fetch the JSON assets with no GitHub API) ──
def _download_host_latest_release_tag(repo: str) -> str | None:
return core.download_host_latest_release_tag(_OPS, repo)
def _download_host_json(url: str) -> Any:
return core.fetch_download_host_json(_OPS, url)
def _download_host_json_once(url: str) -> Any:
"""One attempt, for a probe whose failure path is a cheap fallback.
A refused or blackholed host is a retryable URLError, so the default policy
would spend four attempts with backoff per tag before returning the answer
the caller already has a fallback for.
Only the ATTEMPT count is overridden. ``download_bytes`` falls back to
``auth_headers(url)`` when headers are absent, so passing a bare User-Agent
silently dropped auth: a private published repo 404s and the caller drops to
the "-mix-" suffix compare this exists to replace, and an anonymous
huggingface.co fetch shares the per-IP limit that 429s CI fleets."""
data = download_bytes(url, timeout = 30, attempts = 1, headers = auth_headers(url))
return json.loads(data.decode("utf-8"))
def _resolve_release_via_download_host(
repo: str, published_release_tag: str | None
) -> tuple[ReleaseBundle, dict[str, str]] | None:
return core.resolve_release_via_download_host(_OPS, repo, published_release_tag)
# ── Archive extraction (core's guarded extractor + tar exec-bit restore) ──
def extract_archive(archive_path: Path, destination: Path) -> None:
"""Shared guarded extraction, then restore tar exec bits (the extractor writes
plain files; whisper-server must stay executable)."""
core.extract_archive(archive_path, destination)
core.restore_tar_exec_bits(archive_path, destination)
# ── Install layout ──
def server_binary_name(host: HostInfo) -> str:
return "whisper-server.exe" if host.is_windows else "whisper-server"
def runtime_bin_dir(install_dir: Path, host: HostInfo) -> Path:
"""Canonical directory holding whisper-server + its co-located libs."""
if host.is_windows:
return install_dir / "build" / "bin" / "Release"
return install_dir / "build" / "bin"
def whisper_server_path(install_dir: Path, host: HostInfo) -> Path:
return runtime_bin_dir(install_dir, host) / server_binary_name(host)
def installed_server_path(install_dir: Path, host: HostInfo) -> Path:
return whisper_server_path(install_dir, host)
def _locate_server_in_tree(root: Path, host: HostInfo) -> Path:
return core.locate_server_in_tree(_OPS, root, host)
def locate_server_in_tree(root: Path, host: HostInfo) -> Path:
return _locate_server_in_tree(root, host)
def _assemble_install_tree(bundle_root: Path, staged_root: Path, host: HostInfo) -> Path:
"""Lay out staged_root as a full install in build/bin: co-locate everything beside the server
(shared libs, backend kernel subdirs, license) so RUNPATH=$ORIGIN resolves its libs."""
bin_dir = runtime_bin_dir(staged_root, host)
bin_dir.mkdir(parents = True, exist_ok = True)
for entry in sorted(bundle_root.iterdir()):
if entry.name == METADATA_FILENAME:
continue
dest = bin_dir / entry.name
if entry.is_dir() and not entry.is_symlink():
shutil.copytree(entry, dest, symlinks = True)
else:
shutil.copy2(entry, dest, follow_symlinks = False)
server = bin_dir / server_binary_name(host)
if not server.exists():
raise PrebuiltFallback("staged install is missing the whisper-server binary")
if not host.is_windows:
os.chmod(server, server.stat().st_mode | 0o111)
return server
def assemble_install_tree(bundle_root: Path, staged_root: Path, host: HostInfo) -> Path:
return _assemble_install_tree(bundle_root, staged_root, host)
def _validate_staged_server(staged_root: Path, host: HostInfo) -> None:
"""Optional pre-activate smoke test. Gated off by default (see the switch)."""
if not _RUN_STAGED_PREBUILT_VALIDATION:
return
server = whisper_server_path(staged_root, host)
env = os.environ.copy()
bin_dir = str(runtime_bin_dir(staged_root, host))
for var in ("LD_LIBRARY_PATH", "DYLD_LIBRARY_PATH"):
env[var] = bin_dir + (os.pathsep + env[var] if env.get(var) else "")
try:
result = subprocess.run(
[str(server), "--help"],
capture_output = True,
text = True,
encoding = "utf-8",
errors = "replace",
timeout = 60,
env = env,
**llama.windows_hidden_subprocess_kwargs(),
)
except (OSError, subprocess.SubprocessError) as exc:
raise PrebuiltFallback(f"staged whisper-server failed to launch: {exc}") from exc
if result.returncode != 0:
raise PrebuiltFallback(
f"staged whisper-server --help exited {result.returncode}: {result.stderr.strip()}"
)
def validate_staged_server(staged_root: Path, host: HostInfo) -> None:
_validate_staged_server(staged_root, host)
# ── Slim install wiring (llama ggml runtime into the whisper bin dir) ──
def _elf_needed(path: Path) -> set[str] | None:
"""Read ELF DT_NEEDED names when a standard inspection tool is available."""
commands = (("readelf", "-d"), ("objdump", "-p"))
for command in commands:
try:
result = subprocess.run(
[*command, str(path)],
capture_output = True,
text = True,
encoding = "utf-8",
errors = "replace",
timeout = 10,
)
except (OSError, subprocess.SubprocessError):
continue
if result.returncode != 0:
continue
needed: set[str] = set()
for line in result.stdout.splitlines():
match = re.search(r"\(NEEDED\).*\[([^]]+)\]", line)
if match:
needed.add(match.group(1))
continue
match = re.match(r"\s*NEEDED\s+(\S+)", line)
if match:
needed.add(match.group(1))
return needed
return None
def _runtime_library_sources(llama_bin_dir: Path, backend: str | None) -> list[Path]:
patterns = list(SLIM_GGML_LIBRARY_GLOBS)
sources = {
path for pattern in patterns for path in llama_bin_dir.glob(pattern) if path.is_file()
}
if backend == "rocm":
# Windows ROCm: mirror the whole flat DLL closure; transitive DLLs have unrelated names.
windows_dlls = {path for path in llama_bin_dir.glob("*.dll") if path.is_file()}
if windows_dlls:
sources.update(windows_dlls)
return sorted(sources)
# Linux: copy the DT_NEEDED closure; ROCm globs only when ELF tools are missing.
by_name = {path.name: path for path in llama_bin_dir.iterdir() if path.is_file()}
pending = list(sources)
inspected_hip = False
system_libraries = {
"libc.so.6",
"libdl.so.2",
"libgcc_s.so.1",
"libm.so.6",
"libpthread.so.0",
"librt.so.1",
"libstdc++.so.6",
}
while pending:
source = pending.pop()
needed = _elf_needed(source)
if needed is None:
continue
if source.name.startswith("libggml-hip"):
inspected_hip = True
for name in needed - system_libraries:
dependency = by_name.get(name)
if dependency is not None and dependency not in sources:
sources.add(dependency)
pending.append(dependency)
if not inspected_hip:
sources.update(
path
for pattern in SLIM_ROCM_LIBRARY_GLOBS
for path in llama_bin_dir.glob(pattern)
if path.is_file()
)
return sorted(sources)
def _link_or_copy(source: Path, destination: Path) -> None:
destination.parent.mkdir(parents = True, exist_ok = True)
if destination.exists() or destination.is_symlink():
destination.unlink()
try:
os.link(source, destination)
except OSError:
shutil.copy2(source, destination)
def link_ggml_runtime(
llama_bin_dir: Path,
whisper_bin_dir: Path,
*,
backend: str | None = None,
) -> list[str]:
"""Hardlinks (not symlinks) to the llama ggml libraries keep the paired build alive across an
atomic swap of its install dir; copy only where linking is unsupported or crosses devices;
re-run on each install or update to track the pairing; returns sorted names."""
sources = _runtime_library_sources(llama_bin_dir, backend)
if not any(source.name.startswith(("libggml", "ggml")) for source in sources):
raise PrebuiltFallback(
f"no ggml libraries found in {llama_bin_dir} to pair the slim whisper install"
)
whisper_bin_dir.mkdir(parents = True, exist_ok = True)
for source in sources:
# Hardlink to the resolved inode so links survive llama's dir swap.
_link_or_copy(source, whisper_bin_dir / source.name)
return [source.name for source in sources]
def link_runtime_directories(
llama_bin_dir: Path, whisper_bin_dir: Path, *, backend: str, host: HostInfo
) -> list[str]:
"""Mirror GPU kernel catalogs that packaged ROCm libraries load at runtime."""
if backend != "rocm" or host.is_windows:
return []
linked: list[str] = []
for name in SLIM_ROCM_RUNTIME_DIRS:
source_root = llama_bin_dir / name
required = name in SLIM_ROCM_REQUIRED_RUNTIME_DIRS
files = (
[path for path in source_root.rglob("*") if path.is_file()]
if source_root.is_dir()
else []
)
if not files:
if not required:
log(f"slim install: paired ROCm runtime ships no {name} kernel catalog; skipping")
continue
missing = "is missing its" if not source_root.is_dir() else "has an empty"
raise PrebuiltFallback(f"paired ROCm runtime {missing} {name} kernel catalog")
for source in files:
_link_or_copy(source, whisper_bin_dir / name / source.relative_to(source_root))
linked.append(name)
return linked
def prepare_runtime_payload(staged_root: Path, host: HostInfo, selection: Any) -> Any:
"""Slim installs link the paired llama ggml runtime into the staged bin dir before validation
and the returned selection records the wired filenames; fat installs return None."""
if getattr(selection, "install_kind", None) != "slim" or not selection.linked_from:
return None
source = Path(selection.linked_from)
destination = runtime_bin_dir(staged_root, host)
linked = link_ggml_runtime(source, destination, backend = selection.backend)
linked_dirs = link_runtime_directories(
source,
destination,
backend = selection.backend,
host = host,
)
log(f"slim install: hardlinked {len(linked)} ggml libraries from {selection.linked_from}")
return replace(
selection,
linked_libraries = tuple(linked),
runtime_wiring_version = SLIM_RUNTIME_WIRING_VERSION,
linked_runtime_directories = tuple(linked_dirs),
)
# ── Metadata / marker ──
def metadata_path(install_dir: Path) -> Path:
return install_dir / METADATA_FILENAME
# Walk every bin layout: settle_kept_install passes only the install dir.
_RUNTIME_RECORD_BIN_DIRS = (("build", "bin"), ("build", "bin", "Release"))
_RUNTIME_RECORD_SERVER_NAMES = ("whisper-server", "whisper-server.exe")
def _stat_record(path: Path) -> "dict[str, Any] | None":
"""size + mtime_ns for one regular file, or None when it is neither."""
try:
if not path.is_file():
return None
info = path.stat()
except OSError:
return None
return {"size": info.st_size, "mtime_ns": info.st_mtime_ns}
def _runtime_file_records(
install_dir: Path,
linked_libraries: "Iterable[str] | None" = None,
linked_runtime_directories: "Iterable[str] | None" = None,
) -> "dict[str, dict[str, Any]]":
"""What the installed payload is made of, in a form a later run can re-check without
running it.
The same two tiers as the llama installer's runtime_file_records, because the two
halves of a whisper install fail differently:
* whisper-server gets size + sha256. Its bytes decide whether dictation works at
all, and every reuse path keeps an install without ever starting it, so the
digest is what stands in for "it launched once". One small binary is ~10 ms.
* the ggml libraries a slim bundle hardlinks get size + mtime_ns, stat only.
installed_tree_is_intact checks those for EXISTENCE by name, so a
libggml-base.so truncated by a full disk or an interrupted extract passes it --
and on a CUDA or ROCm pairing those libraries are most of the bytes. A size
comparison catches that for the price of a stat; hashing hundreds of MB of
kernels on every update would not be worth it.
* the ROCm kernel catalogs a slim bundle links get size + mtime_ns, recursively.
installed_tree_is_intact asks only that each of those directories hold ANY file
(`rglob("*")`), so a rocblas/ that lost or truncated one TensileLibrary blob and
kept the rest satisfied it, and the keep-existing path then reported an install
whose catalog no longer loads. Stat only, for the same reason as the libraries:
rocblas is hundreds of MB and this runs on every update.
*linked_libraries* and *linked_runtime_directories* come from the slim selection being
installed (or from the marker being backfilled); without them only the binary tier is
recorded, which is what a fat bundle -- and a caller with no wiring in hand -- can
honestly say.
"""
records: dict[str, dict[str, Any]] = {}
for parts in _RUNTIME_RECORD_BIN_DIRS:
bin_dir = install_dir.joinpath(*parts)
for name in linked_libraries or ():
# Bare filenames only: a marker naming ../.. must not escape the install.
if not isinstance(name, str) or not name or Path(name).name != name:
continue
record = _stat_record(bin_dir / name)
if record is not None:
records[(bin_dir / name).relative_to(install_dir).as_posix()] = record
for name in linked_runtime_directories or ():
if not isinstance(name, str) or not name or Path(name).name != name:
continue
runtime_dir = bin_dir / name
if not runtime_dir.is_dir():
continue
for path in sorted(runtime_dir.rglob("*")):
if not path.is_file():
continue
record = _stat_record(path)
if record is not None:
records[path.relative_to(install_dir).as_posix()] = record
# Last, so a server matched by the wiring loop gets the hashed tier.
for name in _RUNTIME_RECORD_SERVER_NAMES:
candidate = bin_dir / name
record = _stat_record(candidate)
if record is None:
continue
try:
record["sha256"] = sha256_file(candidate)
except (OSError, MemoryError) as exc:
# No record at all: a size-only tier would keep a same-size corrupt server.
log(f"could not hash {name} for the runtime record ({exc}); not recording")
return {}
records[candidate.relative_to(install_dir).as_posix()] = record
return records
def runtime_file_records(install_dir: Path, selection: Any) -> "dict[str, dict[str, Any]]":
"""Hook for prebuilt_core.write_prebuilt_metadata that records the staged tree; slim bundles
pass their wired ggml filenames so the marker describes the hardlinks it claims as well as
the server."""
is_slim = getattr(selection, "install_kind", None) == "slim"
linked = selection.linked_libraries if is_slim else None
runtime_dirs = getattr(selection, "linked_runtime_directories", None) if is_slim else None
return _runtime_file_records(install_dir, linked, runtime_dirs)
def _runtime_files_match(install_dir: Path, marker: "dict[str, Any]") -> bool:
"""Whether every recorded payload file is still the file that was installed.
Sizes for everything, digests for the server that carries one (see
_runtime_file_records for why the split). Copied from the llama installer's
_runtime_files_match, including both of its deliberate choices:
* mtime_ns is recorded but deliberately NOT compared. A restore from backup, an
rsync or a container layer rewrites it without changing a byte, and the answer
to a mismatch here is a 200-400 MB re-download.
* it FAILS CLOSED on a record that is present but not a non-empty mapping of
mappings. This is the evidence that replaces actually starting whisper-server,
so a record that cannot be read is not proof of anything.
The one divergence from llama is where "absent" is decided, and backwards
compatibility forces it: every whisper marker already on a user's disk predates this
key, and rejecting those would re-download an install that is perfectly fine. So an
ABSENT record is accepted here and backfilled once, under the install lock, by
settle_kept_install -> _backfill_runtime_file_records. It is
_existing_install_is_intact -- the no-network fast path, which keeps an install
having looked at no bytes at all -- that demands the key and takes the full path once
without it, exactly as it already does for paired_llama_ggml_tree.
"""
if "runtime_files" not in marker:
return True
recorded = marker.get("runtime_files")
if not isinstance(recorded, dict) or not recorded:
log(f"existing install at {install_dir} has an unusable payload record; reinstalling")
return False
for relative, expected in recorded.items():
if not isinstance(expected, dict):
log(f"existing install at {install_dir} has an unusable record for {relative}")
return False
candidate = install_dir / relative
try:
info = candidate.stat()
if info.st_size != expected.get("size"):
log(
f"existing install at {install_dir} rejected: {relative} is "
f"{info.st_size} bytes"
)
return False
digest = expected.get("sha256")
if digest is not None and sha256_file(candidate) != digest:
log(
f"existing install at {install_dir} rejected: {relative} does not match "
f"the recorded digest"
)
return False
except OSError as exc:
log(f"existing install at {install_dir} rejected: {relative} is unreadable ({exc})")
return False
return True
def selection_from_artifact(
*,
published_repo: str,
release_tag: str,
manifest: dict[str, Any],
artifact: dict[str, Any],
backend: str,
asset_sha256: str,
) -> InstallSelection:
selection = core.selection_from_artifact(
_OPS,
published_repo = published_repo,
release_tag = release_tag,
manifest = manifest,
artifact = artifact,
backend = backend,
asset_sha256 = asset_sha256,
)
if artifact.get("install_kind") != "slim":
return selection
runtime = installed_llama_runtime()
if runtime is None or not llama_runtime_pairs(
runtime[1],
artifact.get("requires_llama_tag"),
installed_ggml_tree = installed_llama_ggml_tree(),
required_ggml_tree = artifact.get("requires_ggml_tree"),
installed_repo = installed_llama_tree_repo(),
):
raise PrebuiltFallback(
"the paired llama.cpp runtime changed underneath the slim whisper selection"
)
llama_bin_dir, llama_tag, _profile = runtime
return replace(
selection,
install_kind = "slim",
paired_llama_tag = llama_tag,
linked_from = str(llama_bin_dir),
)
def write_prebuilt_metadata(install_dir: Path, selection: InstallSelection) -> None:
core.write_prebuilt_metadata(_OPS, install_dir, selection)
def load_whisper_prebuilt_metadata(install_dir: Path) -> dict[str, Any] | None:
return core.load_prebuilt_metadata(_OPS, install_dir)
def load_prebuilt_metadata(install_dir: Path) -> dict[str, Any] | None:
return load_whisper_prebuilt_metadata(install_dir)
def existing_install_matches(
install_dir: Path, host: HostInfo, selection: InstallSelection
) -> bool:
"""A marker match counts as current only if the server is executable (the sidecar refuses
non-executable binaries) and slim wired ggml libraries all exist, since a deleted or moved
llama dir breaks dictation while update reports up to date."""
if not core.existing_install_matches(_OPS, install_dir, host, selection):
return False
return installed_tree_is_intact(install_dir, host)
def kept_install_needs_settling(install_dir: Path) -> bool:
"""Whether settle_kept_install has anything to write: a marker with no payload
record, or a slim marker missing either half of its pairing record."""
marker = load_prebuilt_metadata(install_dir)
if not marker:
return False
# Empty counts as absent: an unhashable server yields {}.
if not marker.get("runtime_files"):
return True
if marker.get("install_kind") != "slim":
return False
return not all(
isinstance(marker.get(key), str) and marker.get(key)
for key in ("paired_llama_ggml_tree", "paired_llama_runtime_id")
)
def settle_kept_install(install_dir: Path) -> None:
"""core.install_selected_prebuilt's hook for a kept install, called under the lock.
The backfill is a read-modify-write of the marker. Done from existing_install_matches
it ran once BEFORE the lock, where another installer swapping in a new release
between the read and the replace would have had its fresh marker overwritten with
the old release's fields plus the backfilled tree.
"""
_backfill_slim_pairing_record(install_dir)
_backfill_runtime_file_records(install_dir)
def _backfill_runtime_file_records(install_dir: Path) -> None:
"""Backfills runtime_files on markers from older installs, which would otherwise refetch the
release, manifest and checksums on every update; records what is on disk now, never
overwrites, never downloads, never raises."""
marker = load_prebuilt_metadata(install_dir)
if not marker or marker.get("runtime_files"):
return
is_slim = marker.get("install_kind") == "slim"
linked = marker.get("linked_libraries") if is_slim else None
runtime_dirs = marker.get("linked_runtime_directories") if is_slim else None
records = _runtime_file_records(
install_dir,
linked if isinstance(linked, list) else None,
runtime_dirs if isinstance(runtime_dirs, list) else None,
)
# Writing an empty record would fail closed on every later update.
if not records:
return
marker["runtime_files"] = records
if llama._write_marker(metadata_path(install_dir), marker):
log(f"existing {COMPONENT} install reused; recorded {len(records)} payload files")
def _wiring_matches_live_llama(install_dir: Path, marker: dict) -> bool:
"""Whether this install's wired libraries ARE the live llama runtime's, right now.
Recording a pairing the wiring has not been checked against is how a FALSE one gets
written: the backfill reads whichever llama marker is live at that moment, and a llama
that was replaced before the first migration -- or by another installer holding its own
per-directory lock during this one -- leaves whisper hardlinked to the previous libraries
while the marker claims the new identity. The next fast check then believes it.
_link_or_copy hardlinks, so a shared (st_dev, st_ino) PROVES the two names are one file.
It falls back to shutil.copy2 across filesystems, where the inodes legitimately differ, so
an inode mismatch is not evidence of staleness on its own and the bytes are compared
instead. Unverifiable answers False: recording nothing costs the fast path, recording a
guess costs the install.
"""
linked = marker.get("linked_libraries")
linked_from = marker.get("linked_from")
if not isinstance(linked, list) or not linked or not isinstance(linked_from, str):
return False
source_dir = Path(linked_from)
if not source_dir.is_dir():
return False
bin_dir = installed_server_path(install_dir, detect_host()).parent
checked = 0
for name in linked:
if not isinstance(name, str) or Path(name).name != name:
return False
ours, theirs = bin_dir / name, source_dir / name
try:
a, b = ours.stat(), theirs.stat()
except OSError:
return False
if (a.st_dev, a.st_ino) != (b.st_dev, b.st_ino):
try:
if a.st_size != b.st_size or core.sha256_file(ours) != core.sha256_file(theirs):
return False
except OSError:
return False
checked += 1
return checked > 0
def _backfill_slim_pairing_record(install_dir: Path) -> None:
"""Record the paired llama runtime on a slim marker written before those keys existed.
existing_install_current_without_plan refuses a slim install whose marker cannot say
which llama runtime it hardlinks, so without this an install made before this PR
would fetch the release, its manifest and its checksum index on EVERY update rather
than once. This is the only place that re-examines a slim install without
reinstalling it, and it runs only after the fingerprint and the wiring have just been
confirmed, so what it writes describes a pairing it verified.
Backfilled rather than re-wired on purpose. An older marker records nothing about which
gfx bundle it was paired against, so a swap that already happened cannot be detected
from it at all, and reinstalling every such install to find out would re-download the
bundle for every existing user to answer a question about a swap that almost never
happened. Recording the current pairing makes the NEXT one detectable, which is the
same trade paired_llama_ggml_tree already makes.
Added, never corrected: a marker that already names a pairing was written by a run that
installed against it. Never raises -- the install is already valid, and a read-only
marker must not fail setup over a metadata refresh.
"""
marker = load_prebuilt_metadata(install_dir)
if not marker or marker.get("install_kind") != "slim":
return
# Only record a pairing the wiring proves; otherwise the guess is trusted forever.
if not _wiring_matches_live_llama(install_dir, marker):
log(
f"existing {COMPONENT} install reused; its wiring does not match the live "
"llama.cpp runtime, so no pairing was recorded"
)
return
added: list[str] = []
for key, live in (
("paired_llama_ggml_tree", installed_paired_runtime_tree),
("paired_llama_runtime_id", installed_paired_runtime_id),
):
recorded = marker.get(key)
if isinstance(recorded, str) and recorded:
continue
value = live()
if not value:
continue
marker[key] = value
added.append(f"{key}={value}")
if not added:
return
if llama._write_marker(metadata_path(install_dir), marker):
log(f"existing {COMPONENT} install reused; recorded its pairing ({', '.join(added)})")
def installed_tree_is_intact(install_dir: Path, host: HostInfo) -> bool:
"""The on-disk half of existing_install_matches, without the fingerprint.
Split out so existing_install_current_without_plan -- which runs before anything is
resolved and so has no selection to fingerprint against -- makes exactly the same
demands of the tree. Two copies of these rules is how a fast path comes to accept an
install the slow path repairs.
"""
server = installed_server_path(install_dir, host)
try:
if not server.is_file() or server.stat().st_size == 0:
return False
except OSError:
return False
if not host.is_windows and not os.access(server, os.X_OK):
log(f"existing install at {install_dir} has a non-executable server; reinstalling")
return False
marker = load_prebuilt_metadata(install_dir) or {}
if marker.get("install_kind") == "slim":
bin_dir = server.parent
if marker.get("runtime_wiring_version") != SLIM_RUNTIME_WIRING_VERSION:
log(f"existing slim install at {install_dir} has stale runtime wiring; reinstalling")
return False
linked_libraries = marker.get("linked_libraries")
if (
not isinstance(linked_libraries, list)
or not linked_libraries
or not all(
isinstance(name, str) and name and Path(name).name == name
for name in linked_libraries
)
):
log(f"existing slim install at {install_dir} has invalid runtime wiring; reinstalling")
return False
missing = [name for name in linked_libraries if not (bin_dir / name).is_file()]
if missing:
log(
f"existing slim install at {install_dir} is missing wired ggml "
f"libraries ({', '.join(missing[:4])}); reinstalling"
)
return False
# Per llama install, not tree: a per-gfx ROCm reselection keeps the tree id but swaps kernels.
recorded_runtime_id = marker.get("paired_llama_runtime_id")
if isinstance(recorded_runtime_id, str) and recorded_runtime_id:
if recorded_runtime_id != installed_paired_runtime_id():
log(
f"existing slim install at {install_dir} is wired to a superseded llama "
"runtime; reinstalling"
)
return False
runtime_dirs = marker.get("linked_runtime_directories")
# Subset plus required: a target without hipBLASLt wires rocblas alone.
if (
marker.get("backend") == "rocm"
and not host.is_windows
and (
not isinstance(runtime_dirs, list)
or not set(runtime_dirs) <= set(SLIM_ROCM_RUNTIME_DIRS)
or not set(SLIM_ROCM_REQUIRED_RUNTIME_DIRS) <= set(runtime_dirs)
)
):
log(f"existing ROCm install at {install_dir} lacks kernel catalogs; reinstalling")
return False
missing_dirs = [
name
for name in runtime_dirs or []
if not isinstance(name, str)
or not (bin_dir / name).is_dir()
or not any(path.is_file() for path in (bin_dir / name).rglob("*"))
]
if missing_dirs:
log(
f"existing slim install at {install_dir} is missing runtime directories "
f"({', '.join(str(name) for name in missing_dirs[:4])}); reinstalling"
)
return False
# Only check that reads payload bytes: a truncated server is still a non-empty executable.
return _runtime_files_match(install_dir, marker)
# ── Orchestration ──
def resolve_newest_release_tag(repo: str) -> str:
return core.resolve_newest_release_tag(_OPS, repo)
def resolve_release_tag(published_repo: str, *, published_release_tag: str | None) -> str:
return core.resolve_release_tag(
_OPS, published_repo, published_release_tag = published_release_tag
)
def fetch_release_for_install(
repo: str, *, published_release_tag: str | None
) -> tuple[ReleaseBundle, dict[str, str]]:
try:
return core.fetch_release_for_install(
_OPS, repo, published_release_tag = published_release_tag
)
except PrebuiltFallback:
raise
except (OSError, ValueError, RuntimeError) as exc:
# The keep path catches only PrebuiltFallback.
raise PrebuiltFallback(
f"could not fetch release {repo}@{published_release_tag or 'latest'}: {exc}"
) from exc
@dataclass(frozen = True)
class WhisperReleasePlan:
bundle: ReleaseBundle
selection: InstallSelection | None
artifact: dict[str, Any]
resolved_backend: str
used_fallback: bool
walk_back: core.WalkBack | None = None
def _normalized_upstream_tag(value: str) -> str:
value = value.strip()
return value[1:] if value[:1].lower() == "v" else value
def _bundle_matches_whisper_tag(bundle: ReleaseBundle, whisper_tag: str) -> bool:
requested = whisper_tag.strip()
if not requested or requested.lower() == "latest":
return True
upstream = bundle.manifest.get("upstream_tag")
return isinstance(upstream, str) and _normalized_upstream_tag(
upstream
) == _normalized_upstream_tag(requested)
def _published_release_tags(repo: str) -> list[str]:
"""Published release tags in newest-first order for compatibility search."""
payload = fetch_json(f"https://api.github.com/repos/{repo}/releases?per_page=100")
if not isinstance(payload, list):
raise PrebuiltFallback(f"unexpected releases payload for {repo}")
releases = [
release
for release in payload
if isinstance(release, dict)
and not release.get("draft")
and not release.get("prerelease")
and isinstance(release.get("tag_name"), str)
and release.get("tag_name")
]
releases.sort(key = lambda release: release.get("published_at") or "", reverse = True)
return [str(release["tag_name"]) for release in releases]
def _fetch_release_candidate(repo: str, release_tag: str) -> ReleaseBundle:
"""Fetch one candidate manifest by its deterministic download-host URL."""
manifest_url = release_asset_download_url(repo, release_tag, MANIFEST_ASSET_NAME)
try:
payload = _download_host_json(manifest_url)
manifest = parse_manifest(payload, label = f"{MANIFEST_ASSET_NAME} in {repo}@{release_tag}")
except Exception as exc:
raise PrebuiltFallback(
f"could not read {MANIFEST_ASSET_NAME} from {repo}@{release_tag}: {exc}"
) from exc
asset_names = {MANIFEST_ASSET_NAME, SHA256_ASSET_NAME}
asset_names.update(
str(artifact["asset"])
for artifact in manifest.get("artifacts", [])
if isinstance(artifact, dict) and artifact.get("asset")
)
asset_urls = {name: release_asset_download_url(repo, release_tag, name) for name in asset_names}
return ReleaseBundle(
repo = repo,
release_tag = release_tag,
manifest = manifest,
asset_urls = asset_urls,
)
def _plan_bundle(
host: HostInfo,
bundle: ReleaseBundle,
checksums: dict[str, str],
*,
published_repo: str,
requested_backend: str,
verify_checksums: bool,
) -> WhisperReleasePlan:
artifact, resolved_backend, used_fallback = select_artifact_with_cpu_fallback(
bundle.manifest, host, requested_backend
)
selection = (
plan_selection(
host,
bundle,
published_repo = published_repo,
backend = requested_backend,
checksums = checksums,
)
if verify_checksums
else None
)
return WhisperReleasePlan(
bundle = bundle,
selection = selection,
artifact = artifact,
resolved_backend = resolved_backend,
used_fallback = used_fallback,
)
def _release_plan_for_host(
host: HostInfo,
*,
published_repo: str,
published_release_tag: str | None,
whisper_tag: str,
requested_backend: str,
verify_checksums: bool = True,
) -> WhisperReleasePlan:
"""Select the requested or newest host-compatible published release.
Explicit published release pins never walk. An upstream ``whisper_tag``
searches published manifests for that exact upstream version. An unpinned
macOS install may walk older published releases only when the newest
manifest has no host-compatible artifact. Checksum and archive failures are
outside this search and remain hard failures.
"""
requested_specific_tag = whisper_tag.strip().lower() not in ("", "latest")
first_bundle: ReleaseBundle | None = None
first_error: PrebuiltFallback | None = None
if not requested_specific_tag or published_release_tag:
first_bundle, first_checksums = fetch_release_for_install(
published_repo, published_release_tag = published_release_tag
)
if not _bundle_matches_whisper_tag(first_bundle, whisper_tag):
first_error = PrebuiltFallback(
f"{published_repo}@{first_bundle.release_tag} targets whisper.cpp "
f"{first_bundle.manifest.get('upstream_tag')}, not requested {whisper_tag}"
)
else:
try:
select_artifact_with_cpu_fallback(first_bundle.manifest, host, requested_backend)
except PrebuiltFallback as exc:
first_error = exc
else:
# Integrity failures are never eligible for release walkback.
return _plan_bundle(
host,
first_bundle,
first_checksums,
published_repo = published_repo,
requested_backend = requested_backend,
verify_checksums = verify_checksums,
)
if published_release_tag:
assert first_error is not None
raise first_error
if not requested_specific_tag and not host.is_macos:
assert first_error is not None
raise first_error
if (
not requested_specific_tag
and isinstance(first_error, LlamaPairingGapError)
# Our releases track llama.cpp builds in order; a custom repo's need not, on either side.
and published_repo == DEFAULT_PUBLISHED_REPO
and installed_llama_tree_repo() == llama.DEFAULT_PUBLISHED_REPO
and first_bundle is not None
and _installed_llama_is_ahead(first_bundle.manifest, host)
):
# llama.cpp is published before its paired whisper.cpp release. Until that lands, the newest
# release pairs with an older llama.cpp and older ones with older still, so a walk finds
# nothing and costs a release listing plus two fetches per release on every update.
assert first_error is not None
raise first_error
# An API limit or network failure is "could not answer", which the keep path handles.
try:
compatible_tags = _published_release_tags(published_repo)
except (OSError, RuntimeError) as exc:
raise PrebuiltFallback(f"could not list {published_repo} releases: {exc}") from exc
for release_tag in compatible_tags:
if first_bundle is not None and release_tag == first_bundle.release_tag:
continue
try:
bundle = _fetch_release_candidate(published_repo, release_tag)
except PrebuiltFallback:
continue
if not _bundle_matches_whisper_tag(bundle, whisper_tag):
continue
try:
# Check compatibility before trusting the checksum index: integrity failures must not downgrade.
select_artifact_with_cpu_fallback(bundle.manifest, host, requested_backend)
except PrebuiltFallback:
continue
checksums = fetch_release_checksums(bundle) if verify_checksums else {}
plan = _plan_bundle(
host,
bundle,
checksums,
published_repo = published_repo,
requested_backend = requested_backend,
verify_checksums = verify_checksums,
)
log(
f"selected compatible published release {bundle.release_tag} "
f"(upstream {bundle.manifest.get('upstream_tag')})"
)
walk_back = (
core.walk_back_for(host, first_bundle.release_tag)
if first_bundle is not None and not requested_specific_tag
else None
)
if walk_back is not None:
plan = replace(
plan,
walk_back = walk_back,
selection = (
replace(plan.selection, walk_back = walk_back)
if plan.selection is not None
else None
),
)
return plan
if requested_specific_tag:
raise PrebuiltFallback(
f"no published {COMPONENT} release for upstream tag {whisper_tag} supports this host"
)
assert first_error is not None
raise first_error
def _install_from_bundle(
install_dir: Path, host: HostInfo, bundle: ReleaseBundle, selection: InstallSelection
) -> None:
core.install_from_bundle(_OPS, install_dir, host, bundle, selection)
def plan_selection(
host: HostInfo,
bundle: ReleaseBundle,
*,
published_repo: str,
backend: str,
checksums: dict[str, str],
) -> InstallSelection:
return core.plan_selection(
_OPS,
host,
bundle,
published_repo = published_repo,
backend = backend,
checksums = checksums,
)
def installed_paired_runtime_tree() -> str | None:
"""The ggml tree of the llama runtime a slim bundle would hardlink right now.
Read from the live llama marker, so prebuilt_core can record it beside
paired_llama_tag without knowing anything about llama.cpp.
"""
tree = installed_llama_ggml_tree()
return tree if isinstance(tree, str) and tree else None
def installed_paired_runtime_id(install_dir: "Path | None" = None) -> str | None:
"""Which llama INSTALL the hardlinks point into, not which source tree built it.
ggml_tree cannot answer this: llama publishes a per-gfx ROCm bundle per release, so
re-selecting for another gfx target swaps the asset while the tree id stays put. Its
install_fingerprint covers asset, asset_sha256 and runtime_sha256, so it moves whenever
the bytes behind the hardlinks are superseded.
"""
root = install_dir if install_dir is not None else llama.default_managed_llama_dir()
metadata = llama.load_prebuilt_metadata(root)
if not metadata:
return None
recorded = metadata.get("install_fingerprint")
return recorded if isinstance(recorded, str) and recorded else None
def _existing_install_is_intact(
install_dir: Path, host: HostInfo, *, published_repo: str, requested_backend: str
) -> dict[str, Any] | None:
"""The marker of a whisper.cpp install worth keeping, or None if there is none.
Everything existing_install_current_without_plan can establish WITHOUT asking which
release is newest: that a previous run of this installer finished and wrote the
marker, that it wrote it for this repo and this backend, that a slim install still
hardlinks the llama ggml tree it was wired against, and that the tree on disk is the
shape the marker describes.
Split out because install_prebuilt's failed-lookup path has to make exactly these
demands and no others -- it runs precisely when "is there a newer release" is the one
question nothing can answer -- and a second copy of the remaining rules is how a keep
path comes to hold an install the install path would have repaired.
"""
marker = load_prebuilt_metadata(install_dir)
if not marker:
return None
if marker.get("schema_version") != SCHEMA_VERSION or marker.get("component") != COMPONENT:
return None
if (marker.get("published_repo") or "") != published_repo:
return None
if marker.get("backend") != requested_backend:
return None
# A bundle for another arch is not intact; old markers infer os/arch from the asset name.
os_token, arch_token = host_platform_tokens(host)
recorded_os, recorded_arch = marker.get("os"), marker.get("arch")
if isinstance(recorded_os, str) and isinstance(recorded_arch, str):
if (recorded_os, recorded_arch) != (os_token, arch_token):
return None
else:
recorded_asset = marker.get("asset")
if (
not isinstance(recorded_asset, str)
or f"-{os_token}-{arch_token}-" not in recorded_asset
):
return None
min_os = marker.get("min_os")
coverage = marker.get("coverage")
if min_os is None and isinstance(coverage, dict):
min_os = coverage.get("min_os")
if host.is_macos and min_os is not None:
if not _macos_min_os_ok(host, min_os):
return None
recorded_release = marker.get("release_tag")
if not isinstance(recorded_release, str) or not recorded_release:
return None
recorded_fingerprint = marker.get("install_fingerprint")
if not isinstance(recorded_fingerprint, str) or not recorded_fingerprint:
return None
# Self-consistency guards against a release_tag edited over an old binary.
if core.marker_install_fingerprint(marker) != recorded_fingerprint:
return None
if marker.get("install_kind") == "slim":
recorded_tree = marker.get("paired_llama_ggml_tree")
if not isinstance(recorded_tree, str) or not recorded_tree:
return None
if recorded_tree != installed_llama_ggml_tree():
return None
# Recorded digests are the only evidence here; this path never runs whisper-server.
if not marker.get("runtime_files") or not isinstance(marker.get("runtime_files"), dict):
return None
if not installed_tree_is_intact(install_dir, host):
return None
return marker
_PACKAGING_SUFFIX = "-unsloth."
def _api_newest_release_tag_for_upstream(
repo: str, whisper_tag: str, recorded_release: str
) -> "str | None":
"""The newest published release packaging *whisper_tag* (v1.9.2-unsloth.17, .18, ...).
The release the marker records is known to package it, so it is a candidate too;
the newest of them is what _release_plan_for_host would take.
"""
wanted = _normalized_upstream_tag(whisper_tag)
try:
releases = llama.github_releases(
repo, max_pages = llama.DEFAULT_GITHUB_RELEASE_SCAN_MAX_PAGES
)
except Exception as exc: # noqa: BLE001 - unreachable is a reason to do the work
log(f"could not list the {COMPONENT} releases packaging {whisper_tag} ({exc})")
return None
matching = []
for release in releases:
tag = release.get("tag_name") if isinstance(release, dict) else None
if not isinstance(tag, str):
continue
# The upstream part can contain a hyphen (v1.9.2-rc1).
packaged = _normalized_upstream_tag(tag)
if (
tag == recorded_release
or packaged == wanted
or packaged.startswith(wanted + _PACKAGING_SUFFIX)
):
matching.append(release)
return llama._newest_release_tag_from_releases(repo, matching)
def existing_install_current_without_plan(
install_dir: Path,
host: HostInfo,
*,
whisper_tag: str,
published_repo: str,
published_release_tag: str | None,
requested_backend: str,
) -> bool:
"""Whether the whisper.cpp install on disk is already the one this run would make.
Runs BEFORE _release_plan_for_host, which fetches the release, its manifest and its
checksum index on every update to conclude that nothing moved. Every check is on-disk
evidence or a tag comparison; the one network call is the same HEAD the llama
pre-check makes, and only when the requested tag is "latest".
The slim pairing is what makes this component's version of the check different: a
slim whisper bundle hardlinks the llama runtime's ggml libraries, so a llama install
that moved underneath it invalidates a whisper install whose own release did not.
That half is _existing_install_is_intact, and it runs FIRST, for the reason llama's
pre-check orders its own probes that way: a box whose install is damaged should not
pay a network round trip to learn it must reinstall anyway.
"""
if llama.prebuilt_full_check_requested():
return False
marker = _existing_install_is_intact(
install_dir,
host,
published_repo = published_repo,
requested_backend = requested_backend,
)
if marker is None:
return False
recorded_release = str(marker.get("release_tag"))
pinned = (published_release_tag or "").strip()
requested = (whisper_tag or "latest").strip().lower()
if requested not in ("", "latest"):
if _normalized_upstream_tag(
str(marker.get("upstream_tag") or "")
) != _normalized_upstream_tag(whisper_tag):
return False
if pinned:
if pinned != recorded_release:
return False
elif requested not in ("", "latest"):
# /releases/latest cannot name an older version's newest packaging; custom repos match by manifest.
if published_repo != DEFAULT_PUBLISHED_REPO:
return False
newest = _api_newest_release_tag_for_upstream(published_repo, whisper_tag, recorded_release)
if not newest or newest != recorded_release:
return False
else:
if not llama._download_host_resolve_enabled():
return False
try:
latest = llama._download_host_latest_release_tag(published_repo)
except Exception as exc: # noqa: BLE001 - unreachable is a reason to do the work
log(f"could not resolve the latest {COMPONENT} release without the API ({exc})")
return False
if not latest:
return False
if latest != recorded_release and not core.walk_back_stands(marker, host, latest):
return False
# "already matches" is the substring setup.sh and setup.ps1 grep for.
log(
f"existing {COMPONENT} install already matches {recorded_release} "
f"({marker.get('backend')}); nothing to do"
)
return True
def install_prebuilt(
install_dir: Path,
*,
whisper_tag: str = "latest",
published_repo: str = DEFAULT_PUBLISHED_REPO,
published_release_tag: str | None = None,
backend: str | None = "auto",
has_rocm: bool = False,
rocm_gfx: str | None = None,
cpu_fallback: bool = False,
force: bool = False,
) -> int:
host = apply_host_overrides(
detect_host(), has_rocm = has_rocm, rocm_gfx = rocm_gfx, force_cpu = cpu_fallback
)
requested_backend = resolve_backend(host, backend, cpu_fallback = cpu_fallback)
os_token, arch_token = host_platform_tokens(host)
log(
f"target {COMPONENT} from {published_repo} "
f"({os_token}-{arch_token}, backend {requested_backend})"
)
if not force and existing_install_current_without_plan(
install_dir,
host,
whisper_tag = whisper_tag,
published_repo = published_repo,
published_release_tag = published_release_tag,
requested_backend = requested_backend,
):
return 0
try:
plan = _release_plan_for_host(
host,
published_repo = published_repo,
published_release_tag = published_release_tag,
whisper_tag = whisper_tag,
requested_backend = requested_backend,
)
except (ReleaseCompatibilityError, core.ReleaseIntegrityError):
# Compatibility and integrity errors are real answers; never report a tamper signal as 'kept'.
raise
except PrebuiltFallback as exc:
# A lookup that could not answer keeps the tree, unless this run explicitly asked for something.
# UNSLOTH_WHISPER_FORCE_COMPILE counts: setup.sh source-builds only after a nonzero exit.
explicit_release_request = (
force
or bool((published_release_tag or "").strip())
or (whisper_tag or "latest").strip().lower() not in ("", "latest")
or os.environ.get("UNSLOTH_WHISPER_FORCE_COMPILE", "").strip() == "1"
)
marker = (
None
if explicit_release_request
else _existing_install_is_intact(
install_dir,
host,
published_repo = published_repo,
requested_backend = requested_backend,
)
)
if marker is None:
raise
# "keeping the existing complete install" is the substring setup.sh and setup.ps1 grep for.
log(
f"{COMPONENT} update unavailable, existing prebuilt kept; keeping the "
f"existing complete install of {marker.get('release_tag')}"
)
# llama.cpp's wording, so update_flow reads both installers alike.
log_lines(f"prebuilt update reason: {exc}".splitlines())
return EXIT_SUCCESS
if plan.selection is None: # pragma: no cover - install plans always verify
raise PrebuiltFallback("install plan did not validate its checksum entry")
return core.install_selected_prebuilt(
_OPS,
install_dir,
host = host,
bundle = plan.bundle,
selection = plan.selection,
force = force,
)
def resolver_payload_extra(artifact: dict[str, Any]) -> dict[str, Any]:
"""Additive --resolve-prebuilt field: whether the selected asset installs
slim (paired with the llama ggml runtime) or fat (self-contained)."""
return {"install_kind": "slim" if artifact.get("install_kind") == "slim" else "fat"}
def unavailable_payload(published_repo: str, exc: BaseException) -> dict[str, Any]:
"""The resolver's negative answer, carrying WHY: the same split the install path
makes (ReleaseCompatibilityError is exit 2, everything else exit 1). Flattened, a
caller cannot tell a confirmed pairing gap from a probe that never answered."""
return {
"prebuilt_available": False,
"repo": published_repo,
"unavailable_reason": (
"incompatible" if isinstance(exc, ReleaseCompatibilityError) else "unresolved"
),
}
def resolve_prebuilt(
host: HostInfo,
*,
published_repo: str,
published_release_tag: str | None,
whisper_tag: str = "latest",
backend: str | None,
cpu_fallback: bool,
) -> dict[str, Any]:
requested_backend = resolve_backend(host, backend, cpu_fallback = cpu_fallback)
try:
plan = _release_plan_for_host(
host,
published_repo = published_repo,
published_release_tag = published_release_tag,
whisper_tag = whisper_tag,
requested_backend = requested_backend,
verify_checksums = False,
)
except PrebuiltFallback as exc:
return unavailable_payload(published_repo, exc)
os_token, arch_token = host_platform_tokens(host)
payload = {
"prebuilt_available": True,
"repo": published_repo,
"release_tag": plan.bundle.release_tag,
"upstream_tag": plan.bundle.manifest.get("upstream_tag"),
"backend": plan.resolved_backend,
"requested_backend": requested_backend,
"cpu_fallback": plan.used_fallback,
"asset": str(plan.artifact.get("asset")),
"os": os_token,
"arch": arch_token,
"runtime_line": plan.artifact.get("runtime_line"),
}
payload.update(resolver_payload_extra(plan.artifact))
return payload
DESCRIPTOR = core.ComponentDescriptor(
component = COMPONENT,
log_prefix = "whisper-prebuilt",
published_repo = DEFAULT_PUBLISHED_REPO,
manifest_asset_name = MANIFEST_ASSET_NAME,
sha256_asset_name = SHA256_ASSET_NAME,
metadata_filename = METADATA_FILENAME,
user_agent = USER_AGENT,
supported_backends = SUPPORTED_BACKENDS,
schema_version = SCHEMA_VERSION,
fallback_backend = FALLBACK_BACKEND,
detect_host = detect_host,
host_platform_tokens = host_platform_tokens,
server_binary_name = server_binary_name,
runtime_bin_dir = runtime_bin_dir,
)
def build_arg_parser() -> argparse.ArgumentParser:
parser = argparse.ArgumentParser(
description = "Install a prebuilt whisper.cpp (whisper-server) for Unsloth Studio"
)
parser.add_argument(
"--install-dir",
default = None,
help = (
"managed whisper.cpp directory, e.g. <UNSLOTH_HOME>/whisper.cpp. Required for an "
"install; omit it only with --resolve-prebuilt (a read-only probe)."
),
)
parser.add_argument(
"--whisper-tag",
default = os.environ.get("UNSLOTH_WHISPER_TAG", "latest"),
help = "upstream whisper.cpp tag hint (default 'latest' or $UNSLOTH_WHISPER_TAG)",
)
parser.add_argument(
"--published-repo",
default = DEFAULT_PUBLISHED_REPO,
help = f"GitHub repo publishing the prebuilt releases (default {DEFAULT_PUBLISHED_REPO})",
)
parser.add_argument(
"--published-release-tag",
default = os.environ.get("UNSLOTH_WHISPER_RELEASE_TAG") or None,
help = "explicit release tag to install (default: the newest published release)",
)
parser.add_argument(
"--backend",
default = os.environ.get("UNSLOTH_WHISPER_BACKEND", "auto"),
choices = ("auto", *SUPPORTED_BACKENDS),
help = "accelerator backend; 'auto' detects from hardware",
)
parser.add_argument("--has-rocm", action = "store_true", help = "treat this host as ROCm-capable")
parser.add_argument("--rocm-gfx", default = None, help = "ROCm gfx target override, e.g. gfx1100")
parser.add_argument(
"--cpu-fallback", action = "store_true", help = "force the CPU asset regardless of hardware"
)
parser.add_argument(
"--resolve-prebuilt",
nargs = "?",
const = "latest",
default = None,
help = "report whether a prebuilt exists for this host without downloading",
)
parser.add_argument(
"--output-format",
choices = ("plain", "json"),
default = "plain",
help = "resolver output format (default plain)",
)
parser.add_argument(
"--force", action = "store_true", help = "reinstall even if the install already matches"
)
return parser
def main(argv: list[str] | None = None) -> int:
global _LOG_TO_STDOUT
parser = build_arg_parser()
args = parser.parse_args(argv)
if args.resolve_prebuilt is not None:
_LOG_TO_STDOUT = False
try:
host = apply_host_overrides(
detect_host(),
has_rocm = args.has_rocm,
rocm_gfx = args.rocm_gfx,
force_cpu = args.cpu_fallback,
)
payload = resolve_prebuilt(
host,
published_repo = args.published_repo,
published_release_tag = args.published_release_tag,
whisper_tag = args.resolve_prebuilt,
backend = args.backend,
cpu_fallback = args.cpu_fallback,
)
except PrebuiltFallback as exc:
payload = unavailable_payload(args.published_repo, exc)
except Exception as exc: # noqa: BLE001 - probe must never crash the caller
log(f"resolve failed: {exc}")
payload = unavailable_payload(args.published_repo, exc)
emit_resolver_output(payload, output_format = args.output_format)
return EXIT_SUCCESS
_LOG_TO_STDOUT = True
if not args.install_dir:
parser.error("--install-dir is required unless --resolve-prebuilt is used")
install_dir = Path(args.install_dir).expanduser().resolve()
try:
return install_prebuilt(
install_dir,
whisper_tag = args.whisper_tag,
published_repo = args.published_repo,
published_release_tag = args.published_release_tag,
backend = args.backend,
has_rocm = args.has_rocm,
rocm_gfx = args.rocm_gfx,
cpu_fallback = args.cpu_fallback,
force = args.force,
)
except BusyInstallConflict as exc:
log(str(exc))
return EXIT_BUSY
except ReleaseCompatibilityError as exc:
log(f"incompatible release: {exc}")
return EXIT_INCOMPATIBLE
except PrebuiltFallback as exc:
log_lines(f"prebuilt install failed: {exc}".splitlines())
return EXIT_ERROR
except Exception as exc: # noqa: BLE001
log(f"unexpected error: {exc}")
return EXIT_ERROR
if __name__ == "__main__":
raise SystemExit(main())