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
"""Caching is safe only for content-addressed downloads, never the venv or a cold-install lane."""
from __future__ import annotations
import re
from pathlib import Path
import pytest
import yaml
REPO_ROOT = Path(__file__).resolve().parents[2]
ACTION = REPO_ROOT / ".github" / "actions" / "install-unsloth-local" / "action.yml"
WORKFLOWS = REPO_ROOT / ".github" / "workflows"
# Named, not detected: removing a cold-machine lane must be a deliberate diff.
COLD_INSTALL_WORKFLOWS = (
"clean-machine-install-ci.yml",
"desktop-app-clean-machine-ci.yml",
"interrupted-install-ci.yml",
# A restored dist would ship a bundle this run never built.
"release-desktop.yml",
)
def _own_steps(action: Path = ACTION) -> list[dict]:
return yaml.safe_load(action.read_text(encoding = "utf-8"))["runs"]["steps"]
def _steps() -> list[dict]:
"""Steps of this action plus those of every local action it delegates to, so no cache goes unseen."""
flat: list[dict] = []
for step in _own_steps():
uses = str(step.get("uses", ""))
local = re.match(r"\./\.github/actions/([\w-]+)$", uses)
if local:
nested = REPO_ROOT / ".github" / "actions" / local.group(1) / "action.yml"
assert nested.is_file(), f"{uses} does not exist, so this action cannot run"
flat.extend(_own_steps(nested))
else:
flat.append(step)
return flat
def _index_of(predicate) -> int:
for i, step in enumerate(_steps()):
if predicate(step):
return i
return -1
# Allowed cache paths. .uv-cache is content-addressed, so a stale entry can only miss.
# studio/frontend/dist is static assets keyed on setup.sh's rebuild inputs; see
# tests/studio/test_frontend_dist_cache.py.
CACHEABLE_PATHS = (".uv-cache", "studio/frontend/dist")
def test_the_cache_holds_downloads_and_build_output_but_never_the_venv() -> None:
"""Caches may hold downloads and build output, never the venv (editable overlay, absolute paths)."""
for step in _steps():
if "cache" not in str(step.get("uses", "")):
continue
path = str((step.get("with") or {}).get("path", ""))
assert any(allowed in path for allowed in CACHEABLE_PATHS), (
f"cache step points at {path!r}, which is not one of the paths this action "
f"is allowed to cache ({', '.join(CACHEABLE_PATHS)}). Add it to "
f"CACHEABLE_PATHS with the argument for why restoring it cannot be wrong."
)
for forbidden in (".unsloth", "site-packages", "unsloth_studio", "venv"):
assert forbidden not in path, (
f"cache step points at {path!r}, which is an INSTALL, not a download "
f"cache. A restored install can be wrong; a restored download cannot."
)
def test_uv_cache_dir_is_set_before_the_install_runs() -> None:
"""Set afterwards it configures nothing, and the step would still look right."""
setter = _index_of(lambda s: "UV_CACHE_DIR" in str(s.get("run", "")))
install = _index_of(lambda s: "install.sh --local --no-torch" in str(s.get("run", "")))
assert setter != -1, "the action no longer points UV_CACHE_DIR anywhere"
assert install != -1, "the action no longer runs the local install"
assert setter < install, (
"UV_CACHE_DIR is set after the install, so the install used uv's default "
"cache and the restored one was never read"
)
def test_the_restore_happens_before_the_install_too() -> None:
restore = _index_of(lambda s: "cache/restore" in str(s.get("uses", "")))
install = _index_of(lambda s: "install.sh --local --no-torch" in str(s.get("run", "")))
assert restore != -1 and restore < install
def test_a_near_miss_still_supplies_most_wheels() -> None:
"""Restore-keys fallback is correct only for content-addressed entries; on a venv it would be a bug."""
restore = next(s for s in _steps() if "cache/restore" in str(s.get("uses", "")))
assert (restore.get("with") or {}).get("restore-keys"), (
"no restore-keys, so any change to requirements or pyproject drops the "
"cache to zero instead of to almost-full"
)
def test_the_cache_is_saved_on_main_only() -> None:
"""Saved on main only: PR entries serve only their PR, and PR saves evict main's copy."""
saves = [s for s in _steps() if "cache/save" in str(s.get("uses", ""))]
assert saves, "the cache is never saved, so it can never be restored either"
for step in saves:
condition = str(step.get("if", ""))
assert (
"refs/heads/main" in condition
), f"a cache/save step is not gated on main: if: {condition!r}"
@pytest.mark.parametrize("name", COLD_INSTALL_WORKFLOWS)
def test_cold_install_lanes_never_adopt_this_action(name: str) -> None:
"""Cold lanes must not adopt this action: GITHUB_ENV's UV_CACHE_DIR outranks a job-level env."""
path = WORKFLOWS / name
if not path.exists():
pytest.skip(f"{name} no longer exists")
text = path.read_text(encoding = "utf-8")
assert "install-unsloth-local" not in text, (
f"{name} uses install-unsloth-local, which warms uv's cache. A cached "
f"cold-install test proves nothing and still goes green."
)
# The Windows jobs adopt the dist cache without this action, so check it separately.
assert "frontend-dist-" not in text, (
f"{name} restores a prebuilt frontend. A cold-install lane handed a bundle built "
f"on another machine last week is not testing a cold install."
)
def test_the_action_is_actually_used() -> None:
"""Otherwise every assertion above guards something nothing runs."""
users = [
p.name
for p in WORKFLOWS.glob("*.yml")
if "install-unsloth-local" in p.read_text(encoding = "utf-8")
]
assert len(users) >= 5, f"only {len(users)} workflows use the action: {users}"
# Windows jobs skip install-unsloth-local, so the uv-cache restore and save are separate actions.
ACTIONS = REPO_ROOT / ".github" / "actions"
UV_RESTORE = ACTIONS / "uv-cache-restore" / "action.yml"
UV_SAVE = ACTIONS / "uv-cache-save" / "action.yml"
# Cold at job level; mirrors the list in tests/studio/test_frontend_dist_cache.py.
COLD_INSTALL_JOBS = (("studio-windows-inference-smoke.yml", "no-vs-cpu"),)
# An invocation, not a mention: mlx-ci.yml's comment names `install.sh --local`.
_INSTALLER = re.compile(r"(?m)^\s*[^#\n]*?(?:^|[\s/&'\"])install\.(?:ps1|sh) --local")
_HELPER = re.compile(r"\.github/scripts/([A-Za-z0-9_.-]+\.sh)")
def _runs_installer(step: dict) -> bool:
"""Also follows one level into a helper script the step runs, since installs can sit one file away."""
run = str(step.get("run", ""))
if _INSTALLER.search(run):
return True
for helper in _HELPER.findall(run):
path = REPO_ROOT / ".github" / "scripts" / helper
if path.is_file() and _INSTALLER.search(path.read_text(encoding = "utf-8", errors = "replace")):
return True
return False
def _jobs():
for f in sorted(WORKFLOWS.glob("*.yml")):
doc = yaml.safe_load(f.read_text(encoding = "utf-8"))
if isinstance(doc, dict) and isinstance(doc.get("jobs"), dict):
for jid, job in doc["jobs"].items():
if isinstance(job, dict):
yield f.name, jid, job
def _produces_on_main(name: str) -> bool:
"""Same rule as the dist guard: `push` to main or `schedule`, never `workflow_dispatch`."""
doc = yaml.safe_load((WORKFLOWS / name).read_text(encoding = "utf-8"))
on = doc.get("on", doc.get(True)) or {}
if isinstance(on, str):
on = {on: None}
elif isinstance(on, list):
on = dict.fromkeys(on)
if "schedule" in on:
return True
if "push" not in on:
return False
push = on.get("push")
branches = push.get("branches") if isinstance(push, dict) else None
return branches is None or "main" in branches
def test_the_uv_cache_key_has_exactly_one_definition() -> None:
"""A second copy agrees today and drifts silently, with the cache still hitting."""
definers = []
for path in sorted(list(ACTIONS.rglob("action.yml")) + list(WORKFLOWS.glob("*.yml"))):
if re.search(r"key:\s*uv-\$\{\{", path.read_text(encoding = "utf-8")):
definers.append(str(path.relative_to(REPO_ROOT)))
assert definers == [
".github/actions/uv-cache-restore/action.yml"
], f"the uv cache key is defined in {definers}; it must have exactly one definition"
def test_install_unsloth_local_delegates_the_uv_cache() -> None:
uses = [str(s.get("uses", "")) for s in _own_steps()]
assert "./.github/actions/uv-cache-restore" in uses, uses
assert "./.github/actions/uv-cache-save" in uses, uses
assert not any("actions/cache" in u for u in uses), (
"install-unsloth-local carries its own cache step again; the key must stay in "
"uv-cache-restore"
)
def test_the_uv_actions_nest_nothing() -> None:
"""The uv cache actions stay leaves, so a job with a nested checkout can still call them."""
for action in (UV_RESTORE, UV_SAVE):
nested = [
str(s.get("uses", ""))
for s in _own_steps(action)
if str(s.get("uses", "")).startswith("./")
]
assert not nested, f"{action.relative_to(REPO_ROOT)} nests {nested}"
def test_every_warm_installer_job_restores_the_uv_cache() -> None:
"""Every installer job must restore the uv cache, unless it is a named cold-install exception."""
offenders = []
for name, jid, job in _jobs():
if name in COLD_INSTALL_WORKFLOWS or (name, jid) in COLD_INSTALL_JOBS:
continue
steps = job.get("steps") or []
runs_installer = any(_runs_installer(s) for s in steps)
if not runs_installer:
continue
restores = any(
"uv-cache-restore" in str(s.get("uses", ""))
or "install-unsloth-local" in str(s.get("uses", ""))
for s in steps
)
if not restores:
offenders.append(f"{name}:{jid}")
assert not offenders, (
"these jobs run the installer with no uv download cache, so every run downloads "
"every wheel again:\n " + "\n ".join(offenders)
)
def test_every_uv_restore_is_paired_with_a_save_wired_to_it() -> None:
"""A restore without a save fills nothing; save flags come from triggers, not an allowlist."""
offenders = []
for name, jid, job in _jobs():
steps = job.get("steps") or []
restore = next((s for s in steps if "uv-cache-restore" in str(s.get("uses", ""))), None)
save = next((s for s in steps if "uv-cache-save" in str(s.get("uses", ""))), None)
if restore is None and save is None:
continue
if restore is None or save is None:
offenders.append(f"{name}:{jid}: restore={restore is not None} save={save is not None}")
continue
ident = restore.get("id")
if not ident:
offenders.append(f"{name}:{jid}: the restore step has no id")
continue
with_ = save.get("with") or {}
for field in ("cache-hit", "key"):
if f"steps.{ident}.outputs.{field}" not in str(with_.get(field, "")):
offenders.append(f"{name}:{jid}: save does not take {field} from steps.{ident}")
installs = [i for i, s in enumerate(steps) if _runs_installer(s)]
if not installs:
offenders.append(f"{name}:{jid}: restores the uv cache but never runs an installer")
continue
if steps.index(restore) > min(installs):
offenders.append(f"{name}:{jid}: the restore runs after the install")
if steps.index(save) < max(installs):
offenders.append(f"{name}:{jid}: the save runs before the install")
uploads = str(with_.get("save", "true")) != "false"
if uploads and not _produces_on_main(name):
offenders.append(
f"{name}:{jid}: saves, but {name} never runs on main; pass save: 'false'"
)
if not uploads and _produces_on_main(name):
offenders.append(f"{name}:{jid}: passes save: 'false', but {name} runs on main")
assert not offenders, "\n ".join(["broken uv cache wiring:"] + offenders)
@pytest.mark.parametrize("name", COLD_INSTALL_WORKFLOWS)
def test_cold_install_lanes_never_adopt_the_uv_actions(name: str) -> None:
path = WORKFLOWS / name
if not path.exists():
pytest.skip(f"{name} no longer exists")
assert "uv-cache-" not in path.read_text(
encoding = "utf-8"
), f"{name} restores a warm uv cache; a cached cold-install test proves nothing"
@pytest.mark.parametrize("name,jid", COLD_INSTALL_JOBS)
def test_cold_install_jobs_never_adopt_the_uv_actions(name: str, jid: str) -> None:
doc = yaml.safe_load((WORKFLOWS / name).read_text(encoding = "utf-8"))
job = (doc.get("jobs") or {}).get(jid)
assert job is not None, f"{name} no longer has job {jid}; update COLD_INSTALL_JOBS"
offenders = [
str(s.get("uses", ""))
for s in job.get("steps") or []
if "uv-cache-" in str(s.get("uses", ""))
]
assert not offenders, f"{name}:{jid} is a deliberate cold-install lane: {offenders}"
def test_the_uv_actions_are_actually_used_directly() -> None:
"""The Windows jobs are the reason the pair exists; if none calls it, it is dead code."""
direct = [
p.name
for p in WORKFLOWS.glob("*.yml")
if "uv-cache-restore" in p.read_text(encoding = "utf-8")
]
assert (
len(direct) >= 4
), f"only {len(direct)} workflows call uv-cache-restore directly: {direct}"