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
"""An exported image LoRA dropped into a custom models folder shows up in the Images LoRA picker, and
never as a model in the model pickers."""
from __future__ import annotations
import asyncio
import json
import os
import struct
import pytest
from core.inference import diffusion_lora as dl
import storage.studio_db as studio_db
_MARK = {"kind": "diffusion-lora"}
_LORA_KEY = "unet.down.0.lora_A.weight"
_MODEL_KEY = "model.layers.0.self_attn.q_proj.weight"
def _safetensors(
path,
sidecar = None,
key = _LORA_KEY,
):
path.parent.mkdir(parents = True, exist_ok = True)
header = json.dumps({key: {"dtype": "F32", "shape": [1], "data_offsets": [0, 4]}}).encode()
path.write_bytes(struct.pack("<Q", len(header)) + header + b"\0\0\0\0")
if sidecar is not None:
path.with_suffix(".json").write_text(json.dumps(sidecar))
return path
# The registered-folder table itself (normalisation, denylist) is covered elsewhere; macOS tmp_path
# lives under /private/var, which registration refuses, so the rows are faked here.
_FOLDERS: list = []
def register(folder):
_FOLDERS.append({"path": str(folder)})
@pytest.fixture(autouse = True)
def _folders(monkeypatch):
_FOLDERS.clear()
monkeypatch.setattr(studio_db, "list_scan_folders", lambda: list(_FOLDERS))
@pytest.fixture
def catalog(tmp_path, monkeypatch):
d = tmp_path / "loras"
d.mkdir()
monkeypatch.setattr(dl, "loras_dir", lambda: d)
return d
def _local():
return {e.id: e for e in dl.list_loras() if e.source == "local"}
def _by_path(path):
return next(e for e in _local().values() if e.local_path == str(path))
def test_an_export_in_a_custom_folder_is_listed(catalog, tmp_path):
(catalog / "mystyle.safetensors").write_bytes(b"w")
(catalog / "mystyle.json").write_text(
json.dumps({"family": "sdxl", "source": "studio-trained"})
)
folder = tmp_path / "my-models"
dl.export_local_lora("mystyle", folder / "image-loras")
(catalog / "mystyle.safetensors").unlink()
(catalog / "mystyle.json").unlink()
register(str(folder))
entry = _by_path(folder / "image-loras" / "mystyle.safetensors")
assert entry.display_name == "mystyle" and entry.id.startswith("mystyle-")
assert entry.families == ("sdxl",) and entry.fine_tuned
assert dl.resolve_one(entry.id, 1.0).path == entry.local_path
def test_unmarked_weights_in_a_custom_folder_are_ignored(catalog, tmp_path):
folder = tmp_path / "my-models"
_safetensors(folder / "model.safetensors", key = _MODEL_KEY)
_safetensors(folder / "notes.safetensors", sidecar = {"family": "sdxl"}, key = _MODEL_KEY)
register(str(folder))
assert _local() == {}
def test_a_third_party_lora_without_a_sidecar_is_listed(catalog, tmp_path):
folder = tmp_path / "my-models"
lora = _safetensors(folder / "pixel-art" / "style.safetensors", key = "lora_unet_down.alpha")
register(folder)
entry = _by_path(lora)
assert entry.display_name == "style" and entry.families == () and not entry.fine_tuned
assert dl.resolve_one(entry.id, 1.0).path == str(lora)
@pytest.mark.parametrize(
"drop",
[
"style.safetensors",
"hub/style.safetensors",
"hub/loras/style.safetensors",
"loras/style.safetensors",
],
)
def test_a_lora_dropped_in_the_models_folder_is_listed(catalog, tmp_path, monkeypatch, drop):
import utils.hf_cache_settings as settings
home = tmp_path / "models"
paths = type("Paths", (), {"cache_home": home, "hub_cache": home / "hub"})()
monkeypatch.setattr(settings, "get_hf_cache_paths", lambda: paths)
lora = _safetensors(home / drop)
_safetensors(home / "hub" / "models--a--b" / "snapshots" / "c" / "deep.safetensors")
assert [e.local_path for e in _local().values()] == [str(lora)]
@pytest.mark.parametrize("registered", ["ComfyUI", "ComfyUI/models"])
def test_loras_under_a_comfyui_folder_are_listed(catalog, tmp_path, registered):
models = tmp_path / "ComfyUI" / "models"
(models / "checkpoints").mkdir(parents = True)
lora = _safetensors(models / "loras" / "flux" / "style.safetensors")
register(tmp_path / registered)
assert [e.local_path for e in _local().values()] == [str(lora)]
def test_loras_listed_in_extra_model_paths_yaml_are_listed(catalog, tmp_path, monkeypatch):
from hub.storage import scan_folders
monkeypatch.setattr(scan_folders, "_denied_path_prefixes", lambda: [])
root = tmp_path / "ComfyUI"
(root / "models" / "checkpoints").mkdir(parents = True)
lora = _safetensors(tmp_path / "shared" / "Lora" / "style.safetensors")
(root / "extra_model_paths.yaml").write_text(
f"a111:\n base_path: {tmp_path / 'shared'}\n loras: Lora\n"
)
register(root)
assert [e.local_path for e in _local().values()] == [str(lora)]
def test_a_chat_adapter_in_a_custom_folder_stays_out_of_the_picker(catalog, tmp_path):
from hub.services.models.local_inventory import _scan_models_dir
folder = tmp_path / "my-models"
adapter = folder / "chat-lora"
_safetensors(adapter / "adapter_model.safetensors")
(adapter / "adapter_config.json").write_text(json.dumps({"peft_type": "LORA"}))
register(folder)
assert _local() == {}
assert [row.display_name for row in _scan_models_dir(folder)] == ["chat-lora"]
def test_header_of_an_unchanged_lora_is_read_once(catalog, tmp_path, monkeypatch):
from core.inference import diffusion_content
folder = tmp_path / "my-models"
lora = _safetensors(folder / "style.safetensors")
register(folder)
reads = []
real = diffusion_content._read_safetensors_header
monkeypatch.setattr(
diffusion_content, "_read_safetensors_header", lambda p: reads.append(p) or real(p)
)
assert len(_local()) == len(_local()) == 1
assert reads == [str(lora)]
def test_an_export_keeps_a_foreign_json_beside_an_identical_lora(catalog, tmp_path):
_safetensors(catalog / "style.safetensors")
dest = tmp_path / "out"
_safetensors(dest / "style.safetensors", sidecar = {"note": "mine"})
assert dl.export_local_lora("style", dest).name == "style-2.safetensors"
assert json.loads((dest / "style.json").read_text()) == {"note": "mine"}
def test_custom_folder_ids_stay_stable_when_folders_change(catalog, tmp_path):
(catalog / "style.safetensors").write_bytes(b"catalog")
folders = [tmp_path / name for name in ("a", "b", "c")]
for folder in folders:
_safetensors(folder / "style.safetensors", sidecar = _MARK)
register(str(folder))
assert _local()["style"].local_path == str(catalog / "style.safetensors")
ids = {str(f): _by_path(f / "style.safetensors").id for f in folders}
assert len(set(ids.values())) == 3 and not _by_path(folders[2] / "style.safetensors").fine_tuned
_FOLDERS.pop(0)
for folder in folders[1:]:
assert _by_path(folder / "style.safetensors").id == ids[str(folder)]
assert ids[str(folders[0])] not in _local()
def test_the_catalog_registered_as_a_custom_folder_is_not_listed_twice(catalog, tmp_path):
_safetensors(catalog / "style.safetensors", sidecar = _MARK)
register(str(catalog))
assert list(_local()) == ["style"]
@pytest.mark.parametrize("scanner", ["routes", "inventory"])
def test_marked_loras_are_not_listed_as_models(tmp_path, scanner):
if scanner == "routes":
from routes.models import _scan_models_dir
else:
from hub.services.models.local_inventory import _scan_models_dir
folder = tmp_path / "image-loras"
_safetensors(folder / "a.safetensors", sidecar = _MARK)
_safetensors(folder / "b.safetensors", sidecar = {"source": "studio-trained"})
assert _scan_models_dir(folder) == []
assert _scan_models_dir(tmp_path) == []
_safetensors(tmp_path / "plain" / "style.safetensors")
assert _scan_models_dir(tmp_path) == []
_safetensors(tmp_path / "checkpoint" / "model.safetensors", key = _MODEL_KEY)
assert [row.display_name for row in _scan_models_dir(tmp_path)] == ["checkpoint"]
def test_the_picker_route_reports_fine_tuned(catalog):
from routes.models import scan_diffusion_loras
_safetensors(catalog / "trained.safetensors", sidecar = {"source": "studio-trained", **_MARK})
_safetensors(catalog / "downloaded.safetensors")
rows = asyncio.run(scan_diffusion_loras(family = None, current_subject = "subject"))["loras"]
flags = {row["id"]: row["fine_tuned"] for row in rows if row["source"] == "local"}
assert flags == {"trained": True, "downloaded": False}
@pytest.mark.parametrize("scanner", ["routes", "inventory"])
def test_a_marked_gguf_in_a_subfolder_is_not_a_model(tmp_path, scanner):
if scanner == "routes":
from routes.models import _scan_models_dir
else:
from hub.services.models.local_inventory import _scan_models_dir
folder = tmp_path / "image-loras"
folder.mkdir()
(folder / "style.gguf").write_bytes(b"GGUF" + b"\0" * 60)
(folder / "style.json").write_text(json.dumps(_MARK))
assert _scan_models_dir(tmp_path) == []
def test_a_managed_account_only_sees_custom_folder_loras_it_may_access(
catalog, tmp_path, monkeypatch
):
from hub.services.models import account_access
folder = tmp_path / "shared"
_safetensors(folder / "style.safetensors", sidecar = _MARK)
register(str(folder))
monkeypatch.setattr(account_access, "managed_account", lambda: True)
monkeypatch.setattr(account_access, "model_visible", lambda reference, **_: False)
assert _local() == {}
with pytest.raises(FileNotFoundError):
dl.export_local_lora("style", tmp_path / "out")
with pytest.raises(FileNotFoundError):
dl.resolve_one("style", 1.0)
@pytest.mark.parametrize("scanner", ["routes", "inventory"])
def test_the_lmstudio_fallback_skips_marked_loras(tmp_path, scanner):
if scanner == "routes":
from routes.models import _scan_lmstudio_dir
else:
from hub.services.models.local_inventory import _scan_lmstudio_dir
for gguf in (tmp_path / "image-loras" / "style.gguf", tmp_path / "loose.gguf"):
gguf.parent.mkdir(parents = True, exist_ok = True)
gguf.write_bytes(b"GGUF" + b"\0" * 60)
gguf.with_suffix(".json").write_text(json.dumps(_MARK))
(tmp_path / "real.gguf").write_bytes(b"GGUF" + b"\0" * 60)
assert [row.display_name for row in _scan_lmstudio_dir(tmp_path)] == ["real"]
def test_stacked_loras_share_one_custom_folder_scan(catalog, tmp_path, monkeypatch):
for name in ("a", "b", "c"):
(catalog / f"{name}.safetensors").write_bytes(b"w")
calls = []
real = dl._scan_folder_roots
monkeypatch.setattr(dl, "_scan_folder_roots", lambda: calls.append(1) or real())
resolved = dl.resolve_specs([("a", 1.0), ("b", 0.5), ("c", 0.8)])
assert [r.path for r in resolved] == [str(catalog / f"{n}.safetensors") for n in "abc"]
assert len(calls) == 1
@pytest.mark.skipif(os.name == "nt", reason = "symlinks need a privilege on Windows")
def test_a_managed_account_cannot_reach_out_through_a_catalog_symlink(
catalog, tmp_path, monkeypatch
):
from hub.services.models import account_access
secret = tmp_path / "elsewhere" / "secret.safetensors"
_safetensors(secret, sidecar = _MARK)
(catalog / "link.safetensors").symlink_to(secret)
(catalog / "own.safetensors").write_bytes(b"w")
monkeypatch.setattr(account_access, "managed_account", lambda: True)
monkeypatch.setattr(
account_access,
"model_visible",
lambda reference, **_: str(catalog) in os.path.realpath(reference),
)
assert list(_local()) == ["own"]
with pytest.raises(FileNotFoundError):
dl.export_local_lora("link", tmp_path / "out")
@pytest.mark.skipif(os.name == "nt", reason = "POSIX byte filenames")
def test_a_non_utf8_filename_does_not_break_the_scan(catalog, tmp_path):
folder = tmp_path / "my-models"
folder.mkdir()
name = os.fsdecode(b"st\xffyle.safetensors")
try:
_safetensors(folder / name, sidecar = _MARK)
except OSError:
pytest.skip("this filesystem refuses non-UTF-8 names (APFS)")
register(folder)
assert [e.local_path for e in _local().values()] == [str(folder / name)]
def test_generation_rechecks_access_on_resolve(catalog, monkeypatch):
from hub.services.models import account_access
(catalog / "own.safetensors").write_bytes(b"w")
catalog_snapshot = dl._catalog_by_id()
monkeypatch.setattr(account_access, "managed_account", lambda: True)
monkeypatch.setattr(account_access, "model_visible", lambda reference, **_: False)
with pytest.raises(FileNotFoundError):
dl.resolve_one("own", 1.0, catalog = catalog_snapshot)
def test_a_marked_gguf_beside_a_model_is_not_a_variant(tmp_path):
from hub.services.models.common import _main_gguf_files
(tmp_path / "config.json").write_text("{}")
(tmp_path / "model-Q4_K_M.gguf").write_bytes(b"GGUF" + b"\0" * 60)
(tmp_path / "style.gguf").write_bytes(b"GGUF" + b"\0" * 60)
(tmp_path / "style.json").write_text(json.dumps(_MARK))
assert [p.name for p in _main_gguf_files(tmp_path)] == ["model-Q4_K_M.gguf"]
def test_a_config_with_only_a_marked_safetensors_is_not_a_model(tmp_path):
from hub.services.models.local_inventory import _scan_models_dir
folder = tmp_path / "loras-with-config"
folder.mkdir()
(folder / "config.json").write_text("{}")
_safetensors(folder / "style.safetensors", sidecar = _MARK)
rows = _scan_models_dir(tmp_path)
assert all(getattr(r, "model_format", None) != "safetensors" for r in rows)
def test_an_unreadable_entry_does_not_fail_the_catalog(catalog, tmp_path, monkeypatch):
from pathlib import Path
folder = tmp_path / "my-models"
_safetensors(folder / "good.safetensors", sidecar = _MARK)
_safetensors(folder / "locked.safetensors", sidecar = _MARK)
register(folder)
real_is_file = Path.is_file
def is_file(self):
if self.name == "locked.safetensors":
raise PermissionError(13, "Permission denied")
return real_is_file(self)
monkeypatch.setattr(Path, "is_file", is_file)
assert [e.display_name for e in _local().values()] == ["good"]
def test_an_unreadable_sibling_keeps_the_root_listed(catalog, tmp_path, monkeypatch):
from pathlib import Path
folder = tmp_path / "my-models"
_safetensors(folder / "good.safetensors", sidecar = _MARK)
(folder / "locked").mkdir()
register(folder)
real_is_dir = Path.is_dir
def is_dir(self):
if self.name == "locked":
raise PermissionError(13, "Permission denied")
return real_is_dir(self)
monkeypatch.setattr(Path, "is_dir", is_dir)
assert [e.display_name for e in _local().values()] == ["good"]
def test_an_export_of_a_listed_adapter_is_listed_once(catalog, tmp_path):
meta = {"family": "sdxl", "source": "studio-trained", "created_at": 1.5, **_MARK}
_safetensors(catalog / "mystyle.safetensors", sidecar = meta)
folder = tmp_path / "my-models"
out = dl.export_local_lora("mystyle", folder / "image-loras")
register(folder)
assert list(_local()) == ["mystyle"]
copy = next(e for e in dl._scan_local() if e.copy_of)
assert copy.copy_of == "mystyle" and copy.local_path == str(out)
# Still resolvable, so a recipe saved with the copy's id keeps working.
assert dl.resolve_one(copy.id, 1.0).path == str(out)
# Account checks see the copy's own path, not its bare id.
from types import SimpleNamespace
from hub.services.models.account_access import media_adapter_references
request = SimpleNamespace(loras = [SimpleNamespace(id = copy.id)], controlnet = None)
assert media_adapter_references(request) == [str(out)]
def test_same_sized_adapters_without_metadata_are_not_collapsed(catalog, tmp_path):
_safetensors(catalog / "a.safetensors")
folder = tmp_path / "my-models"
_safetensors(folder / "b.safetensors", sidecar = _MARK)
register(folder)
assert len(_local()) == 2
def test_a_different_training_run_with_the_same_name_is_not_a_copy(catalog, tmp_path):
_safetensors(
catalog / "style.safetensors", sidecar = {"source": "studio-trained", "created_at": 1.0}
)
folder = tmp_path / "my-models"
_safetensors(
folder / "style.safetensors",
sidecar = {"source": "studio-trained", "created_at": 2.0, **_MARK},
)
register(folder)
assert len(_local()) == 2
def test_a_same_layout_adapter_with_other_weights_is_not_a_copy(catalog, tmp_path):
meta = {"family": "sdxl", "source": "studio-trained", "created_at": 1.5}
(catalog / "style.safetensors").write_bytes(b"A" * 200_000)
(catalog / "style.json").write_text(json.dumps(meta))
folder = tmp_path / "my-models"
folder.mkdir()
(folder / "style.safetensors").write_bytes(b"A" * 100_000 + b"B" * 100_000)
(folder / "style.json").write_text(json.dumps({**meta, **_MARK}))
register(folder)
assert len(_local()) == 2
def test_hand_written_metadata_never_collapses(catalog, tmp_path):
(catalog / "style.safetensors").write_bytes(b"w" * 10)
(catalog / "style.json").write_text(json.dumps({"family": "sdxl"}))
folder = tmp_path / "my-models"
folder.mkdir()
(folder / "style.safetensors").write_bytes(b"w" * 10)
(folder / "style.json").write_text(json.dumps({"family": "sdxl", **_MARK}))
register(folder)
assert len(_local()) == 2