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
"""Studio must not offer a staged GGUF that Hermes itself will not serve."""
import sys
from pathlib import Path
import pytest
sys.path.insert(0, str(Path(__file__).resolve().parents[1]))
from hub.services.models.hermes import ( # noqa: E402
scan_hermes_dir,
staged_gguf_files,
staged_model_id,
)
from utils.paths.storage_roots import _hermes_root, hermes_model_dirs # noqa: E402
def _gguf(path: Path, size: int = 32) -> Path:
path.parent.mkdir(parents = True, exist_ok = True)
path.write_bytes(b"\x00" * size)
return path
def test_a_single_file_download_is_servable(tmp_path):
_gguf(tmp_path / "Qwen3-8B-UD-Q4_K_M.gguf")
assert [p.name for p in staged_gguf_files(tmp_path)] == ["Qwen3-8B-UD-Q4_K_M.gguf"]
rows = scan_hermes_dir(tmp_path)
assert len(rows) == 1
assert rows[0].source == "hermes"
assert rows[0].model_format == "gguf"
assert rows[0].display_name == "Qwen3-8B-UD-Q4_K_M"
assert rows[0].path == str(tmp_path / "Qwen3-8B-UD-Q4_K_M.gguf")
def test_a_complete_split_counts_once_by_its_first_part(tmp_path):
for index in range(1, 4):
_gguf(tmp_path / f"Big-Model-0000{index}-of-00003.gguf")
staged = staged_gguf_files(tmp_path)
assert [p.name for p in staged] == ["Big-Model-00001-of-00003.gguf"]
rows = scan_hermes_dir(tmp_path)
# llama.cpp opens the whole split set from part one.
assert len(rows) == 1
assert rows[0].display_name == "Big-Model"
assert rows[0].path.endswith("Big-Model-00001-of-00003.gguf")
def test_a_split_download_is_sized_as_the_whole_set(tmp_path):
for index, size in ((1, 32), (2, 48), (3, 64)):
_gguf(tmp_path / f"Big-Model-0000{index}-of-00003.gguf", size = size)
rows = scan_hermes_dir(tmp_path)
assert [row.size_bytes for row in rows] == [144]
def test_a_download_still_in_flight_is_not_offered(tmp_path):
_gguf(tmp_path / "Big-Model-00001-of-00003.gguf")
_gguf(tmp_path / "Big-Model-00002-of-00003.gguf")
assert staged_gguf_files(tmp_path) == []
assert scan_hermes_dir(tmp_path) == []
def test_a_continuation_part_is_never_a_row_of_its_own(tmp_path):
_gguf(tmp_path / "Big-Model-00002-of-00003.gguf")
_gguf(tmp_path / "Big-Model-00003-of-00003.gguf")
assert staged_gguf_files(tmp_path) == []
def test_companions_under_assets_are_not_models(tmp_path):
_gguf(tmp_path / "Vision-Model-Q4_K_M.gguf")
# Hermes parks mmproj and draft models here so its router skips them; do not recurse.
_gguf(tmp_path / "assets" / "mmproj-BF16.gguf")
_gguf(tmp_path / "assets" / "Draft-Model-Q4_K_M.gguf")
assert [p.name for p in staged_gguf_files(tmp_path)] == ["Vision-Model-Q4_K_M.gguf"]
def test_an_mmproj_left_at_the_top_level_is_still_not_a_model(tmp_path):
_gguf(tmp_path / "Vision-Model-Q4_K_M.gguf")
_gguf(tmp_path / "mmproj-Vision-Model-F16.gguf")
assert [p.name for p in staged_gguf_files(tmp_path)] == ["Vision-Model-Q4_K_M.gguf"]
def test_non_gguf_files_and_a_missing_dir_are_ignored(tmp_path):
(tmp_path / "presets.ini").write_text("[Qwen3-8B]\n", encoding = "utf-8")
(tmp_path / "state.json").write_text("{}", encoding = "utf-8")
assert staged_gguf_files(tmp_path) == []
assert scan_hermes_dir(tmp_path / "nope") == []
def test_the_row_is_reachable_through_the_scan_limit(tmp_path):
for name in ("A-Q4_K_M.gguf", "B-Q4_K_M.gguf", "C-Q4_K_M.gguf"):
_gguf(tmp_path / name)
assert len(scan_hermes_dir(tmp_path, limit = 2)) == 2
@pytest.mark.parametrize(
"name, expected",
[
("Qwen3-8B-UD-Q4_K_M", "Qwen3-8B-UD-Q4_K_M"),
("Big-Model-00001-of-00003", "Big-Model"),
("Big-Model-00012-of-00099", "Big-Model"),
],
)
def test_staged_model_id_strips_only_a_split_suffix(tmp_path, name, expected):
assert staged_model_id(tmp_path / f"{name}.gguf") == expected
class TestHermesRoot:
"""The models dir hangs off the ROOT, mirroring Hermes' own resolution."""
def test_no_env_uses_the_native_home(self, monkeypatch):
monkeypatch.delenv("HERMES_HOME", raising = False)
if sys.platform != "win32":
assert _hermes_root() == Path.home() / ".hermes"
def test_a_profile_under_the_native_home_still_means_the_root(self, monkeypatch):
if sys.platform == "win32":
pytest.skip("POSIX home layout")
monkeypatch.setenv("HERMES_HOME", str(Path.home() / ".hermes" / "profiles" / "coder"))
assert _hermes_root() == Path.home() / ".hermes"
def test_a_custom_deployment_root_is_used_as_is(self, monkeypatch, tmp_path):
monkeypatch.setenv("HERMES_HOME", str(tmp_path / "opt" / "data"))
assert _hermes_root() == tmp_path / "opt" / "data"
def test_a_profile_outside_the_native_home_resolves_to_its_root(self, monkeypatch, tmp_path):
monkeypatch.setenv("HERMES_HOME", str(tmp_path / "data" / "profiles" / "coder"))
assert _hermes_root() == tmp_path / "data"
def test_the_native_home_is_scanned_even_under_a_session_home(self, monkeypatch, tmp_path):
# `unsloth start hermes` uses a throwaway HERMES_HOME; downloads stay in the native home.
if sys.platform == "win32":
pytest.skip("POSIX home layout")
native_models = tmp_path / "home" / ".hermes" / "models"
native_models.mkdir(parents = True)
session_models = tmp_path / "session" / "models"
session_models.mkdir(parents = True)
monkeypatch.setattr(Path, "home", staticmethod(lambda: tmp_path / "home"))
monkeypatch.setenv("HERMES_HOME", str(tmp_path / "session"))
found = {str(p) for p in hermes_model_dirs()}
assert str(native_models) in found
assert str(session_models) in found
def test_only_directories_that_exist_are_returned(self, monkeypatch, tmp_path):
monkeypatch.setattr(Path, "home", staticmethod(lambda: tmp_path / "empty-home"))
monkeypatch.delenv("HERMES_HOME", raising = False)
assert hermes_model_dirs() == []