Skip to content

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.

GGUF adapter export and llama.cpp installer: use unslothai/llama.cpp releases only, no git (#13056)

Daniel Handb400438fcd8
diff --git a/scripts/risky_loaders_baseline.json b/scripts/risky_loaders_baseline.json
index 82cc9b9fc9a..fb5a1d610de 100644
--- a/scripts/risky_loaders_baseline.json
+++ b/scripts/risky_loaders_baseline.json
@@ -26,14 +26,6 @@
"count": 1,
"reason": "Loads the installed torchao package file it is stubbing around, located via find_spec."
},
- {
- "file": "studio/backend/core/export/export.py",
- "rule": "unpinned-code-fetch",
- "sink": "git-clone-unpinned",
- "digest": "f7dadd837277bc8d",
- "count": 1,
- "reason": "Known residual: clones llama.cpp for convert_lora_to_gguf.py at the bundled release tag when known (--branch tag), else upstream master, the same upstream trust as installing llama.cpp; pinning is a separate change."
- },
{
"file": "studio/backend/core/export/worker.py",
"rule": "trust-remote-code",
diff --git a/studio/backend/core/export/export.py b/studio/backend/core/export/export.py
index 6bacad38e63..448bc6d9d55 100644
--- a/studio/backend/core/export/export.py
+++ b/studio/backend/core/export/export.py
@@ -1933,9 +1933,11 @@ class ExportBackend:
)
from unsloth_zoo import llama_cpp as _zoo_llama_cpp
+ from utils import llama_cpp_source
default_dir = os.path.normpath(_zoo_llama_cpp.LLAMA_CPP_DEFAULT_DIR)
source_dir = os.path.join(os.path.dirname(default_dir), "llama.cpp-source")
+ base_source_dir = source_dir
# A user-set scripts dir is authoritative and is checked before any network revision lookup.
pinned_dir = os.environ.get("UNSLOTH_LLAMA_CPP_SCRIPTS_DIR", "").strip()
if pinned_dir:
@@ -1948,55 +1950,73 @@ class ExportBackend:
elif os.path.exists(os.path.join(default_dir, "convert_lora_to_gguf.py")):
converter = os.path.join(default_dir, "convert_lora_to_gguf.py")
else:
- # Pinned to the installed binaries' revision (else the latest release).
+ # The installed binaries' revision (else latest), from its unslothai/llama.cpp release.
try:
- _repo, tag = _zoo_llama_cpp._resolve_converter_revision(default_dir)
+ repo, tag = _zoo_llama_cpp._resolve_converter_revision(default_dir)
except Exception:
- tag = None
- tag = tag.split("-mix-")[0] if tag else None
- if tag:
+ repo, tag = None, None
+ converter = None
+ if tag and llama_cpp_source.is_fork_release_tag(repo, tag):
source_dir = f"{source_dir}-{tag}"
- converter = os.path.join(source_dir, "convert_lora_to_gguf.py")
- if not os.path.exists(converter):
- converter = None
+ if os.path.exists(os.path.join(source_dir, "convert_lora_to_gguf.py")):
+ converter = os.path.join(source_dir, "convert_lora_to_gguf.py")
+ elif tag and not getattr(_zoo_llama_cpp, "_converter_network_allowed", lambda: True)():
+ # Offline only: online, the download path resolves the stable mix release first.
+ cached = sorted(
+ glob.glob(f"{glob.escape(source_dir)}-{glob.escape(tag)}-mix-*"),
+ key = os.path.getmtime,
+ )
+ cached = [
+ d for d in cached if os.path.isfile(os.path.join(d, "convert_lora_to_gguf.py"))
+ ]
+ if cached:
+ converter = os.path.join(cached[-1], "convert_lora_to_gguf.py")
+ # Trees the previous git-clone exporter left: llama.cpp-source-<upstream tag>, or
+ # llama.cpp-source when no revision was known.
+ legacy = base_source_dir + (f"-{tag.split('-mix-')[0]}" if tag else "")
+ if converter is None and os.path.isfile(
+ os.path.join(legacy, "convert_lora_to_gguf.py")
+ ):
+ converter = os.path.join(legacy, "convert_lora_to_gguf.py")
+ if converter is None and not tag:
+ # No revision known (offline, no marker): the newest tree any exporter left.
+ trees = [
+ d
+ for d in glob.glob(f"{glob.escape(base_source_dir)}-*")
+ if os.path.isfile(os.path.join(d, "convert_lora_to_gguf.py"))
+ ]
+ if trees:
+ converter = os.path.join(
+ max(trees, key = os.path.getmtime), "convert_lora_to_gguf.py"
+ )
if converter is None:
if not getattr(_zoo_llama_cpp, "_converter_network_allowed", lambda: True)():
raise RuntimeError(
"GGUF adapter export needs llama.cpp's convert_lora_to_gguf.py, which is not "
- f"installed, and offline mode forbids cloning it; clone llama.cpp into {source_dir}."
+ "installed, and offline mode forbids downloading it; extract the "
+ f"{llama_cpp_source.FORK_REPO} release's llama.cpp-source-<tag>.tar.gz into "
+ f"{source_dir}."
)
if not getattr(_zoo_llama_cpp, "_auto_install_enabled", lambda: True)():
raise RuntimeError(
- "GGUF adapter export needs a llama.cpp source checkout and automatic "
- f"installation was declined (UNSLOTH_AUTO_INSTALL=0); clone llama.cpp into {source_dir}."
+ "GGUF adapter export needs llama.cpp's converter sources and automatic "
+ "installation was declined (UNSLOTH_AUTO_INSTALL=0); extract the "
+ f"{llama_cpp_source.FORK_REPO} release's llama.cpp-source-<tag>.tar.gz into "
+ f"{source_dir}."
)
- # Not install_llama_cpp: it probes apt-get even when only cloning, which fails on macOS.
- ensure_dir(Path(source_dir).parent)
- with tempfile.TemporaryDirectory(dir = Path(source_dir).parent) as tmp_dir:
- clone = os.path.join(tmp_dir, "llama.cpp")
- subprocess.run(
- [
- "git",
- "clone",
- "--depth",
- "1",
- *(["--branch", tag] if tag else []),
- "https://github.com/ggml-org/llama.cpp",
- clone,
- ],
- check = True,
- capture_output = True,
- text = True,
- encoding = "utf-8",
- errors = "replace",
+ # Not install_llama_cpp: it probes apt-get even when only fetching sources, which fails on macOS.
+ try:
+ fetched = llama_cpp_source.download_converter_source(
+ repo, tag, Path(source_dir).parent
)
- if not os.path.exists(source_dir):
- os.replace(clone, source_dir)
- converter = os.path.join(source_dir, "convert_lora_to_gguf.py")
- if not os.path.exists(converter):
+ except Exception as exc:
raise RuntimeError(
- f"convert_lora_to_gguf.py is missing from the llama.cpp clone at {source_dir}."
- )
+ "Could not download llama.cpp's converter sources from the "
+ f"{llama_cpp_source.FORK_REPO} release: {exc}"
+ ) from exc
+ converter = os.path.join(str(fetched), "convert_lora_to_gguf.py")
+ if not os.path.exists(converter):
+ raise RuntimeError(f"convert_lora_to_gguf.py is missing from {fetched}.")
if importlib.util.find_spec("gguf") is None and not os.path.isdir(
os.path.join(os.path.dirname(converter), "gguf-py")
):
diff --git a/studio/backend/tests/test_export_adapter_format.py b/studio/backend/tests/test_export_adapter_format.py
index 17c918d1c9b..f24a39899c6 100644
--- a/studio/backend/tests/test_export_adapter_format.py
+++ b/studio/backend/tests/test_export_adapter_format.py
@@ -163,7 +163,7 @@ def _converter_harness(monkeypatch, tmp_path, with_converter):
zoo = types.ModuleType("unsloth_zoo")
zoo.llama_cpp = types.SimpleNamespace(
LLAMA_CPP_DEFAULT_DIR = str(llama),
- _resolve_converter_revision = lambda d: ("ggml-org/llama.cpp", "b9000-mix-abc"),
+ _resolve_converter_revision = lambda d: ("unslothai/llama.cpp", "b9000-mix-abc"),
)
monkeypatch.setitem(sys.modules, "unsloth_zoo", zoo)
monkeypatch.setitem(sys.modules, "unsloth_zoo.llama_cpp", zoo.llama_cpp)
@@ -175,9 +175,6 @@ def _converter_harness(monkeypatch, tmp_path, with_converter):
**kwargs,
):
calls.append((cmd, env))
- if cmd[:2] == ["git", "clone"]:
- os.makedirs(os.path.join(cmd[-1], "gguf-py"))
- open(os.path.join(cmd[-1], "convert_lora_to_gguf.py"), "w").close()
return types.SimpleNamespace(returncode = 0, stdout = "", stderr = "")
monkeypatch.setattr(subprocess, "run", _run)
@@ -205,16 +202,138 @@ def test_gguf_converter_token_env(monkeypatch, tmp_path, token, expect):
assert env.get("HF_HUB_DISABLE_IMPLICIT_TOKEN") == ("1" if token is False else "0")
-def test_gguf_converter_cloned_without_package_manager(monkeypatch, tmp_path):
+def _fork_source_tarball(tag, members = None):
+ import io
+ import tarfile
+
+ buf = io.BytesIO()
+ with tarfile.open(fileobj = buf, mode = "w:gz") as tar:
+ for name, data in members or [
+ (f"llama.cpp-{tag}/convert_lora_to_gguf.py", b"import sys\n"),
+ (f"llama.cpp-{tag}/gguf-py/gguf/__init__.py", b""),
+ ]:
+ info = tarfile.TarInfo(name)
+ info.size = len(data)
+ tar.addfile(info, io.BytesIO(data))
+ return buf.getvalue()
+
+
+def _serve_fork_release(
+ monkeypatch,
+ tag,
+ tarball,
+ sha = None,
+ releases = (),
+):
+ """Fake GitHub: the fork release's sha256 json + source asset, and the release listing."""
+ import hashlib
+ import io
+
+ from utils import llama_cpp_source
+
+ sha = sha or hashlib.sha256(tarball).hexdigest()
+ checksums = {
+ "release_tag": tag,
+ "upstream_tag": tag.split("-mix-")[0],
+ "artifacts": {
+ f"llama.cpp-source-{tag}.tar.gz": {"sha256": sha, "repo": "unslothai/llama.cpp"}
+ },
+ }
+ urls = []
+
+ def _open(url, timeout = 60):
+ urls.append(url)
+ assert "ggml-org" not in url
+ if url.endswith("/llama-prebuilt-sha256.json"):
+ return io.BytesIO(json.dumps(checksums).encode())
+ if url.endswith(f"/llama.cpp-source-{tag}.tar.gz"):
+ return io.BytesIO(tarball)
+ if "/releases?" in url:
+ return io.BytesIO(json.dumps(list(releases)).encode())
+ raise AssertionError(url)
+
+ monkeypatch.setattr(llama_cpp_source, "_open", _open)
+ return urls
+
+
+def test_gguf_converter_downloaded_from_fork_release_without_git(monkeypatch, tmp_path):
backend, adapter, calls = _converter_harness(monkeypatch, tmp_path, False)
+ tag = "b9000-mix-abc"
+ urls = _serve_fork_release(monkeypatch, tag, _fork_source_tarball(tag))
backend._convert_peft_dir_to_gguf(adapter, "q8_0", None)
- assert calls[0][0][:6] == ["git", "clone", "--depth", "1", "--branch", "b9000"]
- source = tmp_path / "home" / "llama.cpp-source-b9000"
- assert calls[-1][0][1] == str(source / "convert_lora_to_gguf.py")
+ assert not any(c[0][0] == "git" for c in calls)
+ assert urls == [
+ f"https://github.com/unslothai/llama.cpp/releases/download/{tag}/llama-prebuilt-sha256.json",
+ f"https://github.com/unslothai/llama.cpp/releases/download/{tag}/llama.cpp-source-{tag}.tar.gz",
+ ]
+ source = tmp_path / "home" / f"llama.cpp-source-{tag}"
+ assert [c[0][1] for c in calls] == [str(source / "convert_lora_to_gguf.py")]
assert sorted(p.name for p in (tmp_path / "home").iterdir()) == [
"llama.cpp",
- "llama.cpp-source-b9000",
+ f"llama.cpp-source-{tag}",
]
+ # Cached: a second export makes no request.
+ backend._convert_peft_dir_to_gguf(adapter, "q8_0", None)
+ assert len(urls) == 2
+
+
+def test_gguf_converter_maps_upstream_tag_to_fork_release(monkeypatch, tmp_path):
+ import sys
+
+ backend, adapter, calls = _converter_harness(monkeypatch, tmp_path, False)
+ sys.modules["unsloth_zoo.llama_cpp"]._resolve_converter_revision = lambda d: (
+ "ggml-org/llama.cpp",
+ "b9000",
+ )
+ tag = "b9000-mix-def"
+ urls = _serve_fork_release(
+ monkeypatch,
+ tag,
+ _fork_source_tarball(tag),
+ releases = [
+ {"tag_name": "b9001-mix-aaa", "draft": False},
+ {"tag_name": "b9000-mix-zzz", "draft": True},
+ {"tag_name": tag, "draft": False},
+ ],
+ )
+ backend._convert_peft_dir_to_gguf(adapter, "q8_0", None)
+ assert calls[-1][0][1] == str(
+ tmp_path / "home" / f"llama.cpp-source-{tag}" / "convert_lora_to_gguf.py"
+ )
+ assert any("/releases?" in u for u in urls)
+ # Offline later: the fork tree fetched for that upstream tag is reused.
+ sys.modules["unsloth_zoo.llama_cpp"]._converter_network_allowed = lambda: False
+ backend._convert_peft_dir_to_gguf(adapter, "q8_0", None)
+ assert calls[-1][0][1] == str(
+ tmp_path / "home" / f"llama.cpp-source-{tag}" / "convert_lora_to_gguf.py"
+ )
+
+
+def test_gguf_converter_rejects_checksum_mismatch(monkeypatch, tmp_path):
+ backend, adapter, calls = _converter_harness(monkeypatch, tmp_path, False)
+ tag = "b9000-mix-abc"
+ _serve_fork_release(monkeypatch, tag, _fork_source_tarball(tag), sha = "0" * 64)
+ with pytest.raises(RuntimeError, match = "sha256 mismatch"):
+ backend._convert_peft_dir_to_gguf(adapter, "q8_0", None)
+ assert calls == []
+ assert sorted(p.name for p in (tmp_path / "home").iterdir()) == ["llama.cpp"]
+
+
+ "name",
+ ["../evil.py", "/abs/evil.py", "llama.cpp-x/../../evil.py"],
+)
+def test_gguf_converter_refuses_path_traversal(monkeypatch, tmp_path, name):
+ backend, adapter, calls = _converter_harness(monkeypatch, tmp_path, False)
+ tag = "b9000-mix-abc"
+ tarball = _fork_source_tarball(
+ tag, [(f"llama.cpp-{tag}/convert_lora_to_gguf.py", b"x"), (name, b"x")]
+ )
+ _serve_fork_release(monkeypatch, tag, tarball)
+ with pytest.raises(RuntimeError, match = "unsafe path"):
+ backend._convert_peft_dir_to_gguf(adapter, "q8_0", None)
+ assert calls == []
+ assert not (tmp_path / "evil.py").exists() and not (tmp_path / "home" / "evil.py").exists()
def test_parse_adapter_features(tmp_path):
@@ -289,7 +408,7 @@ def test_local_dir_never_format_mixed(monkeypatch, tmp_path):
assert not ok and "mix" in message
-def test_gguf_converter_offline_refuses_clone(monkeypatch, tmp_path):
+def test_gguf_converter_offline_refuses_download(monkeypatch, tmp_path):
import sys
backend, adapter, calls = _converter_harness(monkeypatch, tmp_path, False)
@@ -325,3 +444,254 @@ def test_gguf_converter_uses_loaded_snapshot(monkeypatch, tmp_path):
backend._convert_peft_dir_to_gguf(adapter, "q8_0", None)
cmd = calls[-1][0]
assert cmd[cmd.index("--base") + 1] == str(snap) and "--base-model-id" not in cmd
+
+
+def _fake_github(monkeypatch, routes):
+ """routes: url suffix or substring -> bytes/obj (served) or Exception (raised)."""
+ import io
+ import urllib.error
+
+ from utils import llama_cpp_source
+
+ urls = []
+
+ def _open(url, timeout = 60):
+ urls.append(url)
+ assert "ggml-org" not in url
+ for key, value in routes.items():
+ if url.endswith(key) or key in url:
+ if value is None:
+ raise urllib.error.HTTPError(url, 404, "Not Found", {}, None)
+ data = value if isinstance(value, bytes) else json.dumps(value).encode()
+ return io.BytesIO(data)
+ raise AssertionError(url)
+
+ monkeypatch.setattr(llama_cpp_source, "_open", _open)
+ return urls
+
+
+def test_gguf_converter_reads_exact_commit_source_archive(monkeypatch, tmp_path):
+ import hashlib
+
+ backend, adapter, calls = _converter_harness(monkeypatch, tmp_path, False)
+ tag, commit = "b9000-mix-abc", "a" * 40
+ tarball = _fork_source_tarball(tag)
+ asset = f"llama.cpp-source-commit-{commit}.tar.gz"
+ _fake_github(
+ monkeypatch,
+ {
+ "/llama-prebuilt-sha256.json": {
+ "release_tag": tag,
+ "source_commit": commit,
+ "artifacts": {asset: {"sha256": hashlib.sha256(tarball).hexdigest()}},
+ },
+ f"/{asset}": tarball,
+ },
+ )
+ backend._convert_peft_dir_to_gguf(adapter, "q8_0", None)
+ assert calls[-1][0][1] == str(
+ tmp_path / "home" / f"llama.cpp-source-{tag}" / "convert_lora_to_gguf.py"
+ )
+
+
+def test_gguf_converter_bare_fork_tag_maps_to_mix_release_across_pages(monkeypatch, tmp_path):
+ import hashlib
+ import sys
+
+ backend, adapter, calls = _converter_harness(monkeypatch, tmp_path, False)
+ sys.modules["unsloth_zoo.llama_cpp"]._resolve_converter_revision = lambda d: (
+ "unslothai/llama.cpp",
+ "b9000",
+ )
+ tag = "b9000-mix-def"
+ tarball = _fork_source_tarball(tag)
+ urls = _fake_github(
+ monkeypatch,
+ {
+ "/download/b9000/llama-prebuilt-sha256.json": None,
+ f"/download/{tag}/llama-prebuilt-sha256.json": {
+ "release_tag": tag,
+ "artifacts": {
+ f"llama.cpp-source-{tag}.tar.gz": {
+ "sha256": hashlib.sha256(tarball).hexdigest()
+ }
+ },
+ },
+ f"/llama.cpp-source-{tag}.tar.gz": tarball,
+ "&page=1": [{"tag_name": f"b{9100 + i}-mix-x", "draft": False} for i in range(100)],
+ "&page=2": [{"tag_name": tag, "draft": False}],
+ },
+ )
+ backend._convert_peft_dir_to_gguf(adapter, "q8_0", None)
+ assert calls[-1][0][1] == str(
+ tmp_path / "home" / f"llama.cpp-source-{tag}" / "convert_lora_to_gguf.py"
+ )
+ assert any("&page=2" in u for u in urls)
+
+
+ "revision,legacy",
+ [
+ (("unslothai/llama.cpp", "b9000-mix-abc"), "llama.cpp-source-b9000"),
+ ((None, None), "llama.cpp-source"),
+ ],
+)
+def test_gguf_converter_reuses_tree_from_previous_exporter_offline(
+ monkeypatch, tmp_path, revision, legacy
+):
+ import sys
+
+ backend, adapter, calls = _converter_harness(monkeypatch, tmp_path, False)
+ zoo = sys.modules["unsloth_zoo.llama_cpp"]
+ zoo._resolve_converter_revision = lambda d: revision
+ zoo._converter_network_allowed = lambda: False
+ old = tmp_path / "home" / legacy
+ (old / "gguf-py").mkdir(parents = True)
+ (old / "convert_lora_to_gguf.py").write_text("")
+ _fake_github(monkeypatch, {})
+ backend._convert_peft_dir_to_gguf(adapter, "q8_0", None)
+ assert calls[-1][0][1] == str(old / "convert_lora_to_gguf.py")
+
+
+def test_gguf_converter_lookup_failure_keeps_the_revision(monkeypatch, tmp_path):
+ import sys
+
+ backend, adapter, calls = _converter_harness(monkeypatch, tmp_path, False)
+ sys.modules["unsloth_zoo.llama_cpp"]._resolve_converter_revision = lambda d: (
+ "ggml-org/llama.cpp",
+ "b9000",
+ )
+ urls = _fake_github(monkeypatch, {"/releases?": None})
+ with pytest.raises(RuntimeError, match = "converter sources"):
+ backend._convert_peft_dir_to_gguf(adapter, "q8_0", None)
+ assert not any("/latest/" in u for u in urls)
+ assert calls == []
+
+
+def test_gguf_converter_skips_prerelease_when_mapping_upstream_tag(monkeypatch):
+ from utils import llama_cpp_source
+ _fake_github(
+ monkeypatch,
+ {
+ "&page=1": [
+ {"tag_name": "b9000-mix-pre", "draft": False, "prerelease": True},
+ {"tag_name": "b9000-mix-rel", "draft": False, "prerelease": False},
+ ]
+ },
+ )
+ assert llama_cpp_source._matching_fork_tag("b9000") == "b9000-mix-rel"
+
+
+def test_gguf_converter_offline_without_revision_reuses_newest_fork_tree(monkeypatch, tmp_path):
+ import os
+ import sys
+
+ backend, adapter, calls = _converter_harness(monkeypatch, tmp_path, False)
+ zoo = sys.modules["unsloth_zoo.llama_cpp"]
+ zoo._resolve_converter_revision = lambda d: (None, None)
+ zoo._converter_network_allowed = lambda: False
+ trees = []
+ for i, tag in enumerate(["b8000-mix-old", "b9000-mix-new"]):
+ tree = tmp_path / "home" / f"llama.cpp-source-{tag}"
+ (tree / "gguf-py").mkdir(parents = True)
+ (tree / "convert_lora_to_gguf.py").write_text("")
+ os.utime(tree, (1000 + i, 1000 + i))
+ trees.append(tree)
+ _fake_github(monkeypatch, {})
+ backend._convert_peft_dir_to_gguf(adapter, "q8_0", None)
+ assert calls[-1][0][1] == str(trees[-1] / "convert_lora_to_gguf.py")
+
+
+def test_gguf_converter_reads_legacy_upstream_named_source_archive(monkeypatch, tmp_path):
+ import hashlib
+
+ backend, adapter, calls = _converter_harness(monkeypatch, tmp_path, False)
+ tag = "b9000-mix-abc"
+ tarball = _fork_source_tarball(tag)
+ asset = "llama.cpp-source-b9000.tar.gz"
+ _fake_github(
+ monkeypatch,
+ {
+ "/llama-prebuilt-sha256.json": {
+ "release_tag": tag,
+ "upstream_tag": "b9000",
+ "artifacts": {asset: {"sha256": hashlib.sha256(tarball).hexdigest()}},
+ },
+ f"/{asset}": tarball,
+ },
+ )
+ backend._convert_peft_dir_to_gguf(adapter, "q8_0", None)
+ assert calls[-1][0][1] == str(
+ tmp_path / "home" / f"llama.cpp-source-{tag}" / "convert_lora_to_gguf.py"
+ )
+
+
+def test_gguf_converter_online_bare_tag_ignores_an_unrelated_mix_cache(monkeypatch, tmp_path):
+ import hashlib
+ import sys
+
+ backend, adapter, calls = _converter_harness(monkeypatch, tmp_path, False)
+ sys.modules["unsloth_zoo.llama_cpp"]._resolve_converter_revision = lambda d: (
+ "ggml-org/llama.cpp",
+ "b9000",
+ )
+ stale = tmp_path / "home" / "llama.cpp-source-b9000-mix-pre"
+ (stale / "gguf-py").mkdir(parents = True)
+ (stale / "convert_lora_to_gguf.py").write_text("")
+ tag = "b9000-mix-rel"
+ tarball = _fork_source_tarball(tag)
+ _fake_github(
+ monkeypatch,
+ {
+ "&page=1": [{"tag_name": tag, "draft": False}],
+ f"/download/{tag}/llama-prebuilt-sha256.json": {
+ "release_tag": tag,
+ "artifacts": {
+ f"llama.cpp-source-{tag}.tar.gz": {
+ "sha256": hashlib.sha256(tarball).hexdigest()
+ }
+ },
+ },
+ f"/llama.cpp-source-{tag}.tar.gz": tarball,
+ },
+ )
+ backend._convert_peft_dir_to_gguf(adapter, "q8_0", None)
+ assert calls[-1][0][1] == str(
+ tmp_path / "home" / f"llama.cpp-source-{tag}" / "convert_lora_to_gguf.py"
+ )
+
+
+def test_source_artifact_accepts_abbreviated_commit():
+ from utils import llama_cpp_source
+ name, digest = llama_cpp_source.source_artifact(
+ {
+ "source_commit": "abc1234",
+ "artifacts": {"llama.cpp-source-commit-abc1234.tar.gz": {"sha256": "a" * 64}},
+ },
+ "b9000-mix-abc",
+ )
+ assert name == "llama.cpp-source-commit-abc1234.tar.gz"
+
+
+def test_safe_extract_without_data_filter_drops_links(monkeypatch, tmp_path):
+ import io
+ import tarfile
+
+ from utils import llama_cpp_source
+
+ archive = tmp_path / "a.tar.gz"
+ with tarfile.open(archive, "w:gz") as tar:
+ link = tarfile.TarInfo("root/a")
+ link.type = tarfile.SYMTYPE
+ link.linkname = "."
+ tar.addfile(link)
+ data = b"x"
+ info = tarfile.TarInfo("root/convert_lora_to_gguf.py")
+ info.size = len(data)
+ tar.addfile(info, io.BytesIO(data))
+ monkeypatch.delattr(tarfile, "data_filter", raising = False)
+ out = tmp_path / "out"
+ out.mkdir()
+ llama_cpp_source.safe_extract_tar(archive, out)
+ assert (out / "root" / "convert_lora_to_gguf.py").is_file()
+ assert not (out / "root" / "a").exists() and not (out / "root" / "a").is_symlink()
diff --git a/studio/backend/tests/test_install_resolve_prebuilt.py b/studio/backend/tests/test_install_resolve_prebuilt.py
index e29b1b358a7..dae2ed7d26b 100644
--- a/studio/backend/tests/test_install_resolve_prebuilt.py
+++ b/studio/backend/tests/test_install_resolve_prebuilt.py
@@ -700,11 +700,9 @@ def _linux_arm64_vulkan_host():
)
-def test_route_to_vulkan_prebuilt_linux_arm64_falls_back_to_upstream():
- # The fork ships no ARM64 Vulkan bundle, so a forced-Vulkan Linux ARM64 host
- # must keep planning against upstream (which publishes
- # llama-<tag>-bin-ubuntu-vulkan-arm64.tar.gz). The fork pin is dropped because
- # the two repos use different tag namespaces.
+def test_route_to_vulkan_prebuilt_linux_arm64_stays_on_the_fork():
+ # The fork publishes a linux-vulkan-arm64 bundle, so a forced-Vulkan Linux ARM64
+ # host keeps planning against the fork and its pin; nothing comes from upstream.
routed, repo, tag, persist = ilp._route_to_vulkan_prebuilt(
_linux_arm64_vulkan_host(),
FORK,
@@ -713,15 +711,14 @@ def test_route_to_vulkan_prebuilt_linux_arm64_falls_back_to_upstream():
llama_backend = "vulkan",
)
- assert repo == UPSTREAM
- assert tag == ""
+ assert repo == FORK
+ assert tag == "b9596-mix-abc"
assert persist == "vulkan"
assert routed.has_intel_gpu is True
def test_forced_vulkan_linux_arm64_still_resolves_a_vulkan_bundle():
- # End to end for the routing above: without it the fork planner yields only the
- # ARM64 CPU attempt, and the strict-Vulkan filter then leaves nothing to install.
+ # End to end: the fork's ARM64 Vulkan bundle survives the strict-Vulkan filter.
routed, repo, _tag, _persist = ilp._route_to_vulkan_prebuilt(
_linux_arm64_vulkan_host(),
FORK,
@@ -729,22 +726,25 @@ def test_forced_vulkan_linux_arm64_still_resolves_a_vulkan_bundle():
force_cpu = False,
llama_backend = "vulkan",
)
- fork_attempts = ilp._linux_published_attempts(
- routed, _published_vulkan_bundle("linux-vulkan", "linux-arm64")
- )
- assert [attempt.install_kind for attempt in fork_attempts] == ["linux-arm64"]
-
- release = _upstream_release(
- "b9925",
- ["llama-b9925-bin-ubuntu-vulkan-arm64.tar.gz", "llama-b9925-bin-ubuntu-arm64.tar.gz"],
+ assert repo == FORK
+ bundle = _published_vulkan_bundle("linux-arm64")
+ bundle.artifacts.insert(
+ 0,
+ ilp.PublishedLlamaArtifact(
+ asset_name = "app-release-linux-arm64-vulkan",
+ install_kind = "linux-vulkan",
+ runtime_line = None,
+ coverage_class = None,
+ supported_sms = [],
+ min_sm = None,
+ max_sm = None,
+ bundle_profile = "linux-vulkan-arm64",
+ rank = 60,
+ ),
)
- plan = ilp.direct_upstream_release_plan(release, routed, repo, "latest")
- filtered = ilp._backend_only_release_plans([plan], "vulkan")
-
- assert [attempt.name for attempt in filtered[0].attempts] == [
- "llama-b9925-bin-ubuntu-vulkan-arm64.tar.gz"
- ]
- assert filtered[0].attempts[0].repo == UPSTREAM
+ bundle.assets["app-release-linux-arm64-vulkan"] = "https://example.invalid/arm64-vulkan.tar.gz"
+ attempts = ilp._linux_published_attempts(routed, bundle)
+ assert [attempt.name for attempt in attempts][:1] == ["app-release-linux-arm64-vulkan"]
def test_route_to_vulkan_prebuilt_linux_arm64_keeps_an_explicit_repo_override():
diff --git a/studio/backend/utils/llama_cpp_source.py b/studio/backend/utils/llama_cpp_source.py
new file mode 100644
index 00000000000..eb22a2f67b2
--- /dev/null
+++ b/studio/backend/utils/llama_cpp_source.py
@@ -0,0 +1,191 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+"""llama.cpp converter sources (convert_lora_to_gguf.py, gguf-py) from the Unsloth fork's releases.
+
+Each unslothai/llama.cpp release carries ``llama.cpp-source-<tag>.tar.gz`` and the
+``llama-prebuilt-sha256.json`` that pins its digest, so no git and no ggml-org download is
+needed. The backend cannot import the studio/ installer scripts (see
+utils/prebuilt/runtime_libs.py), hence this small standalone copy.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+import re
+import tarfile
+import tempfile
+import urllib.parse
+import urllib.request
+from pathlib import Path, PurePosixPath
+from typing import Optional
+
+FORK_REPO = "unslothai/llama.cpp"
+SHA256_ASSET_NAME = "llama-prebuilt-sha256.json"
+_USER_AGENT = "unsloth-studio-llama-cpp-source"
+
+
+def source_asset_name(tag: str) -> str:
+ return f"llama.cpp-source-{tag}.tar.gz"
+
+
+def is_fork_release_tag(repo: Optional[str], tag: Optional[str]) -> bool:
+ return repo == FORK_REPO and bool(tag) and "-mix-" in tag
+
+
+def _asset_url(tag: Optional[str], name: str) -> str:
+ if tag is None:
+ return f"https://github.com/{FORK_REPO}/releases/latest/download/{name}"
+ return (
+ f"https://github.com/{FORK_REPO}/releases/download/"
+ f"{urllib.parse.quote(tag, safe = '')}/{urllib.parse.quote(name, safe = '')}"
+ )
+
+
+def _open(url: str, timeout: int = 60):
+ headers = {"User-Agent": _USER_AGENT}
+ token = os.environ.get("GITHUB_TOKEN") or os.environ.get("GH_TOKEN")
+ if token and urllib.parse.urlparse(url).hostname == "api.github.com":
+ headers["Authorization"] = f"Bearer {token}"
+ return urllib.request.urlopen(urllib.request.Request(url, headers = headers), timeout = timeout)
+
+
+def _fetch_json(url: str):
+ with _open(url) as response:
+ return json.loads(response.read().decode("utf-8"))
+
+
+def _matching_fork_tag(upstream_tag: str) -> Optional[str]:
+ """Newest non-draft fork release built on ``upstream_tag`` (tags are ``<upstream>-mix-<sha>``)."""
+ prefix = f"{upstream_tag}-mix-"
+ for page in range(1, 21):
+ releases = _fetch_json(
+ f"https://api.github.com/repos/{FORK_REPO}/releases?per_page=100&page={page}"
+ )
+ if not isinstance(releases, list) or not releases:
+ return None
+ for release in releases:
+ tag = release.get("tag_name") or ""
+ if (
+ not release.get("draft")
+ and not release.get("prerelease")
+ and tag.startswith(prefix)
+ ):
+ return tag
+ return None
+
+
+def resolve_fork_release(repo: Optional[str], tag: Optional[str]) -> tuple[str, dict]:
+ """(fork release tag, its llama-prebuilt-sha256.json) for a converter revision.
+
+ A fork tag is used as is; a bare tag the fork reports is tried as a release first. Anything
+ else (an old ggml-org marker, nothing) maps to the fork release built on that upstream tag,
+ else the latest.
+ """
+ fork_tag: Optional[str] = None
+ checksums = None
+ if tag and ("-mix-" in tag or repo == FORK_REPO):
+ try:
+ checksums = _fetch_json(_asset_url(tag, SHA256_ASSET_NAME))
+ fork_tag = tag
+ except Exception:
+ if "-mix-" in tag:
+ raise
+ if checksums is None:
+ if tag:
+ # A failed lookup raises: falling back to latest would drop the installed revision.
+ fork_tag = _matching_fork_tag(tag.split("-mix-")[0])
+ checksums = _fetch_json(_asset_url(fork_tag, SHA256_ASSET_NAME))
+ if not isinstance(checksums, dict):
+ raise RuntimeError(f"{SHA256_ASSET_NAME} from {FORK_REPO} is not a JSON object")
+ release_tag = checksums.get("release_tag") or fork_tag
+ if not isinstance(release_tag, str) or not release_tag:
+ raise RuntimeError(f"{SHA256_ASSET_NAME} from {FORK_REPO} names no release_tag")
+ if fork_tag is not None and release_tag != fork_tag:
+ raise RuntimeError(
+ f"{SHA256_ASSET_NAME} for {FORK_REPO}@{fork_tag} describes release {release_tag}"
+ )
+ return release_tag, checksums
+
+
+def source_artifact(checksums: dict, release_tag: str) -> tuple[str, str]:
+ """(asset name, sha256) of the release's source archive: tag-named, exact-commit
+ (``llama.cpp-source-commit-<source_commit>.tar.gz``) or upstream-tag-named, as the installer accepts."""
+ artifacts = checksums.get("artifacts") or {}
+ names = [source_asset_name(release_tag)]
+ commit = checksums.get("source_commit")
+ if isinstance(commit, str) and re.fullmatch(r"[0-9a-fA-F]{7,40}", commit):
+ names.append(f"llama.cpp-source-commit-{commit.lower()}.tar.gz")
+ upstream = checksums.get("upstream_tag")
+ if isinstance(upstream, str) and upstream and upstream != release_tag:
+ names.append(source_asset_name(upstream)) # older releases name it after upstream_tag
+ for name in names:
+ entry = artifacts.get(name)
+ digest = entry.get("sha256") if isinstance(entry, dict) else None
+ if isinstance(digest, str) and re.fullmatch(r"[0-9a-fA-F]{64}", digest):
+ return name, digest.lower()
+ raise RuntimeError(f"{FORK_REPO}@{release_tag} publishes no sha256 for its source archive")
+
+
+def safe_extract_tar(archive: Path, destination: Path) -> None:
+ """Extract a .tar.gz refusing absolute paths, '..', links leaving ``destination``, devices."""
+ base = destination.resolve()
+ with tarfile.open(archive, "r:gz") as tar:
+ members = tar.getmembers()
+ for member in members:
+ name = member.name.replace("\\", "/")
+ parts = PurePosixPath(name).parts
+ if name.startswith("/") or ".." in parts or re.match(r"^[A-Za-z]:", name):
+ raise RuntimeError(f"unsafe path in llama.cpp source archive: {member.name}")
+ if not (member.isfile() or member.isdir() or member.issym() or member.islnk()):
+ raise RuntimeError(f"unsupported entry in llama.cpp source archive: {member.name}")
+ if member.issym() or member.islnk():
+ link = member.linkname.replace("\\", "/")
+ origin = (base / name).parent if member.issym() else base
+ if link.startswith("/") or not (origin / link).resolve().is_relative_to(base):
+ raise RuntimeError(f"link escapes the llama.cpp source archive: {member.name}")
+ if hasattr(tarfile, "data_filter"):
+ tar.extractall(destination, members = members, filter = "data")
+ else: # Python < 3.11.4: links could chain out mid-extraction; the converter needs none.
+ tar.extractall(destination, members = [m for m in members if m.isfile() or m.isdir()])
+
+
+def download_converter_source(repo: Optional[str], tag: Optional[str], parent: Path) -> Path:
+ """Download, verify and publish ``parent/llama.cpp-source-<fork tag>``; returns that dir."""
+ release_tag, checksums = resolve_fork_release(repo, tag)
+ target = Path(parent) / f"llama.cpp-source-{release_tag}"
+ if (target / "convert_lora_to_gguf.py").is_file():
+ return target
+ asset, expected = source_artifact(checksums, release_tag)
+ Path(parent).mkdir(parents = True, exist_ok = True)
+ with tempfile.TemporaryDirectory(dir = parent, prefix = ".llama.cpp-source-") as tmp:
+ archive = Path(tmp) / asset
+ digest = hashlib.sha256()
+ with (
+ _open(_asset_url(release_tag, archive.name), timeout = 300) as response,
+ open(archive, "wb") as out,
+ ):
+ while chunk := response.read(1 << 20):
+ digest.update(chunk)
+ out.write(chunk)
+ if digest.hexdigest() != expected:
+ raise RuntimeError(
+ f"{archive.name} sha256 mismatch: expected {expected}, got {digest.hexdigest()}"
+ )
+ extract_dir = Path(tmp) / "extract"
+ extract_dir.mkdir()
+ safe_extract_tar(archive, extract_dir)
+ roots = [p for p in extract_dir.iterdir() if p.is_dir()]
+ if len(roots) != 1 or not (roots[0] / "convert_lora_to_gguf.py").is_file():
+ raise RuntimeError(
+ f"{archive.name} has no convert_lora_to_gguf.py under one top directory"
+ )
+ if not target.exists():
+ try:
+ os.replace(roots[0], target)
+ except OSError:
+ if not (target / "convert_lora_to_gguf.py").is_file():
+ raise
+ return target
diff --git a/studio/install_llama_prebuilt.py b/studio/install_llama_prebuilt.py
index da9dea7a55b..4f773cc71b3 100644
--- a/studio/install_llama_prebuilt.py
+++ b/studio/install_llama_prebuilt.py
@@ -4247,6 +4247,12 @@ def resolve_release_asset_choice(
"published Windows CUDA assets ignored for install planning: "
f"{release.repo}@{release.release_tag} ({exc})"
)
+ if release.repo == DEFAULT_PUBLISHED_REPO:
+ # Prebuilts come only from the fork's own release, never upstream ggml-org's.
+ raise PrebuiltFallback(
+ f"no published Windows CUDA bundle in {release.repo}@{release.release_tag} "
+ "covers this host"
+ )
upstream_assets = github_release_assets(UPSTREAM_REPO, llama_tag)
upstream_attempts = _drop_blackwell_incapable_windows_cuda(
selection_host,
@@ -4284,8 +4290,8 @@ def resolve_release_asset_choice(
else:
published_choice = published_asset_choice_for_kind(release, "windows-cpu")
elif host.is_windows and host.is_arm64:
- # Prefer a CUDA bundle, as x64 does: the published windows-arm64-cuda artifact first, then
- # upstream's -arm64 zip, both hash-gated. The opt-out gates the WHOLE branch.
+ # A host the fork's windows-arm64-cuda bundle does not cover takes its ARM64 CPU bundle.
+ # The opt-out gates the WHOLE branch.
if host.has_usable_nvidia and _upstream_arm64_cuda_allowed():
torch_preference = detect_torch_cuda_runtime_preference(host)
published_arm64_cuda = _drop_blackwell_incapable_windows_cuda(
@@ -4306,50 +4312,10 @@ def resolve_release_asset_choice(
"published Windows ARM64 CUDA assets ignored for install planning: "
f"{release.repo}@{release.release_tag} ({exc})"
)
- # Same rule as the digest fetch below: a rate limit, an outage or a malformed payload from the
- # release API costs the CUDA bundle, never the install; the ARM64 CPU bundle is still there.
- try:
- upstream_arm64_assets = github_release_assets(UPSTREAM_REPO, llama_tag)
- except Exception as exc:
- log(
- f"could not list the upstream {UPSTREAM_REPO}@{llama_tag} release assets "
- f"({exc}); falling through to the ARM64 CPU bundle."
- )
- upstream_arm64_assets = {}
- upstream_arm64_cuda = _drop_blackwell_incapable_windows_cuda(
- host,
- resolve_windows_cuda_choices(
- host,
- llama_tag,
- upstream_arm64_assets,
- arch = "arm64",
- ),
+ log(
+ f"no published Windows ARM64 CUDA bundle in {release.repo}@{release.release_tag} "
+ "covers this GPU; falling through to the ARM64 CPU bundle."
)
- if upstream_arm64_cuda:
- try:
- return apply_approved_hashes(upstream_arm64_cuda, checksums)
- except PrebuiltFallback as exc:
- # The fork publishes no windows-arm64-cuda bundle yet, so take upstream ggml-org's, the same release this fork
- # repackages. Verified against GitHub's per-asset digest; an asset it states no digest for is refused, not installed.
- verified = _apply_release_digests(
- upstream_arm64_cuda,
- github_release_asset_digests(UPSTREAM_REPO, llama_tag),
- )
- if verified:
- log(
- "no approved checksum covers a Windows ARM64 CUDA bundle "
- f"({exc}); installing the upstream {UPSTREAM_REPO} bundle "
- f"{verified[0].name}, verified against the release asset digest "
- "GitHub reports. Set UNSLOTH_LLAMA_ARM64_CUDA=0 to use the CPU "
- "bundle instead."
- )
- return verified
- log(
- "no approved checksum covers a Windows ARM64 CUDA bundle "
- f"({exc}), and GitHub reports no asset digest for the upstream "
- f"{UPSTREAM_REPO} bundle either; refusing to install it unverified "
- "and falling through to the ARM64 CPU bundle."
- )
published_choice = published_asset_choice_for_kind(release, "windows-arm64")
elif host.is_macos and host.is_arm64:
published_choice = published_asset_choice_for_kind(release, "macos-arm64")
@@ -4365,6 +4331,12 @@ def resolve_release_asset_choice(
f"{release.repo}@{release.release_tag} {published_choice.name} ({exc})"
)
+ if release.repo == DEFAULT_PUBLISHED_REPO:
+ # The upstream filename resolver below lists ggml-org's release; the fork never uses it.
+ raise PrebuiltFallback(
+ f"no compatible published prebuilt in {release.repo}@{release.release_tag} "
+ f"for {host.system} {host.machine}"
+ )
return apply_approved_hashes(
[resolve_asset_choice(host, llama_tag)],
checksums,
@@ -4408,12 +4380,21 @@ def copy_globs(
shutil.copy2(path, destination / name)
-def ensure_converter_scripts(install_dir: Path, llama_tag: str) -> None:
+def ensure_converter_scripts(
+ install_dir: Path,
+ llama_tag: str,
+ *,
+ repo: str | None = None,
+ release_tag: str | None = None,
+) -> None:
canonical = install_dir / "convert_hf_to_gguf.py"
if not canonical.exists():
- # Hydrated source tree should have placed this file already.
- # Fall back to a network fetch so the install is not blocked.
- raw_base = f"https://raw.githubusercontent.com/ggml-org/llama.cpp/{llama_tag}"
+ # Hydration normally placed it; else the fork at the installed mix tag (bare bNNNN tags are not pushed).
+ source_repo = repo or DEFAULT_PUBLISHED_REPO
+ ref = release_tag or llama_tag
+ raw_base = (
+ f"https://raw.githubusercontent.com/{source_repo}/{urllib.parse.quote(ref, safe = '')}"
+ )
source_url = f"{raw_base}/convert_hf_to_gguf.py"
data = download_bytes(
source_url,
@@ -10754,20 +10735,7 @@ def _route_to_vulkan_prebuilt(
else:
log("Intel GPU detected; installing the Vulkan llama.cpp prebuilt")
persist_backend = None
- # The fork manifest's Vulkan app bundles are x64 only, and the architecture
- # filter in published_asset_choice_for_kind rejects them for an ARM64 host, so
- # the fork planner returns no Vulkan attempt at all there. Strict Vulkan
- # filtering then drops the ARM64 CPU attempt too and the install resolves to
- # nothing. Upstream does publish llama-<tag>-bin-ubuntu-vulkan-arm64.tar.gz, so
- # keep routing Linux ARM64 there (Windows arm64 exits above via
- # _has_no_vulkan_prebuilt, macOS via the Metal branch).
- if (published_repo or DEFAULT_PUBLISHED_REPO) == DEFAULT_PUBLISHED_REPO and (
- host.is_linux and host.is_arm64
- ):
- # Fork and upstream use different tag namespaces (fork b9596-mix-<sha> vs
- # upstream b9596), so carrying a fork pin over would make the upstream
- # resolver query a release that does not exist.
- return host, UPSTREAM_REPO, "", persist_backend
+ # A fork release without a linux-vulkan-arm64 bundle source-builds; no upstream prebuilt.
return host, published_repo, published_release_tag, persist_backend
@@ -11508,7 +11476,12 @@ def install_prebuilt(
activate_install_tree(selected_staging_dir, install_dir, host)
try:
- ensure_converter_scripts(install_dir, plan.llama_tag)
+ ensure_converter_scripts(
+ install_dir,
+ plan.llama_tag,
+ repo = published_repo or DEFAULT_PUBLISHED_REPO,
+ release_tag = plan.release_tag,
+ )
except Exception as exc:
log(
"converter script fetch failed after activation; install remains valid "
diff --git a/tests/studio/install/test_cuda_driver_floor_12842.py b/tests/studio/install/test_cuda_driver_floor_12842.py
index 7908d840f07..e54d9a29596 100644
--- a/tests/studio/install/test_cuda_driver_floor_12842.py
+++ b/tests/studio/install/test_cuda_driver_floor_12842.py
@@ -242,7 +242,9 @@ class TestWindowsBelowTheFloorGetsTheCpuBundle:
assert choices and all(c.install_kind == "windows-cuda" for c in choices)
def test_a_cuda_11_driver_keeps_its_old_route(self, monkeypatch):
- assert self._choices(monkeypatch, (11, 8)) == []
+ # No fork bundle covers it; the caller turned main's empty list into this same fallback.
+ with pytest.raises(m.PrebuiltFallback, match = "no published Windows CUDA bundle"):
+ self._choices(monkeypatch, (11, 8))
class TestTheSourceStageDoesNotKeepABrokenCudaPrebuilt:
diff --git a/tests/studio/install/test_install_llama_prebuilt_logic.py b/tests/studio/install/test_install_llama_prebuilt_logic.py
index d9a4a9246af..1e9b576b7a0 100644
--- a/tests/studio/install/test_install_llama_prebuilt_logic.py
+++ b/tests/studio/install/test_install_llama_prebuilt_logic.py
@@ -2469,7 +2469,7 @@ def test_install_prebuilt_falls_back_to_older_release_plan(
monkeypatch.setattr(
INSTALL_LLAMA_PREBUILT,
"ensure_converter_scripts",
- lambda install_dir, llama_tag: ensured_tags.append(llama_tag),
+ lambda install_dir, llama_tag, **kwargs: ensured_tags.append(llama_tag),
)
install_prebuilt(install_dir, "latest", "unslothai/llama.cpp", "")
@@ -3741,7 +3741,7 @@ def test_install_prebuilt_same_tag_upstream_failure_uses_older_unsloth_release_p
monkeypatch.setattr(
INSTALL_LLAMA_PREBUILT,
"ensure_converter_scripts",
- lambda install_dir, llama_tag: None,
+ lambda install_dir, llama_tag, **kwargs: None,
)
install_prebuilt(install_dir, "latest", "unslothai/llama.cpp", "")
diff --git a/tests/studio/install/test_selection_logic.py b/tests/studio/install/test_selection_logic.py
index 32791d324a8..c700cbfb39a 100644
--- a/tests/studio/install/test_selection_logic.py
+++ b/tests/studio/install/test_selection_logic.py
@@ -1759,7 +1759,10 @@ class TestResolveInstallAttempts:
assert attempts[0].expected_sha256 == "a" * 64
assert approved.release_tag == "llama-prebuilt-latest"
- def test_windows_cuda_uses_selected_release_upstream_tag(self, monkeypatch):
+ def test_windows_cuda_fork_never_falls_back_to_upstream_assets(self, monkeypatch):
+ # The fork's checksums once approved an upstream ggml-org Windows CUDA zip by name;
+ # prebuilts now come only from the fork, so a release without a covering published
+ # bundle raises (older release / source build) and never lists ggml-org's assets.
host = make_host(system = "Windows", machine = "AMD64")
host.driver_cuda_version = (12, 4)
mock_windows_runtime(monkeypatch, ["cuda12"])
@@ -1771,41 +1774,19 @@ class TestResolveInstallAttempts:
)
mock_published_releases(monkeypatch, release, checksums)
- monkeypatch.setattr(
- INSTALL_LLAMA_PREBUILT,
- "github_release_assets",
- lambda repo, tag: {
+ listed = []
+
+ def _assets(repo, tag):
+ listed.append(repo)
+ return {
f"llama-{tag}-bin-win-cuda-12.4-x64.zip": f"https://example.com/llama-{tag}-bin-win-cuda-12.4-x64.zip"
- },
- )
- monkeypatch.setattr(
- INSTALL_LLAMA_PREBUILT,
- "resolve_windows_cuda_choices",
- lambda host, tag, assets: [
- AssetChoice(
- repo = UPSTREAM_REPO,
- tag = tag,
- name = f"llama-{tag}-bin-win-cuda-12.4-x64.zip",
- url = assets[f"llama-{tag}-bin-win-cuda-12.4-x64.zip"],
- source_label = "upstream",
- install_kind = "windows-cuda",
- runtime_line = "cuda12",
- )
- ],
- )
+ }
- requested_tag, resolved_tag, attempts, approved = resolve_install_attempts(
- "latest",
- host,
- "unslothai/llama.cpp",
- "",
- )
+ monkeypatch.setattr(INSTALL_LLAMA_PREBUILT, "github_release_assets", _assets)
- assert requested_tag == "latest"
- assert resolved_tag == "b9000"
- assert attempts[0].name == "llama-b9000-bin-win-cuda-12.4-x64.zip"
- assert attempts[0].expected_sha256 == "a" * 64
- assert approved.release_tag == "llama-prebuilt-latest"
+ with pytest.raises(PrebuiltFallback, match = "no published Windows CUDA bundle"):
+ resolve_install_attempts("latest", host, "unslothai/llama.cpp", "")
+ assert UPSTREAM_REPO not in listed
def test_linux_cpu_fork_without_bundle_raises_no_upstream_fallback(self, monkeypatch):
# CPU-only Linux routes to the fork. If a release manifest ships no CPU bundle the resolver raises rather
@@ -2081,7 +2062,7 @@ class TestResolveInstallAttempts:
with pytest.raises(
PrebuiltFallback,
- match = "approved checksum asset did not contain the selected prebuilt archive",
+ match = "no compatible published prebuilt in unslothai/llama.cpp",
):
resolve_install_attempts(
"latest",
@@ -5043,3 +5024,155 @@ class TestUpstreamDigestKeepsTheFunctionalSmokeTest:
assert any(
INSTALL_LLAMA_PREBUILT.prebuilt_needs_functional_validation(a) for a in plan.attempts
), "the probe would be resolved lazily inside the per-candidate handler"
+
+
+# ===========================================================================
+# Fork-only prebuilts: no default path downloads from upstream ggml-org
+# ===========================================================================
+
+
+class TestForkOnlyPrebuilts:
+ """Prebuilt binaries and converter scripts come only from unslothai/llama.cpp releases."""
+
+ TAG = "b11443-mix-d65395f"
+ UPSTREAM = "b11443"
+ ARM64_CUDA = f"app-{TAG}-windows-arm64-cuda13-portable.zip"
+ ARM64_CPU = f"app-{TAG}-windows-arm64-cpu.zip"
+
+ def _arm64_release(self):
+ # The two Windows ARM64 entries exactly as the fork's llama-prebuilt-manifest.json lists them.
+ artifacts = [
+ make_artifact(
+ self.ARM64_CUDA,
+ install_kind = "windows-arm64-cuda",
+ bundle_profile = "cuda13-portable",
+ runtime_line = "cuda13",
+ coverage_class = "portable",
+ supported_sms = ["120", "121"],
+ min_sm = 120,
+ max_sm = 121,
+ rank = 60,
+ ),
+ make_cpu_artifact(
+ self.ARM64_CPU,
+ install_kind = "windows-arm64",
+ bundle_profile = "windows-cpu-arm64",
+ rank = 1000,
+ ),
+ ]
+ return make_release(artifacts, release_tag = self.TAG, upstream_tag = self.UPSTREAM)
+
+ def _no_upstream(self, monkeypatch):
+ listed = []
+
+ def _record(repo, tag):
+ listed.append(repo)
+ return {}
+
+ monkeypatch.setattr(INSTALL_LLAMA_PREBUILT, "github_release_assets", _record)
+ monkeypatch.setattr(INSTALL_LLAMA_PREBUILT, "github_release_asset_digests", _record)
+ return listed
+
+ def _arm64_host(self, caps):
+ return make_host(
+ system = "Windows", machine = "ARM64", driver_cuda_version = (13, 4), compute_caps = caps
+ )
+
+ def _prefer(self, monkeypatch):
+ mock_windows_runtime(monkeypatch, ["cuda13"])
+ monkeypatch.setattr(
+ INSTALL_LLAMA_PREBUILT,
+ "detect_torch_cuda_runtime_preference",
+ lambda host: CudaRuntimePreference(runtime_line = None, selection_log = []),
+ )
+ monkeypatch.delenv("UNSLOTH_LLAMA_ARM64_CUDA", raising = False)
+
+ def test_windows_arm64_nvidia_selects_the_fork_cuda_bundle(self, monkeypatch):
+ self._prefer(monkeypatch)
+ listed = self._no_upstream(monkeypatch)
+ result = resolve_release_asset_choice(
+ self._arm64_host(["121"]),
+ self.UPSTREAM,
+ self._arm64_release(),
+ make_checksums([self.ARM64_CUDA, self.ARM64_CPU]),
+ )
+ assert [a.name for a in result] == [self.ARM64_CUDA]
+ assert result[0].repo == "unslothai/llama.cpp"
+ assert result[0].install_kind == "windows-arm64-cuda"
+ assert listed == []
+
+ def test_windows_arm64_uncovered_gpu_takes_the_fork_cpu_bundle_not_upstream(self, monkeypatch):
+ """An sm_89 card is outside the fork bundle's 120-121 coverage: CPU bundle, never ggml-org."""
+ self._prefer(monkeypatch)
+ listed = self._no_upstream(monkeypatch)
+ result = resolve_release_asset_choice(
+ self._arm64_host(["89"]),
+ self.UPSTREAM,
+ self._arm64_release(),
+ make_checksums([self.ARM64_CUDA, self.ARM64_CPU]),
+ )
+ assert [a.name for a in result] == [self.ARM64_CPU]
+ assert result[0].repo == "unslothai/llama.cpp"
+ assert UPSTREAM_REPO not in listed
+
+ def test_fork_release_without_a_platform_bundle_never_lists_upstream(self, monkeypatch):
+ listed = self._no_upstream(monkeypatch)
+ host = make_host(system = "Darwin", machine = "arm64", has_usable_nvidia = False)
+ with pytest.raises(PrebuiltFallback, match = "no compatible published prebuilt"):
+ resolve_release_asset_choice(
+ host, self.UPSTREAM, make_release([], release_tag = self.TAG), make_checksums([])
+ )
+ assert listed == []
+
+ def test_converter_fallback_fetches_from_the_fork_release_tag(self, monkeypatch, tmp_path):
+ urls = []
+
+ def _download(url, **kwargs):
+ urls.append(url)
+ return b"import sys\n"
+
+ monkeypatch.setattr(INSTALL_LLAMA_PREBUILT, "download_bytes", _download)
+ INSTALL_LLAMA_PREBUILT.ensure_converter_scripts(
+ tmp_path, self.UPSTREAM, repo = "unslothai/llama.cpp", release_tag = self.TAG
+ )
+ assert urls == [
+ f"https://raw.githubusercontent.com/unslothai/llama.cpp/{self.TAG}/convert_hf_to_gguf.py"
+ ]
+ assert (tmp_path / "convert_hf_to_gguf.py").read_bytes() == b"import sys\n"
+
+ def test_converter_fallback_defaults_to_the_fork(self, monkeypatch, tmp_path):
+ urls = []
+ monkeypatch.setattr(
+ INSTALL_LLAMA_PREBUILT,
+ "download_bytes",
+ lambda url, **kwargs: urls.append(url) or b"import sys\n",
+ )
+ INSTALL_LLAMA_PREBUILT.ensure_converter_scripts(tmp_path, self.TAG)
+ assert urls and "ggml-org" not in urls[0]
+ assert urls[0].startswith("https://raw.githubusercontent.com/unslothai/llama.cpp/")
+
+ def test_linux_arm64_vulkan_stays_on_the_fork(self, monkeypatch):
+ host = make_host(
+ system = "Linux",
+ machine = "aarch64",
+ has_usable_nvidia = False,
+ has_physical_nvidia = False,
+ nvidia_smi = None,
+ )
+ _host, repo, tag, _persist = INSTALL_LLAMA_PREBUILT._route_to_vulkan_prebuilt(
+ host, "unslothai/llama.cpp", self.TAG, force_cpu = False, llama_backend = "vulkan"
+ )
+ assert (repo, tag) == ("unslothai/llama.cpp", self.TAG)
+ release = make_release(
+ [
+ make_cpu_artifact(
+ f"app-{self.TAG}-linux-arm64-vulkan.tar.gz",
+ install_kind = "linux-vulkan",
+ bundle_profile = "linux-vulkan-arm64",
+ rank = 60,
+ )
+ ],
+ release_tag = self.TAG,
+ )
+ attempts = INSTALL_LLAMA_PREBUILT._linux_published_attempts(_host, release)
+ assert [a.name for a in attempts][:1] == [f"app-{self.TAG}-linux-arm64-vulkan.tar.gz"]