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
# SPDX-License-Identifier: AGPL-3.0-only
# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
"""Component-agnostic prebuilt_core tests run against whisper's and a llama-flavored descriptor."""
import contextlib
import http.client
import importlib.util
import io
import json
import sys
import tarfile
import urllib.error
import zipfile
from pathlib import Path
from types import SimpleNamespace
import pytest
PACKAGE_ROOT = Path(__file__).resolve().parents[3]
STUDIO_DIR = PACKAGE_ROOT / "studio"
if str(STUDIO_DIR) not in sys.path:
sys.path.insert(0, str(STUDIO_DIR))
SPEC = importlib.util.spec_from_file_location(
"studio_prebuilt_core", STUDIO_DIR / "prebuilt_core.py"
)
assert SPEC is not None and SPEC.loader is not None
core = importlib.util.module_from_spec(SPEC)
sys.modules[SPEC.name] = core
SPEC.loader.exec_module(core)
WSPEC = importlib.util.spec_from_file_location(
"studio_install_whisper_prebuilt_for_core", STUDIO_DIR / "install_whisper_prebuilt.py"
)
assert WSPEC is not None and WSPEC.loader is not None
iwp = importlib.util.module_from_spec(WSPEC)
sys.modules[WSPEC.name] = iwp
WSPEC.loader.exec_module(iwp)
LLAMA_DESCRIPTOR = core.ComponentDescriptor(
component = "llama.cpp",
log_prefix = "llama-prebuilt",
published_repo = "unslothai/llama.cpp",
manifest_asset_name = "llama-prebuilt-manifest.json",
sha256_asset_name = "llama-prebuilt-sha256.json",
metadata_filename = "UNSLOTH_LLAMA_PREBUILT_INFO.json",
user_agent = "unsloth-studio-llama-prebuilt",
# A GPU-selection miss reports 'no prebuilt' so the caller source-builds instead of using CPU.
fallback_backend = None,
server_binary_name = lambda host: "llama-server",
runtime_bin_dir = lambda install_dir, host: install_dir / "build" / "bin",
)
class Component:
"""One descriptor under test plus the mutable namespace behind its ops."""
def __init__(self, descriptor):
self.descriptor = descriptor
self.namespace = core.component_namespace(descriptor)
self.namespace["log"] = lambda message: None
self.ops = core.ModuleOps(self.namespace)
@property
def falls_back_to_cpu(self):
return self.descriptor.fallback_backend == "cpu"
@pytest.fixture(params = ["whisper", "llama"])
def component(request):
if request.param == "whisper":
return Component(iwp.DESCRIPTOR)
return Component(LLAMA_DESCRIPTOR)
def make_host(
component,
*,
os_token = "linux",
arch_token = "x64",
is_windows = False,
is_macos = False,
is_apple_silicon = False,
has_usable_nvidia = False,
has_rocm = False,
rocm_gfx = None,
macos_version = None,
):
if component.descriptor is iwp.DESCRIPTOR:
return iwp.HostInfo(
system = {"linux": "Linux", "macos": "Darwin", "windows": "Windows"}[os_token],
machine = "x86_64" if arch_token == "x64" else "arm64",
whisper_os = os_token,
whisper_arch = arch_token,
archive_ext = ".zip" if is_windows else ".tar.gz",
is_windows = is_windows,
is_macos = is_macos,
is_apple_silicon = is_apple_silicon,
has_usable_nvidia = has_usable_nvidia,
has_rocm = has_rocm,
rocm_gfx = rocm_gfx,
macos_version = macos_version,
)
# Descriptor-only component: the default host_platform_tokens hook reads .os_token/.arch_token.
return SimpleNamespace(
os_token = os_token,
arch_token = arch_token,
is_windows = is_windows,
is_macos = is_macos,
is_apple_silicon = is_apple_silicon,
has_usable_nvidia = has_usable_nvidia,
has_rocm = has_rocm,
rocm_gfx = rocm_gfx,
macos_version = macos_version,
)
def artifact(
os_ = "linux",
arch = "x64",
backend = "cpu",
asset = "bundle.tar.gz",
**extra,
):
payload = {"os": os_, "arch": arch, "backend": backend, "asset": asset}
payload.update(extra)
return payload
def manifest_for(component, artifacts, **extra):
payload = {
"schema_version": 1,
"component": extra.pop("component_name", component.descriptor.component),
"upstream_tag": "v1.0.0",
"source_commit": "a" * 40,
"artifacts": artifacts,
}
payload.update(extra)
return payload
def test_parse_manifest_normalizes(component):
manifest = component.ops.parse_manifest(
manifest_for(component, [artifact(), "not-a-dict", {"os": "linux"}]), label = "m"
)
assert manifest["component"] == component.descriptor.component
assert manifest["upstream_tag"] == "v1.0.0"
assert [a["asset"] for a in manifest["artifacts"]] == ["bundle.tar.gz"]
def test_parse_manifest_rejects_wrong_component(component):
with pytest.raises(core.PrebuiltFallback):
component.ops.parse_manifest(
manifest_for(component, [artifact()], component_name = "other.cpp"), label = "m"
)
def test_parse_manifest_rejects_unknown_schema(component):
with pytest.raises(core.PrebuiltFallback):
component.ops.parse_manifest(
manifest_for(component, [artifact()], schema_version = 99), label = "m"
)
def test_parse_manifest_rejects_non_object(component):
with pytest.raises(core.PrebuiltFallback):
component.ops.parse_manifest(["nope"], label = "m")
with pytest.raises(core.PrebuiltFallback):
component.ops.parse_manifest(
{"schema_version": 1, "component": component.descriptor.component}, label = "m"
)
def test_select_cpu_first_match(component):
manifest = component.ops.parse_manifest(
manifest_for(
component,
[
artifact(backend = "cpu", asset = "first-cpu.tar.gz"),
artifact(backend = "cpu", asset = "second-cpu.tar.gz"),
],
),
label = "m",
)
host = make_host(component)
chosen = component.ops.select_artifact(manifest, host, "cpu")
assert chosen["asset"] == "first-cpu.tar.gz"
def test_select_respects_os_arch(component):
manifest = component.ops.parse_manifest(
manifest_for(component, [artifact(os_ = "windows", backend = "cpu")]), label = "m"
)
host = make_host(component)
assert component.ops.select_artifact(manifest, host, "cpu") is None
def test_fallback_policy_differs_per_descriptor(component):
# No asset for the backend: whisper degrades to CPU; the llama-flavored descriptor reports none.
manifest = component.ops.parse_manifest(
manifest_for(component, [artifact(backend = "cpu", asset = "cpu.tar.gz")]), label = "m"
)
host = make_host(component, has_usable_nvidia = True)
assert component.ops.select_artifact(manifest, host, "cuda") is None
if component.falls_back_to_cpu:
chosen, backend, used_fallback = component.ops.select_artifact_with_fallback(
manifest, host, "cuda"
)
assert (chosen["asset"], backend, used_fallback) == ("cpu.tar.gz", "cpu", True)
else:
with pytest.raises(core.PrebuiltFallback):
component.ops.select_artifact_with_fallback(manifest, host, "cuda")
def test_macos_min_os_gate(component):
manifest = component.ops.parse_manifest(
manifest_for(
component,
[
artifact(
os_ = "macos",
arch = "arm64",
backend = "metal",
asset = "metal-new.tar.gz",
min_os = "macos-15.0",
)
],
),
label = "m",
)
old_host = make_host(
component,
os_token = "macos",
arch_token = "arm64",
is_macos = True,
is_apple_silicon = True,
macos_version = (14, 7),
)
new_host = make_host(
component,
os_token = "macos",
arch_token = "arm64",
is_macos = True,
is_apple_silicon = True,
macos_version = (15, 1),
)
assert component.ops.select_artifact(manifest, old_host, "metal") is None
chosen = component.ops.select_artifact(manifest, new_host, "metal")
assert chosen["asset"] == "metal-new.tar.gz"
def _metal_artifact(asset, min_os):
return artifact(
os_ = "macos",
arch = "arm64",
backend = "metal",
asset = asset,
min_os = min_os,
)
def _arm_mac_host(component, macos_version):
return make_host(
component,
os_token = "macos",
arch_token = "arm64",
is_macos = True,
is_apple_silicon = True,
macos_version = macos_version,
)
def test_macos_min_os_filters_to_compatible_bundle(component):
manifest = component.ops.parse_manifest(
manifest_for(
component,
[
_metal_artifact("metal-new.tar.gz", "macos-15.0"),
_metal_artifact("metal.tar.gz", "macos-13.0"),
],
),
label = "m",
)
host = _arm_mac_host(component, (14, 0))
assert component.ops.select_artifact(manifest, host, "metal")["asset"] == "metal.tar.gz"
def test_macos_min_os_unknown_host_version_keeps_artifact(component):
# Unknown host macOS version -> defer to runtime validation, don't reject.
manifest = component.ops.parse_manifest(
manifest_for(component, [_metal_artifact("metal-new.tar.gz", "macos-15.0")]), label = "m"
)
host = _arm_mac_host(component, None)
assert component.ops.select_artifact(manifest, host, "metal")["asset"] == "metal-new.tar.gz"
def test_macos_min_os_accepts_bare_version_format(component):
# A bare "14.0" (no 'macos-' prefix) must still parse, for forward-compat.
manifest = component.ops.parse_manifest(
manifest_for(component, [_metal_artifact("metal.tar.gz", "14.0")]), label = "m"
)
host = _arm_mac_host(component, (13, 0))
assert component.ops.select_artifact(manifest, host, "metal") is None # 13.0 < 14.0
def test_macos_min_os_ok_helper_handles_prefix_and_bare(component):
host14 = _arm_mac_host(component, (14, 0))
# The live manifest format is 'macos-<ver>'; the prefix must be stripped.
assert component.ops.macos_min_os_ok(host14, "macos-14.0") is True
assert component.ops.macos_min_os_ok(host14, "macos-15.0") is False
assert component.ops.macos_min_os_ok(host14, "13.3") is True
assert component.ops.macos_min_os_ok(host14, None) is True
host_unknown = _arm_mac_host(component, None)
assert component.ops.macos_min_os_ok(host_unknown, "macos-15.0") is True
def test_resolve_backend_auto_and_validation(component):
gpu_host = make_host(component, has_usable_nvidia = True)
assert component.ops.resolve_backend(gpu_host, "auto", cpu_fallback = False) == "cuda"
assert component.ops.resolve_backend(gpu_host, "auto", cpu_fallback = True) == "cpu"
assert component.ops.resolve_backend(gpu_host, "cuda", cpu_fallback = True) == "cpu"
assert component.ops.resolve_backend(gpu_host, "vulkan", cpu_fallback = False) == "vulkan"
mac_host = make_host(
component, os_token = "macos", arch_token = "arm64", is_macos = True, is_apple_silicon = True
)
assert component.ops.resolve_backend(mac_host, None, cpu_fallback = False) == "metal"
# Intel mac has no Metal bundle in the P0 matrix -> cpu.
intel_mac = make_host(component, os_token = "macos", arch_token = "x64", is_macos = True)
assert component.ops.resolve_backend(intel_mac, "auto", cpu_fallback = False) == "cpu"
rocm_host = make_host(component, has_rocm = True, rocm_gfx = "gfx1100")
assert component.ops.resolve_backend(rocm_host, "auto", cpu_fallback = False) == "rocm"
bare_host = make_host(component)
assert component.ops.resolve_backend(bare_host, None, cpu_fallback = False) == "cpu"
with pytest.raises(core.PrebuiltFallback):
component.ops.resolve_backend(gpu_host, "tpu", cpu_fallback = False)
def _index_for(
component,
tag = "v1",
artifacts = None,
):
return {
"schema_version": 1,
"component": component.descriptor.component,
"release_tag": tag,
"artifacts": artifacts
if artifacts is not None
else {"bundle.tar.gz": {"sha256": "0" * 64}},
}
def test_parse_release_checksums_valid(component):
out = component.ops.parse_release_checksums("r", "v1", _index_for(component))
assert out == {"bundle.tar.gz": "0" * 64}
@pytest.mark.parametrize(
"mutation",
[
{"component": "other.cpp"},
{"schema_version": 99},
{"release_tag": "v2"},
{"artifacts": {"bundle.tar.gz": {"sha256": "nope"}}},
{"artifacts": "not-a-map"},
],
)
def test_parse_release_checksums_fails_closed(component, mutation):
payload = _index_for(component)
payload.update(mutation)
with pytest.raises(core.PrebuiltFallback):
component.ops.parse_release_checksums("r", "v1", payload)
def test_parse_release_checksums_rejects_non_object(component):
with pytest.raises(core.PrebuiltFallback):
component.ops.parse_release_checksums("r", "v1", ["not", "a", "dict"])
def test_expected_sha256_covered_asset_plain_lookup(component):
assert component.ops.expected_sha256_for({"a.tar.gz": "0" * 64}, "a.tar.gz") == "0" * 64
def test_expected_sha256_missing_asset_fails_closed(component):
with pytest.raises(core.PrebuiltFallback):
component.ops.expected_sha256_for({"a.tar.gz": "0" * 64}, "b.tar.gz")
def test_expected_sha256_manifest_disagreement_fails_closed(component):
with pytest.raises(core.PrebuiltFallback):
component.ops.expected_sha256_for(
{"a.tar.gz": "0" * 64}, "a.tar.gz", manifest_sha256 = "1" * 64
)
assert (
component.ops.expected_sha256_for(
{"a.tar.gz": "0" * 64}, "a.tar.gz", manifest_sha256 = "0" * 64
)
== "0" * 64
)
def test_extract_archive_rejects_traversal(tmp_path):
archive = tmp_path / "evil.tar.gz"
with tarfile.open(archive, "w:gz") as tar:
data = b"x"
info = tarfile.TarInfo("../escape.txt")
info.size = len(data)
tar.addfile(info, io.BytesIO(data))
with pytest.raises(core.PrebuiltFallback):
core.extract_archive(archive, tmp_path / "out")
def test_extract_archive_rejects_absolute_member(tmp_path):
archive = tmp_path / "abs.tar.gz"
with tarfile.open(archive, "w:gz") as tar:
data = b"x"
info = tarfile.TarInfo("/abs.txt")
info.size = len(data)
tar.addfile(info, io.BytesIO(data))
with pytest.raises(core.PrebuiltFallback):
core.extract_archive(archive, tmp_path / "out")
def test_extract_archive_rejects_zip_symlink(tmp_path):
archive = tmp_path / "link.zip"
with zipfile.ZipFile(archive, "w") as zf:
info = zipfile.ZipInfo("link")
info.create_system = 3
info.external_attr = 0o120777 << 16
zf.writestr(info, "target")
with pytest.raises(core.PrebuiltFallback, match = "zip archive contained a symlink entry"):
core.extract_archive(archive, tmp_path / "out")
def test_extract_archive_rejects_absolute_zip_member(tmp_path):
archive = tmp_path / "abs.zip"
with zipfile.ZipFile(archive, "w") as zf:
zf.writestr("/etc/passwd", b"pwn")
with pytest.raises(core.PrebuiltFallback):
core.extract_archive(archive, tmp_path / "out")
def test_extract_archive_allows_safe_tar_symlink_chain(tmp_path):
archive = tmp_path / "bundle.tar.gz"
payload = b"shared-object"
with tarfile.open(archive, "w:gz") as tar:
versioned = tarfile.TarInfo("libllama.so.0.0.1")
versioned.size = len(payload)
tar.addfile(versioned, io.BytesIO(payload))
soname = tarfile.TarInfo("libllama.so.0")
soname.type = tarfile.SYMTYPE
soname.linkname = "libllama.so.0.0.1"
tar.addfile(soname)
linker_name = tarfile.TarInfo("libllama.so")
linker_name.type = tarfile.SYMTYPE
linker_name.linkname = "libllama.so.0"
tar.addfile(linker_name)
destination = tmp_path / "extract"
core.extract_archive(archive, destination)
assert (destination / "libllama.so.0.0.1").read_bytes() == payload
assert (destination / "libllama.so.0").is_symlink()
assert (destination / "libllama.so").is_symlink()
assert (destination / "libllama.so").resolve().read_bytes() == payload
def test_extract_archive_allows_safe_tar_hardlink(tmp_path):
archive = tmp_path / "bundle.tar.gz"
payload = b"quantize"
with tarfile.open(archive, "w:gz") as tar:
target = tarfile.TarInfo("llama-quantize")
target.size = len(payload)
tar.addfile(target, io.BytesIO(payload))
hardlink = tarfile.TarInfo("llama-quantize-copy")
hardlink.type = tarfile.LNKTYPE
hardlink.linkname = "llama-quantize"
tar.addfile(hardlink)
destination = tmp_path / "extract"
core.extract_archive(archive, destination)
assert (destination / "llama-quantize-copy").read_bytes() == payload
assert not (destination / "llama-quantize-copy").is_symlink()
def test_extract_archive_rejects_absolute_tar_symlink_target(tmp_path):
archive = tmp_path / "bundle.tar.gz"
with tarfile.open(archive, "w:gz") as tar:
entry = tarfile.TarInfo("libllama.so")
entry.type = tarfile.SYMTYPE
entry.linkname = "/tmp/libllama.so.0"
tar.addfile(entry)
with pytest.raises(core.PrebuiltFallback, match = "archive link used an absolute target"):
core.extract_archive(archive, tmp_path / "extract")
def test_extract_archive_rejects_escaping_tar_symlink_target(tmp_path):
archive = tmp_path / "bundle.tar.gz"
with tarfile.open(archive, "w:gz") as tar:
entry = tarfile.TarInfo("libllama.so")
entry.type = tarfile.SYMTYPE
entry.linkname = "../outside/libllama.so.0"
tar.addfile(entry)
with pytest.raises(core.PrebuiltFallback, match = "archive link escaped destination"):
core.extract_archive(archive, tmp_path / "extract")
def test_extract_archive_rejects_unresolved_tar_symlink_target(tmp_path):
archive = tmp_path / "bundle.tar.gz"
with tarfile.open(archive, "w:gz") as tar:
entry = tarfile.TarInfo("libllama.so")
entry.type = tarfile.SYMTYPE
entry.linkname = "libllama.so.0"
tar.addfile(entry)
with pytest.raises(core.PrebuiltFallback, match = "unresolved link entries"):
core.extract_archive(archive, tmp_path / "extract")
def test_extract_archive_rejects_unknown_format(tmp_path):
archive = tmp_path / "blob.xz"
archive.write_bytes(b"data")
with pytest.raises(core.PrebuiltFallback):
core.extract_archive(archive, tmp_path / "out")
def test_restore_tar_exec_bits(tmp_path):
payload = tmp_path / "server"
payload.write_bytes(b"#!/bin/sh\n")
payload.chmod(0o755)
archive = tmp_path / "bundle.tar.gz"
with tarfile.open(archive, "w:gz") as tar:
tar.add(payload, arcname = "bundle/server")
out = tmp_path / "out"
core.extract_archive(archive, out)
extracted = out / "bundle" / "server"
assert extracted.is_file()
core.restore_tar_exec_bits(archive, out)
assert extracted.stat().st_mode & 0o111
def _fake_release(component, artifacts):
ns = component.namespace
manifest = component.ops.parse_manifest(manifest_for(component, artifacts), label = "m")
bundle = core.ReleaseBundle(
repo = component.descriptor.published_repo,
release_tag = "v1",
manifest = manifest,
asset_urls = {},
)
checksums = {str(a["asset"]): "0" * 64 for a in artifacts}
ns["fetch_release_for_install"] = lambda repo, *, published_release_tag: (bundle, checksums)
return bundle
def test_resolve_prebuilt_payload_keys(component):
_fake_release(component, [artifact(backend = "cpu", asset = "cpu.tar.gz")])
host = make_host(component)
payload = component.ops.resolve_prebuilt(
host,
published_repo = component.descriptor.published_repo,
published_release_tag = None,
backend = "cpu",
cpu_fallback = True,
)
assert payload == {
"prebuilt_available": True,
"repo": component.descriptor.published_repo,
"release_tag": "v1",
"upstream_tag": "v1.0.0",
"backend": "cpu",
"requested_backend": "cpu",
"cpu_fallback": False,
"asset": "cpu.tar.gz",
"os": "linux",
"arch": "x64",
"runtime_line": None,
}
def test_resolve_prebuilt_unavailable_payload(component):
ns = component.namespace
def boom(repo, *, published_release_tag):
raise core.PrebuiltFallback("no release")
ns["fetch_release_for_install"] = boom
host = make_host(component)
payload = component.ops.resolve_prebuilt(
host,
published_repo = component.descriptor.published_repo,
published_release_tag = None,
backend = "cpu",
cpu_fallback = True,
)
assert payload == {"prebuilt_available": False, "repo": component.descriptor.published_repo}
def test_emit_resolver_output_formats(capsys):
payload = {"prebuilt_available": True, "asset": "a.tar.gz"}
core.emit_resolver_output(payload, output_format = "json")
assert json.loads(capsys.readouterr().out) == payload
core.emit_resolver_output(payload, output_format = "plain")
assert capsys.readouterr().out.strip() == "a.tar.gz"
core.emit_resolver_output({"prebuilt_available": False}, output_format = "plain")
assert json.loads(capsys.readouterr().out) == {"prebuilt_available": False}
def test_install_fingerprint_is_stable_and_sensitive(component):
kwargs = dict(
published_repo = component.descriptor.published_repo,
release_tag = "v1",
upstream_tag = "v1.0.0",
source_commit = "a" * 40,
asset = "cpu.tar.gz",
asset_sha256 = "0" * 64,
backend = "cpu",
runtime_line = None,
coverage = {},
)
first = core.compute_install_fingerprint(**kwargs)
assert first == core.compute_install_fingerprint(**kwargs)
changed = core.compute_install_fingerprint(**{**kwargs, "asset_sha256": "1" * 64})
assert changed != first
def test_write_and_match_marker(component, tmp_path):
host = make_host(component)
install_dir = tmp_path / "install"
manifest = component.ops.parse_manifest(
manifest_for(component, [artifact(backend = "cpu", asset = "cpu.tar.gz")]), label = "m"
)
selection = component.ops.selection_from_artifact(
published_repo = component.descriptor.published_repo,
release_tag = "v1",
manifest = manifest,
artifact = manifest["artifacts"][0],
backend = "cpu",
asset_sha256 = "0" * 64,
)
assert not component.ops.existing_install_matches(install_dir, host, selection)
bin_dir = component.ops.runtime_bin_dir(install_dir, host)
bin_dir.mkdir(parents = True)
component.ops.write_prebuilt_metadata(install_dir, selection)
assert not component.ops.existing_install_matches(install_dir, host, selection)
(bin_dir / component.ops.server_binary_name(host)).write_bytes(b"bin")
marker = json.loads((install_dir / component.descriptor.metadata_filename).read_text())
assert marker["component"] == component.descriptor.component
assert marker["install_fingerprint"] == selection.fingerprint()
assert component.ops.existing_install_matches(install_dir, host, selection)
other = core.InstallSelection(
**{
**selection.__dict__,
"asset_sha256": "1" * 64,
}
)
assert not component.ops.existing_install_matches(install_dir, host, other)
def test_slim_selection_fields_are_additive(component, tmp_path):
"""The slim pairing identity rides InstallSelection additively: it never
enters the fingerprint, and only a slim selection writes marker fields."""
manifest = component.ops.parse_manifest(
manifest_for(component, [artifact(backend = "cpu", asset = "cpu.tar.gz")]), label = "m"
)
selection = component.ops.selection_from_artifact(
published_repo = component.descriptor.published_repo,
release_tag = "v1",
manifest = manifest,
artifact = manifest["artifacts"][0],
backend = "cpu",
asset_sha256 = "0" * 64,
)
import dataclasses
slim = dataclasses.replace(
selection,
install_kind = "slim",
paired_llama_tag = "b10069-mix-fb3d4ca",
linked_from = "/llama/build/bin",
linked_libraries = ("libggml.so.0", "libggml-base.so.0"),
)
assert slim.fingerprint() == selection.fingerprint()
fat_dir, slim_dir = tmp_path / "fat", tmp_path / "slim"
fat_dir.mkdir(), slim_dir.mkdir()
component.ops.write_prebuilt_metadata(fat_dir, selection)
fat_marker = json.loads((fat_dir / component.descriptor.metadata_filename).read_text())
for key in ("install_kind", "paired_llama_tag", "linked_from", "linked_libraries"):
assert key not in fat_marker
component.ops.write_prebuilt_metadata(slim_dir, slim)
slim_marker = json.loads((slim_dir / component.descriptor.metadata_filename).read_text())
assert slim_marker["install_kind"] == "slim"
assert slim_marker["paired_llama_tag"] == "b10069-mix-fb3d4ca"
assert slim_marker["linked_from"] == "/llama/build/bin"
assert slim_marker["linked_libraries"] == ["libggml.so.0", "libggml-base.so.0"]
assert set(slim_marker) == set(fat_marker) | {
"install_kind",
"paired_llama_tag",
"linked_from",
"linked_libraries",
}
def test_core_slim_hooks_default_inert(component, tmp_path):
# A hookless component adds nothing: llama's probe output must stay byte-identical.
assert component.ops.resolver_payload_extra({"install_kind": "slim"}) == {}
host = make_host(component)
selection = object()
assert component.ops.prepare_runtime_payload(tmp_path, host, selection) is None
def test_busy_activation_restores_previous_install(monkeypatch, tmp_path):
install_dir = tmp_path / "whisper.cpp"
staged_root = tmp_path / "staged"
install_dir.mkdir()
staged_root.mkdir()
(install_dir / "version").write_text("old")
(staged_root / "version").write_text("new")
real_replace = core.os.replace
def locked_activation(source, destination):
if Path(source) == staged_root:
raise PermissionError(13, "Permission denied")
return real_replace(source, destination)
monkeypatch.setattr(core.os, "replace", locked_activation)
with pytest.raises(core.BusyInstallConflict):
core.swap_into_place(staged_root, install_dir)
assert (install_dir / "version").read_text() == "old"
assert staged_root.is_dir()
assert not list(tmp_path.glob(".whisper.cpp.old-*"))
@pytest.mark.parametrize(
"value,expected",
[
("8.6", "86"),
("07.05", "75"),
("75", "75"),
(86, "86"),
("", None),
(" ", None),
("x.y", None),
("8.6.0", None),
("9.0", "90"),
],
)
def test_normalize_compute_cap(value, expected):
assert core.normalize_compute_cap(value) == expected
@pytest.mark.parametrize(
"values,expected",
[
(["8.6", "86", "8.6"], ["86"]), # deduplication
(["9.0", "7.5", "8.6"], ["75", "86", "90"]), # numeric sort
(["8.6", "bad", "", "7.5"], ["75", "86"]), # drops invalid
([], []),
],
)
def test_normalize_compute_caps(values, expected):
assert core.normalize_compute_caps(values) == expected
@pytest.mark.parametrize(
"value,expected",
[
(None, None),
("", []),
("-1", []),
("0", ["0"]),
("0,1,2", ["0", "1", "2"]),
(" 0 , 1 ", ["0", "1"]),
],
)
def test_parse_cuda_visible_devices(value, expected):
assert core.parse_cuda_visible_devices(value) == expected
@pytest.mark.parametrize(
"visible,expected",
[
(["0", "1", "2"], True),
(["GPU-abc123"], True),
(None, False),
([], False),
(["0", "MIG-device"], False),
],
)
def test_supports_explicit_visible_device_matching(visible, expected):
assert core.supports_explicit_visible_device_matching(visible) is expected
_GPU_ROWS = [
("0", "GPU-aaa", "8.6"),
("1", "GPU-bbb", "7.5"),
("2", "GPU-ccc", "8.9"),
]
@pytest.mark.parametrize(
"visible,expected_indices",
[
(None, [0, 1, 2]),
([], []),
(["0", "2"], [0, 2]),
(["gpu-bbb"], [1]), # UUID match is case insensitive
(["0", "0"], [0]),
(["99"], []),
],
)
def test_select_visible_gpu_rows(visible, expected_indices):
expected = [_GPU_ROWS[i] for i in expected_indices]
assert core.select_visible_gpu_rows(_GPU_ROWS, visible) == expected
@pytest.mark.parametrize(
"driver,expected",
[
(None, []),
((11, 8), []),
((12, 4), ["cuda12"]),
((13, 0), ["cuda13", "cuda12"]),
((14, 0), ["cuda14", "cuda13", "cuda12"]), # future major derives lines
],
)
def test_compatible_linux_runtime_lines(driver, expected):
host = SimpleNamespace(driver_cuda_version = driver)
assert core.compatible_linux_runtime_lines(host) == expected
@pytest.mark.parametrize(
"value,expected",
[
("12.6", "cuda12"),
("13.0", "cuda13"),
("11.8", None),
(None, None),
("", None),
],
)
def test_runtime_line_from_cuda_version(value, expected):
assert core.runtime_line_from_cuda_version(value) == expected
def _caps_host(caps):
return SimpleNamespace(compute_caps = list(caps))
def test_host_is_blackwell_includes_datacenter_parts():
assert core.host_is_blackwell(_caps_host(["10.0"])) is True # B200 sm_100
assert core.host_is_blackwell(_caps_host(["10.3"])) is True # B300 sm_103
assert core.host_is_blackwell(_caps_host(["12.0"])) is True # RTX 50 sm_120
assert core.host_is_blackwell(_caps_host(["12.1"])) is True # DGX Spark sm_121
assert core.host_is_blackwell(_caps_host(["9.0"])) is False
assert core.host_is_blackwell(_caps_host(["8.0"])) is False
assert core.host_is_blackwell(_caps_host(["9.0", "10.0"])) is True
def test_blackwell_min_toolkit_is_sm_aware():
# Family floor is 12.8; sm_103/sm_121 (no native target before 12.9) lift it.
f = core.blackwell_min_toolkit_for_host
assert f(_caps_host(["10.0"])) == (12, 8)
assert f(_caps_host(["12.0"])) == (12, 8)
assert f(_caps_host(["10.3"])) == (12, 9) # B300
assert f(_caps_host(["12.1"])) == (12, 9) # DGX Spark
assert f(_caps_host(["10.0", "10.3"])) == (12, 9)
def test_module_ops_prefers_module_globals_over_core_defaults(component):
ns = dict(component.namespace)
calls = []
def fake_download_file(url, destination):
calls.append(url)
destination.write_bytes(b"data")
ns["download_file"] = fake_download_file
ops = core.ModuleOps(ns)
assert ops.download_file is fake_download_file
assert callable(ops.fetch_json)
with pytest.raises(AttributeError):
_ = ops.does_not_exist_anywhere
def _github_api_403(headers):
return urllib.error.HTTPError(
"https://api.github.com/repos/unslothai/llama.cpp/releases/tags/b1",
403,
"rate limit exceeded",
headers,
io.BytesIO(b""),
)
@pytest.mark.parametrize(
("headers", "retryable"),
[
({}, False),
({"Retry-After": "5"}, True),
({"X-RateLimit-Reset": "1700000030"}, True),
({"X-RateLimit-Reset": "1700003600"}, False),
],
)
def test_github_api_403_retries_only_with_a_reachable_reset(monkeypatch, headers, retryable):
monkeypatch.setattr(core.time, "time", lambda: 1_700_000_000.0)
assert core.is_retryable_url_error(_github_api_403(headers)) is retryable
def test_github_api_403_without_a_reachable_reset_makes_one_request():
component = Component(LLAMA_DESCRIPTOR)
requests = []
class Opener:
def open(
self,
request,
timeout = None,
):
requests.append(request.full_url)
raise _github_api_403({})
component.namespace["_URL_OPENER"] = Opener()
with pytest.raises(urllib.error.HTTPError):
core.download_bytes(
component.ops,
"https://api.github.com/repos/unslothai/llama.cpp/releases/tags/b1",
)
assert len(requests) == 1
# urllib wraps only a failure to SEND in URLError; getresponse()/read errors arrive raw.
_DROPPED_CONNECTIONS = [
http.client.RemoteDisconnected("Remote end closed connection without response"),
ConnectionResetError(104, "Connection reset by peer"),
ConnectionAbortedError(10053, "An established connection was aborted"),
http.client.IncompleteRead(b"partial", 1024),
]
_NODE_SPEC = importlib.util.spec_from_file_location(
"studio_install_node_prebuilt_for_core", STUDIO_DIR / "install_node_prebuilt.py"
)
assert _NODE_SPEC is not None and _NODE_SPEC.loader is not None
install_node_prebuilt = importlib.util.module_from_spec(_NODE_SPEC)
sys.modules[_NODE_SPEC.name] = install_node_prebuilt
_NODE_SPEC.loader.exec_module(install_node_prebuilt)
@pytest.mark.parametrize("exc", _DROPPED_CONNECTIONS, ids = lambda e: type(e).__name__)
@pytest.mark.parametrize(
"classify",
[core.is_retryable_url_error, install_node_prebuilt.is_retryable_url_error],
ids = ["prebuilt_core", "install_node_prebuilt"],
)
def test_a_dropped_connection_is_retried(classify, exc):
assert classify(exc) is True
@pytest.mark.parametrize(
"classify",
[core.is_retryable_url_error, install_node_prebuilt.is_retryable_url_error],
ids = ["prebuilt_core", "install_node_prebuilt"],
)
def test_a_programming_error_is_still_not_retried(classify):
assert classify(ValueError("bad url")) is False
assert classify(FileNotFoundError("gone")) is False
class _Response:
def __init__(
self,
body,
*,
fail_after = None,
):
self._body = io.BytesIO(body)
self._fail_after = fail_after
self.headers = {"Content-Length": str(len(body))}
def __enter__(self):
return self
def __exit__(self, *exc):
return False
def read(self, size = -1):
if self._fail_after is not None and self._body.tell() >= self._fail_after:
raise ConnectionResetError(104, "Connection reset by peer")
return self._body.read(size)
@pytest.mark.parametrize("where", ["before the response", "mid-body"])
def test_a_download_that_drops_once_is_retried_to_completion(monkeypatch, tmp_path, where):
component = Component(LLAMA_DESCRIPTOR)
monkeypatch.setattr(core.time, "sleep", lambda s: None)
body = b"x" * (3 << 20)
requests = []
class Opener:
def open(
self,
request,
timeout = None,
):
requests.append(request.full_url)
if len(requests) == 1:
if where == "before the response":
raise http.client.RemoteDisconnected(
"Remote end closed connection without response"
)
return _Response(body, fail_after = 1 << 20)
return _Response(body)
component.namespace["_URL_OPENER"] = Opener()
destination = tmp_path / "app-windows-x64-cpu.zip"
core.download_file(
component.ops,
"https://github.com/unslothai/llama.cpp/releases/download/b1/a.zip",
destination,
)
assert len(requests) == 2
assert destination.read_bytes() == body
assert [p.name for p in tmp_path.iterdir()] == [destination.name]
def test_a_settle_does_not_hold_a_finished_launch_for_the_install_timeout(tmp_path):
"""A busy lock makes the settle give up quickly, not wait out the install timeout."""
install_dir = tmp_path / "component"
install_dir.mkdir()
server = install_dir / "server"
server.write_text("", encoding = "utf-8")
events = []
asked = []
@contextlib.contextmanager
def busy_lock(path, *, timeout = None):
asked.append(timeout)
raise core.BusyInstallConflict("held elsewhere")
yield # pragma: no cover - unreachable, keeps this a generator
ops = SimpleNamespace(
COMPONENT = "test",
existing_install_matches = lambda d, h, s: True,
install_lock = busy_lock,
install_lock_path = lambda d: d / "lock",
kept_install_needs_settling = lambda d: True,
settle_kept_install = lambda d: events.append("settled"),
_install_from_bundle = lambda d, h, b, s: events.append("installed"),
installed_server_path = lambda d, h: server,
log = lambda message: events.append(message),
)
bundle = SimpleNamespace(release_tag = "b1")
selection = SimpleNamespace(backend = "cpu")
rc = core.install_selected_prebuilt(
ops, install_dir, host = None, bundle = bundle, selection = selection, force = False
)
assert rc == 0
assert "installed" not in events, "a kept install was reinstalled over a busy lock"
assert "settled" not in events
assert asked == [core.SETTLE_LOCK_TIMEOUT_SECONDS]
assert core.SETTLE_LOCK_TIMEOUT_SECONDS < core.INSTALL_LOCK_TIMEOUT_SECONDS
def test_a_kept_install_that_changes_under_the_lock_is_re_validated(tmp_path):
"""A keep that changed under the lock must fall through to full re-validation, not report success."""
install_dir = tmp_path / "component"
install_dir.mkdir()
server = install_dir / "server"
server.write_text("", encoding = "utf-8")
# pre-lock keep, the settle's re-check, the locked path's re-check
answers = iter([True, False, False])
events = []
ops = SimpleNamespace(
COMPONENT = "test",
existing_install_matches = lambda d, h, s: next(answers),
install_lock = lambda path, **kwargs: contextlib.nullcontext(),
install_lock_path = lambda d: d / "lock",
kept_install_needs_settling = lambda d: True,
settle_kept_install = lambda d: events.append("settled"),
_install_from_bundle = lambda d, h, b, s: events.append("installed"),
installed_server_path = lambda d, h: server,
log = lambda message: events.append(message),
)
bundle = SimpleNamespace(release_tag = "b1")
selection = SimpleNamespace(backend = "cpu")
rc = core.install_selected_prebuilt(
ops, install_dir, host = None, bundle = bundle, selection = selection, force = False
)
assert rc == 0
assert "settled" not in events
assert "installed" in events
@pytest.mark.skipif(not hasattr(core.os, "chown"), reason = "os.chown is POSIX only")
def test_a_live_marker_rewrite_keeps_the_group_when_the_owner_is_refused(tmp_path, monkeypatch):
"""Non-root members can set the group but not the owner; the combined chown is tried first for
root, and group-only is the fallback, since a refused combined call would leave the primary
group."""
marker = tmp_path / "MARKER.json"
marker.write_text('{"a": 1}', encoding = "utf-8")
original = marker.stat()
calls = []
def refusing(path, uid, gid):
calls.append((uid, gid))
if uid != -1:
raise PermissionError("a non-root member may not give a file away")
monkeypatch.setattr(core.os, "chown", refusing)
core.write_live_marker(marker, {"a": 1, "b": 2})
assert json.loads(marker.read_text(encoding = "utf-8")) == {"a": 1, "b": 2}
assert calls == [(original.st_uid, original.st_gid), (-1, original.st_gid)]
assert not list(tmp_path.glob("MARKER.json.tmp-*"))
def test_a_walk_back_is_recorded_with_the_host_version_that_decided_it():
"""prebuilt_core WalkBack: a marker-only re-check keeps a Mac below the newest release's floor
current only if the newest release was skipped on the same macOS version."""
mac = SimpleNamespace(is_macos = True, macos_version = (14, 7))
assert core.macos_version_label(mac) == "14.7"
assert core.macos_version_label(SimpleNamespace(is_macos = True, macos_version = None)) is None
assert core.macos_version_label(SimpleNamespace(is_macos = False, macos_version = (14, 7))) is None
walk_back = core.walk_back_for(mac, "r2")
assert walk_back == core.WalkBack(release_tag = "r2", macos_version = "14.7")
assert core.walk_back_for(mac, None) is None
assert core.walk_back_for(SimpleNamespace(is_macos = False, macos_version = None), "r2") is None
marker = {"release_tag": "r1", **walk_back.marker_fields()}
assert core.marker_walk_back(marker) == walk_back
assert core.marker_walk_back({"release_tag": "r1", "walked_back_from": "r2"}) is None
assert core.walk_back_stands(marker, mac, "r2") is True
assert core.walk_back_stands(marker, mac, "r3") is False
assert core.walk_back_stands(marker, mac, None) is False
assert (
core.walk_back_stands(marker, SimpleNamespace(is_macos = True, macos_version = (15, 0)), "r2")
is False
)
assert (
core.walk_back_stands(marker, SimpleNamespace(is_macos = False, macos_version = None), "r2")
is False
)
assert core.walk_back_patch({}, walk_back) == walk_back.marker_fields()
assert core.walk_back_patch(marker, walk_back) == {}
assert core.walk_back_patch({"walked_back_from": "r2"}, walk_back) == {
"walked_back_on_macos": "14.7"
}
assert core.walk_back_patch(marker, None) == {
"walked_back_from": None,
"walked_back_on_macos": None,
}
assert core.walk_back_patch({}, None) == {}