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.

Studio: detect models downloaded by Hermes (#10327)

Nilay29b87ecac112
diff --git a/studio/backend/core/inference/local_model_resolver.py b/studio/backend/core/inference/local_model_resolver.py
index adcb55bfa60..76d32a9a2b9 100644
--- a/studio/backend/core/inference/local_model_resolver.py
+++ b/studio/backend/core/inference/local_model_resolver.py
@@ -621,7 +621,7 @@ def _build_index() -> dict[str, _LocalGgufEntry]:
"""Map normalized id/model_id/display_name -> local model entry.
Scans the same roots Unsloth's model picker lists (./models, the active plus
- legacy/default HF caches, LM Studio dirs, and user scan folders) so a named
+ legacy/default HF caches, LM Studio and Hermes dirs, and user scan folders) so a named
local model is never missed and silently served as the loaded one. Ollama's
scanner is skipped: it creates symlinks as a side effect and this runs on the
request path.
@@ -691,6 +691,15 @@ def _build_index() -> dict[str, _LocalGgufEntry]:
found += _scan_lmstudio_dir(lm_dir)
except Exception as exc:
logger.debug("auto-switch: LM Studio scan failed: %s", exc)
+ # Read-only like the LM Studio scan, so it is safe on the request path. This is the path Hermes
+ # itself takes: it downloads the GGUF, then asks Unsloth for it by name.
+ try:
+ from hub.services.models.hermes import scan_hermes_dir
+ from utils.paths import hermes_model_dirs
+ for hermes_dir in hermes_model_dirs():
+ found += scan_hermes_dir(hermes_dir)
+ except Exception as exc:
+ logger.debug("auto-switch: Hermes scan failed: %s", exc)
try:
from storage.studio_db import list_scan_folders
diff --git a/studio/backend/hub/schemas/inventory.py b/studio/backend/hub/schemas/inventory.py
index c7e31077f00..ce60b0b70b5 100644
--- a/studio/backend/hub/schemas/inventory.py
+++ b/studio/backend/hub/schemas/inventory.py
@@ -142,7 +142,7 @@ class LocalModelInfo(BaseModel):
default_factory = LocalModelCapabilities,
description = "Declared capabilities for this inventory row",
)
- source: Literal["models_dir", "hf_cache", "lmstudio", "ollama", "custom"] = Field(
+ source: Literal["models_dir", "hf_cache", "lmstudio", "ollama", "hermes", "custom"] = Field(
...,
description = "Discovery source",
)
@@ -219,6 +219,10 @@ class LocalModelListResponse(BaseModel):
default_factory = list,
description = "Ollama model directories that were scanned",
)
+ hermes_dirs: List[str] = Field(
+ default_factory = list,
+ description = "Hermes model directories that were scanned",
+ )
models: List[LocalModelInfo] = Field(
default_factory = list,
description = "Discovered local/cached models",
diff --git a/studio/backend/hub/services/models/common.py b/studio/backend/hub/services/models/common.py
index fcd73fa3a94..726adacafaa 100644
--- a/studio/backend/hub/services/models/common.py
+++ b/studio/backend/hub/services/models/common.py
@@ -30,7 +30,7 @@ from utils.audio_tokens import detect_local_tts_audio_type
from utils.paths.path_utils import drop_appledouble_metadata, is_appledouble_metadata
ModelType = Literal["text", "vision", "audio", "embeddings"]
-LocalModelSource = Literal["models_dir", "hf_cache", "lmstudio", "ollama", "custom"]
+LocalModelSource = Literal["models_dir", "hf_cache", "lmstudio", "ollama", "hermes", "custom"]
def _safe_is_dir(path) -> bool:
diff --git a/studio/backend/hub/services/models/hermes.py b/studio/backend/hub/services/models/hermes.py
new file mode 100644
index 00000000000..fc7ad134bf9
--- /dev/null
+++ b/studio/backend/hub/services/models/hermes.py
@@ -0,0 +1,106 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+"""Hermes model inventory: the GGUFs Hermes Desktop's one-click download stages.
+
+Hermes keeps its managed runtime's weights as flat ``.gguf`` files directly in
+``<hermes root>/models``, with vision projectors and speculative-decode drafters
+tucked under a ``models/assets/`` subdirectory so its own router never lists them
+as servable. Which files count is decided by
+``hermes_cli.local_runtime.bootstrap.staged_models``; :func:`staged_gguf_files`
+mirrors that rule, because a file Hermes does not consider servable is one Studio
+must not offer to load either.
+"""
+
+from __future__ import annotations
+
+import re
+from pathlib import Path
+from typing import List, Optional
+
+from loggers import get_logger
+
+from hub.schemas.inventory import LocalModelInfo
+from hub.services.models.common import (
+ _classify_local_path,
+ _is_main_gguf_filename,
+ _sum_file_sizes,
+)
+
+logger = get_logger(__name__)
+
+# llama.cpp's split naming, e.g. Model-00001-of-00005.gguf.
+_SPLIT_PART = re.compile(r"-(\d{5})-of-(\d{5})\.gguf$")
+
+
+def staged_model_id(path: Path) -> str:
+ """The id Hermes knows a staged GGUF by: its stem, minus any split suffix."""
+ return re.sub(r"-\d{5}-of-\d{5}$", "", path.stem)
+
+
+def staged_gguf_files(hermes_dir: Path) -> List[Path]:
+ """Servable GGUFs staged in *hermes_dir*, a split counted once by its first part.
+
+ A flat glob, never a walk: ``assets/`` holds companions rather than models,
+ and Hermes excludes it by scanning only the top level. A split counts only
+ when EVERY part is on disk -- a download still in flight is not loadable, and
+ surfacing it would offer a model that fails at load. Continuation parts are
+ never rows of their own; llama.cpp opens the whole set from part one.
+ """
+ try:
+ files = sorted(p for p in hermes_dir.glob("*.gguf") if p.is_file())
+ except OSError as exc:
+ logger.warning("Error scanning Hermes directory %s: %s", hermes_dir, exc)
+ return []
+
+ names = {p.name for p in files}
+ staged: List[Path] = []
+ for path in files:
+ # mmproj/drafter companions belong under assets/, but a hand-dropped one
+ # at the top level is still not something to serve.
+ if not _is_main_gguf_filename(path.name):
+ continue
+ part = _SPLIT_PART.search(path.name)
+ if part is None:
+ staged.append(path)
+ continue
+ if part.group(1) != "00001":
+ continue
+ stem = path.name[: part.start()]
+ total = int(part.group(2))
+ if all(
+ f"{stem}-{index:05d}-of-{part.group(2)}.gguf" in names for index in range(2, total + 1)
+ ):
+ staged.append(path)
+ return staged
+
+
+def scan_hermes_dir(hermes_dir: Path, *, limit: Optional[int] = None) -> List[LocalModelInfo]:
+ """Scan a Hermes models directory for downloaded models."""
+ if not hermes_dir.exists() or not hermes_dir.is_dir():
+ return []
+
+ from utils.models.model_config import colocated_split_shards
+
+ rows: List[LocalModelInfo] = []
+ for path in staged_gguf_files(hermes_dir):
+ try:
+ updated_at = path.stat().st_mtime
+ except OSError:
+ updated_at = None
+ classified = _classify_local_path(
+ path,
+ "hermes",
+ display_name = staged_model_id(path),
+ updated_at = updated_at,
+ )
+ # The row points at part one and the classifier sizes the one file it was handed;
+ # the download is the whole set.
+ shards, _complete = colocated_split_shards(path)
+ if len(shards) > 1:
+ size_bytes = _sum_file_sizes(shards)
+ classified = [row.model_copy(update = {"size_bytes": size_bytes}) for row in classified]
+ rows += classified
+ if limit is not None and len(rows) >= limit:
+ break
+ return rows
diff --git a/studio/backend/hub/services/models/local_inventory.py b/studio/backend/hub/services/models/local_inventory.py
index 7e77d61b4a0..1a55dbeb41e 100644
--- a/studio/backend/hub/services/models/local_inventory.py
+++ b/studio/backend/hub/services/models/local_inventory.py
@@ -24,6 +24,7 @@ from hub.storage.scan_folders import (
)
from hub.utils import download_manifest, gguf, inventory_scan as hf_cache_scan
from hub.utils.paths import (
+ hermes_model_dirs,
hf_default_cache_dir,
legacy_hf_cache_dir,
lmstudio_model_dirs,
@@ -34,6 +35,7 @@ from hub.utils.paths import (
studio_root,
)
from hub.services.models import common as model_common
+from hub.services.models.hermes import scan_hermes_dir
from hub.services.models.ollama import scan_ollama_dir
from utils.hidden_models import is_hidden_model
from utils.paths.path_utils import is_appledouble_metadata
@@ -56,6 +58,7 @@ class _LocalInventorySources(NamedTuple):
hf_default: Path
lm_dirs: tuple[Path, ...]
ollama_dirs: tuple[Path, ...]
+ hermes_dirs: tuple[Path, ...]
known_hf_caches: tuple[Path, ...]
@@ -166,6 +169,7 @@ def _local_inventory_sources() -> _LocalInventorySources:
hf_default_cache_dir(),
tuple(lmstudio_model_dirs()),
tuple(ollama_model_dirs()),
+ tuple(hermes_model_dirs()),
tuple(known_hf_hub_caches()),
)
@@ -649,6 +653,7 @@ async def _collect_models_from_default_sources(
hf_default: Path,
lm_dirs: tuple[Path, ...],
ollama_dirs: tuple[Path, ...],
+ hermes_dirs: tuple[Path, ...],
known_hf_caches: tuple[Path, ...],
custom_folders: list[dict],
) -> List[LocalModelInfo]:
@@ -726,6 +731,10 @@ async def _collect_models_from_default_sources(
for ollama_dir in ollama_dirs:
local_models += await _scan_source("Ollama", scan_ollama_dir, ollama_dir)
+ for hermes_dir in hermes_dirs:
+ local_models += await _scan_source("Hermes", scan_hermes_dir, hermes_dir)
+
+ hermes_identities = {_inventory_physical_identity(str(d)) for d in hermes_dirs}
for folder_path, discovered, row_path in custom_sources:
try:
custom_models = await asyncio.to_thread(
@@ -735,6 +744,19 @@ async def _collect_models_from_default_sources(
variant_states = variant_states,
active_hub_cache = hf_cache_dir,
)
+ if _inventory_physical_identity(str(folder_path)) in hermes_identities:
+ # Registering ~/.hermes/models was how Hermes downloads were listed before this scan;
+ # the walk lists every download a second time under the same id. Anything else kept
+ # in that folder is still the user's custom row.
+ staged = {
+ _inventory_physical_identity(row.path)
+ for row in await asyncio.to_thread(scan_hermes_dir, folder_path)
+ }
+ custom_models = [
+ model
+ for model in custom_models
+ if _inventory_physical_identity(model.path) not in staged
+ ]
except Exception as e:
logger.warning("Skipping unreadable scan folder %s: %s", folder_path, e)
# Only an OS failure is something the user can fix, so only that is shown.
@@ -812,7 +834,7 @@ def _scan_custom_folder(
def _promote_to_custom_source(model: LocalModelInfo) -> LocalModelInfo:
- if model.source in {"hf_cache", "ollama"}:
+ if model.source in {"hf_cache", "ollama", "hermes"}:
return model
return model.model_copy(
update = {
@@ -916,7 +938,9 @@ async def _scan_local_models_response(
models_dir: str, custom_folders: list[dict], sources: _LocalInventorySources
) -> LocalModelListResponse:
"""List local model candidates from every supported on-device source."""
- hf_cache_dir, legacy_hf, hf_default, lm_dirs, ollama_dirs, known_hf_caches = sources
+ hf_cache_dir, legacy_hf, hf_default, lm_dirs, ollama_dirs, hermes_dirs, known_hf_caches = (
+ sources
+ )
allowed_roots: list[Path] = [Path("./models").resolve(), hf_cache_dir]
if _safe_is_dir(legacy_hf):
@@ -938,6 +962,7 @@ async def _scan_local_models_response(
hf_default,
lm_dirs,
ollama_dirs,
+ hermes_dirs,
known_hf_caches,
custom_folders,
)
@@ -947,6 +972,7 @@ async def _scan_local_models_response(
hf_cache_dir = str(hf_cache_dir),
lmstudio_dirs = [str(d) for d in lm_dirs],
ollama_dirs = [str(d) for d in ollama_dirs],
+ hermes_dirs = [str(d) for d in hermes_dirs],
models = models,
)
except Exception as e:
diff --git a/studio/backend/hub/tests/test_model_services.py b/studio/backend/hub/tests/test_model_services.py
index 574c8eb08d8..c5c16d342d1 100644
--- a/studio/backend/hub/tests/test_model_services.py
+++ b/studio/backend/hub/tests/test_model_services.py
@@ -1126,6 +1126,7 @@ def test_local_inventory_indexes_registered_hf_state_once(monkeypatch, tmp_path)
(),
(),
(),
+ (),
[{"path": str(custom)}],
)
)
@@ -1133,6 +1134,42 @@ def test_local_inventory_indexes_registered_hf_state_once(monkeypatch, tmp_path)
assert propagated == [indexed, indexed]
+def test_local_inventory_lists_a_hermes_dir_registered_as_a_scan_folder_once(monkeypatch, tmp_path):
+ # Adding ~/.hermes/models as a custom folder was the way to see Hermes downloads before
+ # Studio scanned it; the Hermes scan and a generic walk of the same folder must not each
+ # list every download under the same id.
+ hermes = tmp_path / ".hermes" / "models"
+ hermes.mkdir(parents = True)
+ weight = hermes / "Qwen3.8-27B-UD-Q4_K_M.gguf"
+ weight.write_bytes(b"\x00" * 32)
+ # Something else the user keeps in that folder stays a custom row.
+ extra = hermes / "extra" / "Other-Q4_K_M.gguf"
+ extra.parent.mkdir()
+ extra.write_bytes(b"\x00" * 32)
+ monkeypatch.setattr(local_inventory, "note_scan_folder_scanned", lambda *_a, **_k: None)
+ monkeypatch.setattr(local_inventory, "record_scan_failure", lambda *_a, **_k: None)
+
+ rows = asyncio.run(
+ local_inventory._collect_models_from_default_sources(
+ tmp_path / "models",
+ tmp_path / "hf",
+ tmp_path / "legacy",
+ tmp_path / "default",
+ (),
+ (),
+ (hermes,),
+ (),
+ [{"path": str(hermes)}],
+ )
+ )
+ rows = local_inventory._filter_and_dedupe_local_models(rows)
+
+ assert sorted((row.source, row.path) for row in rows) == [
+ ("custom", str(extra.parent)),
+ ("hermes", str(weight)),
+ ]
+
+
def test_list_local_gguf_variants_skips_big_endian_sibling(tmp_path):
(tmp_path / "model-Q4_K_M-be.gguf").write_bytes(b"x" * 100)
(tmp_path / "model-Q4_K_M.gguf").write_bytes(b"y" * 10)
diff --git a/studio/backend/hub/utils/paths.py b/studio/backend/hub/utils/paths.py
index dd887575092..018787afb9c 100644
--- a/studio/backend/hub/utils/paths.py
+++ b/studio/backend/hub/utils/paths.py
@@ -21,6 +21,7 @@ from utils.paths.path_utils import wsl_automount_root
# One policy, defined in utils.paths.storage_roots: the copy that used to live here drifted, and a
# BOM'd settings.json was honoured by one side and dropped by the other (#9748).
from utils.paths.storage_roots import (
+ hermes_model_dirs,
lmstudio_model_dirs,
ollama_model_dirs,
well_known_model_dirs,
@@ -29,7 +30,7 @@ from utils.paths.storage_roots import (
logger = get_logger(__name__)
# Re-export shim: marks them used so the import-hoist safety net does not flag them.
-_REEXPORTED = (lmstudio_model_dirs, ollama_model_dirs, well_known_model_dirs)
+_REEXPORTED = (hermes_model_dirs, lmstudio_model_dirs, ollama_model_dirs, well_known_model_dirs)
def _infer_studio_home_from_venv() -> Optional[Path]:
diff --git a/studio/backend/models/models.py b/studio/backend/models/models.py
index cd9bb7f0c24..e0c9a81b2a1 100644
--- a/studio/backend/models/models.py
+++ b/studio/backend/models/models.py
@@ -221,7 +221,7 @@ class LocalModelInfo(BaseModel):
id: str = Field(..., description = "Identifier to use for loading/training")
display_name: str = Field(..., description = "Display label")
path: str = Field(..., description = "Local path where model data was discovered")
- source: Literal["models_dir", "hf_cache", "lmstudio", "ollama", "custom"] = Field(
+ source: Literal["models_dir", "hf_cache", "lmstudio", "ollama", "hermes", "custom"] = Field(
...,
description = "Discovery source",
)
@@ -270,6 +270,10 @@ class LocalModelListResponse(BaseModel):
default_factory = list,
description = "LM Studio model directories that were scanned",
)
+ hermes_dirs: List[str] = Field(
+ default_factory = list,
+ description = "Hermes model directories that were scanned",
+ )
models: List[LocalModelInfo] = Field(
default_factory = list,
description = "Discovered local/cached models",
diff --git a/studio/backend/routes/inference.py b/studio/backend/routes/inference.py
index 60e5e81167e..0020e915919 100644
--- a/studio/backend/routes/inference.py
+++ b/studio/backend/routes/inference.py
@@ -6848,6 +6848,15 @@ def _drafter_for_path(
return detected
+def _native_mmproj_accept(candidate: str, gguf_path: str) -> bool:
+ """Apply native projector authorization before discovery reads its header."""
+ try:
+ _validate_native_gguf_companion(candidate, gguf_path, "vision companion")
+ except HTTPException:
+ return False
+ return True
+
+
def _native_drafter_accept(candidate: str, gguf_path: str, kind: str, search_root: str) -> bool:
"""The native lease rule, in the shape ModelConfig.from_identifier takes.
@@ -14318,6 +14327,7 @@ async def _load_model_impl(
# pass that touches a drafter candidate, so the boundary has
# to travel with it rather than being applied afterwards.
drafter_accept = _native_drafter_accept if native_grant_backed else None,
+ mmproj_accept = _native_mmproj_accept if native_grant_backed else None,
gguf_companion_roots = request._gguf_companion_roots or None,
)
@@ -15318,6 +15328,7 @@ async def validate_model(
# pass that touches a drafter candidate, so the boundary has
# to travel with it rather than being applied afterwards.
drafter_accept = _native_drafter_accept if native_grant_backed else None,
+ mmproj_accept = _native_mmproj_accept if native_grant_backed else None,
)
config = await asyncio.to_thread(_resolve_config)
@@ -16161,6 +16172,7 @@ def _cached_estimate_config(
hf_token = hf_token,
gguf_variant = gguf_variant,
drafter_accept = _native_drafter_accept if native_grant_backed else None,
+ mmproj_accept = _native_mmproj_accept if native_grant_backed else None,
)
# Offline FIRST, not only when the Hub is unreachable. The gate above established
diff --git a/studio/backend/routes/models.py b/studio/backend/routes/models.py
index aaa84d37458..4c6f4725e3c 100644
--- a/studio/backend/routes/models.py
+++ b/studio/backend/routes/models.py
@@ -1022,16 +1022,33 @@ def _scan_ollama_dir(ollama_dir: Path, limit: Optional[int] = None) -> List[Loca
return found
+def _scan_hermes_dir(hermes_dir: Path) -> List[LocalModelInfo]:
+ """Hermes rows in this module's row schema; the scanner builds the Hub inventory's."""
+ from hub.services.models.hermes import scan_hermes_dir
+
+ fields = LocalModelInfo.model_fields
+ return [
+ LocalModelInfo.model_validate({k: v for k, v in row.model_dump().items() if k in fields})
+ for row in scan_hermes_dir(hermes_dir)
+ ]
+
+
class _CompatLocalInventorySources(NamedTuple):
hf_cache_dir: Path
legacy_hf: Path
hf_default: Path
lm_dirs: tuple[Path, ...]
known_hf_caches: tuple[Path, ...]
+ hermes_dirs: tuple[Path, ...] = ()
def _compat_local_inventory_sources() -> _CompatLocalInventorySources:
- from utils.paths import hf_default_cache_dir, legacy_hf_cache_dir, lmstudio_model_dirs
+ from utils.paths import (
+ hermes_model_dirs,
+ hf_default_cache_dir,
+ legacy_hf_cache_dir,
+ lmstudio_model_dirs,
+ )
from utils.hf_cache_settings import known_hf_hub_caches
return _CompatLocalInventorySources(
_resolve_hf_cache_dir(),
@@ -1039,6 +1056,7 @@ def _compat_local_inventory_sources() -> _CompatLocalInventorySources:
hf_default_cache_dir(),
tuple(lmstudio_model_dirs()),
tuple(known_hf_hub_caches()),
+ tuple(hermes_model_dirs()),
)
@@ -1048,8 +1066,8 @@ def collect_local_models(
custom_folders: Optional[list[dict]] = None,
sources: Optional[_CompatLocalInventorySources] = None,
) -> List[LocalModelInfo]:
- """Scan ``models_root``, the HF caches, LM Studio dirs, and user scan folders,
- returning a deduplicated, hidden-filtered list of discovered local models.
+ """Scan ``models_root``, the HF caches, LM Studio and Hermes dirs, and user scan
+ folders, returning a deduplicated, hidden-filtered list of discovered local models.
Shared by ``GET /models/local`` (the model picker) and the OpenAI-compatible
catalog (``GET /v1/models``) so the UI and the API never drift. ``models_root``
@@ -1122,8 +1140,15 @@ def collect_local_models(
for lm_dir in lm_dirs:
local_models += _scan_lmstudio_dir(lm_dir)
+ for hermes_dir in sources.hermes_dirs:
+ try:
+ local_models += _scan_hermes_dir(hermes_dir)
+ except Exception as e:
+ logger.warning("Error scanning Hermes directory %s: %s", hermes_dir, e)
+
# Scan user-added custom folders (per-folder cap).
_MAX_MODELS_PER_FOLDER = 200
+ hermes_identities = {_compat_inventory_path_identity(str(d)) for d in sources.hermes_dirs}
for folder in custom_folders:
folder_path = Path(folder["path"])
try:
@@ -1166,6 +1191,18 @@ def collect_local_models(
):
custom_models.append(model)
custom_models = gguf_utils.dedupe_custom_gguf_rows(custom_models)
+ if _compat_inventory_path_identity(str(folder_path)) in hermes_identities:
+ # Registering ~/.hermes/models was how Hermes downloads were listed before this
+ # scan; the walk lists every download a second time under the same id. Anything
+ # else kept in that folder is still the user's custom row.
+ staged = {
+ _compat_inventory_path_identity(m.path) for m in _scan_hermes_dir(folder_path)
+ }
+ custom_models = [
+ m
+ for m in custom_models
+ if _compat_inventory_path_identity(m.path) not in staged
+ ]
if len(custom_models) < _MAX_MODELS_PER_FOLDER:
custom_models += _scan_ollama_dir(
folder_path,
@@ -1182,7 +1219,9 @@ def collect_local_models(
# custom entries. Mirrors _promote_to_custom_source() in
# hub/services/models/local_inventory.py.
local_models += [
- m if m.source in ("hf_cache", "ollama") else m.model_copy(update = {"source": "custom"})
+ m
+ if m.source in ("hf_cache", "ollama", "hermes")
+ else m.model_copy(update = {"source": "custom"})
for m in custom_models
]
@@ -1362,7 +1401,7 @@ async def list_local_models(
),
current_subject: str = Depends(get_current_subject),
):
- """List local model candidates from the models dir, HF caches, and LM Studio dirs."""
+ """List local model candidates from the models dir, HF caches, LM Studio and Hermes dirs."""
# Resolve all scan directories up front.
sources = _compat_local_inventory_sources()
hf_cache_dir = sources.hf_cache_dir
@@ -1402,6 +1441,7 @@ async def list_local_models(
models_dir = str(models_root),
hf_cache_dir = str(hf_cache_dir),
lmstudio_dirs = [str(d) for d in lm_dirs],
+ hermes_dirs = [str(d) for d in sources.hermes_dirs],
models = models,
)
except Exception as e:
diff --git a/studio/backend/tests/test_detect_mmproj_file.py b/studio/backend/tests/test_detect_mmproj_file.py
index 2414218b294..b3e2d0ca09a 100644
--- a/studio/backend/tests/test_detect_mmproj_file.py
+++ b/studio/backend/tests/test_detect_mmproj_file.py
@@ -378,3 +378,36 @@ def test_trusted_companion_snapshot_finds_nested_projector(tmp_path: Path):
assert detect_mmproj_file(
str(weight), search_root = str(sibling), allow_disjoint_search_root = True
) == str(projector.resolve())
+
+
+def test_finds_the_projector_hermes_stages_under_assets(tmp_path: Path):
+ """Hermes keeps a download's mmproj in models/assets/ so its router never lists it as a
+ model; the weight sits one level up. A sibling-only walk loads Qwen3.8-27B text-only."""
+ model = _touch(tmp_path / "Qwen3.8-27B-UD-Q4_K_M.gguf")
+ mmproj = _touch(tmp_path / "assets" / "mmproj-Qwen3.8-27B-BF16.gguf")
+ assert detect_mmproj_file(str(model)) == str(mmproj.resolve())
+
+
+def test_assets_holding_several_projectors_still_pairs_by_family(tmp_path: Path):
+ """One assets/ dir serves every Hermes download, so it fills with projectors for
+ different families. The family gate must keep picking the right one."""
+ model = _touch(tmp_path / "gemma-4-26B-A4B-it-UD-Q4_K_M.gguf")
+ _touch(tmp_path / "assets" / "mmproj-Qwen3.8-27B-BF16.gguf")
+ gemma = _touch(tmp_path / "assets" / "mmproj-gemma-4-26B-A4B-it-BF16.gguf")
+ assert detect_mmproj_file(str(model)) == str(gemma.resolve())
+
+
+def test_assets_holding_two_same_family_projectors_pairs_by_name(tmp_path: Path):
+ """Two Qwen downloads share one assets/ dir. Without header metadata both projectors
+ survive the family gate, so the name tie-break has to read past the mmproj- marker;
+ comparing raw stems ties at zero and the shorter name (the wrong model) won."""
+ model = _touch(tmp_path / "Qwen3.6-35B-A3B-UD-Q4_K_M.gguf")
+ _touch(tmp_path / "assets" / "mmproj-Qwen3.8-27B-BF16.gguf")
+ mine = _touch(tmp_path / "assets" / "mmproj-Qwen3.6-35B-A3B-BF16.gguf")
+ assert detect_mmproj_file(str(model)) == str(mine.resolve())
+
+
+def test_a_draft_model_under_assets_is_not_mistaken_for_a_projector(tmp_path: Path):
+ model = _touch(tmp_path / "Qwen3.8-27B-UD-Q4_K_M.gguf")
+ _touch(tmp_path / "assets" / "Qwen3.8-0.8B-draft-Q4_K_M.gguf")
+ assert detect_mmproj_file(str(model)) is None
diff --git a/studio/backend/tests/test_hermes_model_scan.py b/studio/backend/tests/test_hermes_model_scan.py
new file mode 100644
index 00000000000..bd4517992ca
--- /dev/null
+++ b/studio/backend/tests/test_hermes_model_scan.py
@@ -0,0 +1,171 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+"""Hermes Desktop stages its one-click downloads as flat GGUFs in <root>/models.
+
+The staging rules mirror hermes_cli.local_runtime.bootstrap.staged_models: a file
+Hermes will not serve is one Studio must not offer to load.
+"""
+
+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 set from part one, so the row points at it and
+ # carries the id Hermes knows the model by, not the part's own stem.
+ 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):
+ # Parts 1 and 2 of 3 on disk: loading this fails, so it must not be listed.
+ _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):
+ # Only the tail parts, e.g. after the first was deleted: nothing is servable.
+ _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 vision projectors and spec-decode drafters here precisely so its
+ # own router never lists them; a recursive scan would surface both as models.
+ _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
+
+
+ "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"))
+ # A 20 GB GGUF is a machine asset every profile shares, so it never
+ # follows the active profile.
+ 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` points HERMES_HOME at a throwaway session dir; the
+ # user's real downloads stay under the native home and must still be found.
+ 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() == []
diff --git a/studio/backend/tests/test_legacy_ollama_source.py b/studio/backend/tests/test_legacy_ollama_source.py
index 5cfcbb1c0b6..a64c78bd9dd 100644
--- a/studio/backend/tests/test_legacy_ollama_source.py
+++ b/studio/backend/tests/test_legacy_ollama_source.py
@@ -66,7 +66,7 @@ def test_legacy_scanner_tags_rows_ollama(tmp_path):
assert found[0].model_id == "ollama/llama3:latest"
[email protected]("source", ["hf_cache", "ollama"])
[email protected]("source", ["hf_cache", "ollama", "hermes"])
def test_custom_folder_merge_keeps_real_sources(source):
# The merge step mirrors _promote_to_custom_source() in
# hub/services/models/local_inventory.py: only unattributed rows become
@@ -74,7 +74,7 @@ def test_custom_folder_merge_keeps_real_sources(source):
src = (Path(__file__).resolve().parent.parent / "routes" / "models.py").read_text(
encoding = "utf-8"
)
- assert 'm if m.source in ("hf_cache", "ollama") else' in src
+ assert 'if m.source in ("hf_cache", "ollama", "hermes")' in src
row = LocalModelInfo(
id = "/x",
display_name = "x",
@@ -82,6 +82,8 @@ def test_custom_folder_merge_keeps_real_sources(source):
source = source,
)
kept = (
- row if row.source in ("hf_cache", "ollama") else row.model_copy(update = {"source": "custom"})
+ row
+ if row.source in ("hf_cache", "ollama", "hermes")
+ else row.model_copy(update = {"source": "custom"})
)
assert kept.source == source
diff --git a/studio/backend/tests/test_local_model_format.py b/studio/backend/tests/test_local_model_format.py
index c57b2b0a23a..5cdb5508e3e 100644
--- a/studio/backend/tests/test_local_model_format.py
+++ b/studio/backend/tests/test_local_model_format.py
@@ -176,6 +176,74 @@ def test_compat_inventory_does_not_cross_dedupe_default_sources(tmp_path):
}
+def test_compat_inventory_lists_hermes_downloads(tmp_path):
+ # /api/models/local and /v1/models are served by this scan, not the hub inventory, so
+ # the recipe picker, the chat auto-load and the OpenAI catalog see only what it returns.
+ models_root = tmp_path / "models"
+ models_root.mkdir()
+ hermes = tmp_path / ".hermes" / "models"
+ weight = _touch(hermes / "Qwen3.8-27B-UD-Q4_K_M.gguf")
+ _touch(hermes / "assets" / "mmproj-Qwen3.8-27B-BF16.gguf")
+ empty = _empty_compat_sources(tmp_path)
+ sources = empty._replace(hermes_dirs = (hermes,))
+
+ rows = models_route.collect_local_models(
+ models_root,
+ custom_folders = [],
+ sources = sources,
+ )
+
+ assert {(row.source, Path(row.path)) for row in rows} == {("hermes", weight)}
+ assert rows[0].display_name == "Qwen3.8-27B-UD-Q4_K_M"
+
+
+def test_compat_inventory_lists_a_hermes_dir_registered_as_a_scan_folder_once(tmp_path):
+ models_root = tmp_path / "models"
+ models_root.mkdir()
+ hermes = tmp_path / ".hermes" / "models"
+ weight = _touch(hermes / "Qwen3.8-27B-UD-Q4_K_M.gguf")
+ # Something else the user keeps in that folder stays a custom row.
+ extra = _touch(hermes / "extra" / "Other-Q4_K_M.gguf")
+ sources = _empty_compat_sources(tmp_path)._replace(hermes_dirs = (hermes,))
+
+ rows = models_route.collect_local_models(
+ models_root,
+ custom_folders = [{"path": str(hermes)}],
+ sources = sources,
+ )
+
+ assert sorted((row.source, Path(row.path)) for row in rows) == [
+ ("custom", extra.parent),
+ ("hermes", weight),
+ ]
+
+
+def test_local_route_returns_hermes_downloads(monkeypatch, tmp_path):
+ # The scanner builds the Hub inventory's row class; this route answers with its own, so a
+ # Hermes row must cross that boundary or the route is a 500 for anyone with a download.
+ models_dir = tmp_path / "models"
+ models_dir.mkdir()
+ hermes = tmp_path / ".hermes" / "models"
+ weight = _touch(hermes / "Qwen3.8-27B-UD-Q4_K_M.gguf")
+ sources = models_route._CompatLocalInventorySources(
+ hf_cache_dir = models_dir,
+ legacy_hf = tmp_path / "legacy",
+ hf_default = tmp_path / "default",
+ lm_dirs = (),
+ known_hf_caches = (),
+ hermes_dirs = (hermes,),
+ )
+ monkeypatch.setattr(models_route, "_compat_local_inventory_sources", lambda: sources)
+ monkeypatch.setattr("storage.studio_db.list_scan_folders", lambda: [])
+
+ response = asyncio.run(
+ models_route.list_local_models(models_dir = str(models_dir), current_subject = "test")
+ )
+
+ assert response.hermes_dirs == [str(hermes)]
+ assert [(m.source, Path(m.path)) for m in response.models] == [("hermes", weight)]
+
+
def test_compat_inventory_preserves_ollama_tags_sharing_a_blob(tmp_path):
root = tmp_path / "ollama"
digest = "sha256-model"
diff --git a/studio/backend/tests/test_mtp_drafter_companion.py b/studio/backend/tests/test_mtp_drafter_companion.py
index edcbbd5d7f7..60087855f24 100644
--- a/studio/backend/tests/test_mtp_drafter_companion.py
+++ b/studio/backend/tests/test_mtp_drafter_companion.py
@@ -232,6 +232,31 @@ def test_detect_dspark_file_prefers_matching_q8_sidecar(tmp_path):
assert detect_dspark_file(str(weight)) == str(q8.resolve())
+def test_detect_dspark_file_finds_the_sidecar_hermes_stages_under_assets(tmp_path):
+ # Hermes' catalog ships DeepSeek V4 Flash with its DSpark drafter under models/assets/,
+ # the folder its router never lists; the weight sits one level up as a flat split.
+ weight = tmp_path / "DeepSeek-V4-Flash-0731-UD-Q4_K_XL-00001-of-00002.gguf"
+ weight.write_bytes(b"target")
+ (tmp_path / "DeepSeek-V4-Flash-0731-UD-Q4_K_XL-00002-of-00002.gguf").write_bytes(b"target")
+ assets = tmp_path / "assets"
+ assets.mkdir()
+ sidecar = assets / "dspark-DeepSeek-V4-Flash-0731-Q8_0.gguf"
+ sidecar.write_bytes(b"q8")
+ (assets / "mmproj-Qwen3.8-27B-BF16.gguf").write_bytes(b"projector")
+
+ assert detect_dspark_file(str(weight)) == str(sidecar.resolve())
+
+
+def test_detect_mtp_file_finds_the_sidecar_hermes_stages_under_assets(tmp_path):
+ (tmp_path / "gemma-4-12B-it-qat-Q4_0.gguf").write_bytes(b"x")
+ assets = tmp_path / "assets"
+ assets.mkdir()
+ (assets / "mtp-gemma-4-12B-it.gguf").write_bytes(b"x")
+
+ found = detect_mtp_file(str(tmp_path / "gemma-4-12B-it-qat-Q4_0.gguf"))
+ assert found == str((assets / "mtp-gemma-4-12B-it.gguf").resolve())
+
+
def test_detect_dspark_file_accepts_the_suffix_naming_scheme(tmp_path):
"""``<model>-dspark.gguf`` pairs too, the same second scheme MTP accepts."""
weight = tmp_path / "model-Q4_K_M.gguf"
@@ -2219,6 +2244,16 @@ def _write_gguf(path: Path, architecture: str) -> Path:
return path
+def test_detect_dflash_file_leaves_a_shared_assets_pool_alone(tmp_path):
+ # The published sidecar names no family, so one under a Hermes assets/ pool could be any
+ # download's; DSpark and MTP sidecars name their weight, DFlash keeps the root-only rule.
+ weight = _write_gguf(tmp_path / "Muse-Glimmer-30B-UD-Q4_K_XL.gguf", "muse-glimmer")
+ (tmp_path / "assets").mkdir()
+ _write_gguf(tmp_path / "assets" / "dflash-kquant.gguf", "dflash")
+
+ assert detect_dflash_file(str(weight)) is None
+
+
def test_detect_dflash_file_finds_the_unpaired_published_sidecar(tmp_path):
"""The published sidecar is dflash-kquant.gguf, which names no model family,
so the filename pairing DSpark uses would reject the one file this exists to
diff --git a/studio/backend/tests/test_native_gguf_companion.py b/studio/backend/tests/test_native_gguf_companion.py
index 31e88c45087..0cdbc41cf9c 100644
--- a/studio/backend/tests/test_native_gguf_companion.py
+++ b/studio/backend/tests/test_native_gguf_companion.py
@@ -22,6 +22,7 @@ from routes.inference import _validate_native_mtp_drafter
from routes.inference import _loaded_is_local_model
from routes.inference import _mtp_draft_for_path
from routes.inference import _native_gguf_companion_usable
+from routes.inference import _native_mmproj_accept
from utils.models.model_config import (
_local_gguf_companion_search_root,
detect_dflash_file,
@@ -83,6 +84,91 @@ def test_native_companion_allows_model_directory(tmp_path):
_validate_native_gguf_companion(str(companion), str(weight), "vision companion")
[email protected]("native", [False, True])
[email protected]("root_projector", [False, True])
+def test_projector_discovery_admits_before_reading(tmp_path, monkeypatch, native, root_projector):
+ from utils.models import model_config as mc
+
+ weight = tmp_path / "Qwen3.8-27B-Q4_K_M.gguf"
+ weight.write_bytes(b"\0" * 32)
+ assets = tmp_path / "assets"
+ assets.mkdir()
+ outside = assets / "mmproj-Qwen3.8-27B-BF16.gguf"
+ outside.write_bytes(b"\0" * 32)
+ sibling = tmp_path / "mmproj-F16.gguf"
+ if root_projector:
+ sibling.write_bytes(b"\0" * 32)
+
+ reads = []
+ original = mc.read_gguf_general_metadata
+
+ def read(path):
+ reads.append(Path(path).resolve())
+ if native:
+ assert Path(path).resolve() != outside.resolve()
+ return original(path)
+
+ monkeypatch.setattr(mc, "read_gguf_general_metadata", read)
+ config = mc.ModelConfig.from_identifier(
+ str(weight),
+ mmproj_accept = _native_mmproj_accept if native else None,
+ )
+ expected = sibling if native and root_projector else None if native else outside
+ assert config.gguf_mmproj_file == (str(expected.resolve()) if expected else None)
+ assert config.is_vision is (expected is not None)
+ if native:
+ assert outside.resolve() not in reads
+ intent = _resolve_gguf_load_intent(
+ config,
+ LoadRequest(model_path = str(weight)),
+ native_grant_backed = True,
+ chat_template_override = None,
+ extra_args = None,
+ placement = SimpleNamespace(resolved_gpu_ids = None, gpu_ids_are_vulkan_ordinals = False),
+ n_parallel = 1,
+ )
+ assert intent.mmproj_path == config.gguf_mmproj_file
+ else:
+ assert outside.resolve() in reads
+
+
[email protected]("directory_link", [False, True])
+def test_native_projector_symlink_rejected_before_header_read(
+ tmp_path, monkeypatch, directory_link
+):
+ from utils.models import model_config as mc
+
+ model_dir = tmp_path / "model"
+ model_dir.mkdir()
+ weight = model_dir / "model.gguf"
+ weight.write_bytes(b"\0" * 32)
+ outside = tmp_path / "outside"
+ outside.mkdir()
+ projector = outside / "mmproj-F16.gguf"
+ projector.write_bytes(b"\0" * 32)
+ try:
+ if directory_link:
+ (model_dir / "assets").symlink_to(outside, target_is_directory = True)
+ else:
+ (model_dir / projector.name).symlink_to(projector)
+ except OSError as exc:
+ pytest.skip(f"symlinks unavailable: {exc}")
+
+ original = mc.read_gguf_general_metadata
+
+ def read(path):
+ assert Path(path).resolve() != projector.resolve()
+ return original(path)
+
+ monkeypatch.setattr(mc, "read_gguf_general_metadata", read)
+ assert (
+ mc.detect_mmproj_file(
+ str(weight), accept = lambda candidate: _native_mmproj_accept(candidate, str(weight))
+ )
+ is None
+ )
+
+
@pytest.mark.parametrize("folder", ["MTP", "mtp", "MtP"])
def test_native_mtp_companion_allows_mtp_directory(tmp_path, folder):
weight, companion = _write_pair(tmp_path, folder)
diff --git a/studio/backend/tests/test_openai_auto_switch.py b/studio/backend/tests/test_openai_auto_switch.py
index 909f2d249ab..13b0a4b5f99 100644
--- a/studio/backend/tests/test_openai_auto_switch.py
+++ b/studio/backend/tests/test_openai_auto_switch.py
@@ -1846,6 +1846,51 @@ def test_build_index_covers_legacy_default_lmstudio_and_custom_roots(monkeypatch
assert str((tmp_path / "lmstudio").resolve()) in lm
+def test_build_index_covers_hermes_downloads(monkeypatch, tmp_path):
+ # Hermes downloads a GGUF and then asks Unsloth for it BY NAME, so the name must resolve
+ # to the file Hermes itself staged or the request is served by whatever is loaded.
+ from pathlib import Path
+ import routes.models as models_route
+ from hub.services.models import hermes as hermes_scan
+ from utils import paths as upaths
+ from utils import hf_cache_settings
+ import storage.studio_db as studio_db
+
+ monkeypatch.setattr(models_route, "_scan_models_dir", lambda d, limit = None: [])
+ monkeypatch.setattr(models_route, "_scan_hf_cache", lambda d, **_: [])
+ monkeypatch.setattr(models_route, "_scan_lmstudio_dir", lambda d: [])
+ monkeypatch.setattr(models_route, "_resolve_hf_cache_dir", lambda: tmp_path / "active")
+ monkeypatch.setattr(models_route, "_is_hidden_model", lambda *a, **k: False)
+ monkeypatch.setattr(hf_cache_settings, "known_hf_hub_caches", lambda: [])
+ monkeypatch.setattr(upaths, "legacy_hf_cache_dir", lambda: tmp_path / "legacy")
+ monkeypatch.setattr(upaths, "hf_default_cache_dir", lambda: tmp_path / "default")
+ monkeypatch.setattr(upaths, "lmstudio_model_dirs", lambda: [])
+ monkeypatch.setattr(studio_db, "list_scan_folders", lambda: [])
+
+ hermes_models = tmp_path / ".hermes" / "models"
+ hermes_models.mkdir(parents = True)
+ weight = hermes_models / "Qwen3.8-27B-UD-Q4_K_M.gguf"
+ weight.write_bytes(b"\x00" * 32)
+ monkeypatch.setattr(upaths, "hermes_model_dirs", lambda: [hermes_models])
+
+ scanned = []
+ real_scan = hermes_scan.scan_hermes_dir
+ monkeypatch.setattr(
+ hermes_scan,
+ "scan_hermes_dir",
+ lambda d, **kw: scanned.append(str(Path(d).resolve())) or real_scan(d, **kw),
+ )
+
+ index = resolver._build_index()
+
+ assert scanned == [str(hermes_models.resolve())]
+ # The id Hermes configures as model.default is the stem; it must land on the staged file.
+ entry = index.get("qwen3.8-27b-ud-q4_k_m")
+ assert entry is not None
+ assert entry.is_gguf
+ assert Path(entry.load_path).resolve() == weight.resolve()
+
+
# ── gemini round: list-body 400, non-POST not tracked ──
diff --git a/studio/backend/tests/test_scan_folder_health.py b/studio/backend/tests/test_scan_folder_health.py
index 5c0091918a5..da36ff4e73a 100644
--- a/studio/backend/tests/test_scan_folder_health.py
+++ b/studio/backend/tests/test_scan_folder_health.py
@@ -428,6 +428,7 @@ def test_the_hub_scan_probes_off_the_event_loop(tmp_path: Path):
[],
[],
[],
+ [],
list(rows),
)
)
@@ -464,6 +465,7 @@ def test_the_hub_scan_records_a_folder_it_cannot_read(tmp_path: Path):
[],
[],
[],
+ [],
list(rows),
)
)
diff --git a/studio/backend/utils/models/drafters/dflash.py b/studio/backend/utils/models/drafters/dflash.py
index f372a1197ba..c30ed465963 100644
--- a/studio/backend/utils/models/drafters/dflash.py
+++ b/studio/backend/utils/models/drafters/dflash.py
@@ -104,6 +104,8 @@ def detect_dflash_file(
p = Path(path)
weight_name = p.name if p.suffix.lower() == ".gguf" else None
start_dir = p.parent if p.is_file() else p
+ # Not assets/: the published sidecar names no family, so in Hermes' shared pool it
+ # could not be told apart from another download's, and Hermes stages no DFlash.
dirs = [start_dir]
if search_root is not None:
dirs.append(Path(search_root))
diff --git a/studio/backend/utils/models/model_config.py b/studio/backend/utils/models/model_config.py
index cd472f9b370..1fc63ef6d2e 100644
--- a/studio/backend/utils/models/model_config.py
+++ b/studio/backend/utils/models/model_config.py
@@ -1949,6 +1949,7 @@ def detect_mmproj_file(
path: str,
search_root: Optional[str] = None,
allow_disjoint_search_root: bool = False,
+ accept: Optional[Callable[[str], bool]] = None,
) -> Optional[str]:
"""Find the mmproj GGUF for a model.
@@ -1956,6 +1957,7 @@ def detect_mmproj_file(
to also walk (snapshot layouts where the weight is in ``snapshot/BF16/``
but the projector sits at ``snapshot/``). A trusted cache resolver may set
``allow_disjoint_search_root`` for another revision of the same repository.
+ ``accept`` applies caller authorization before candidate metadata is read.
Returns the projector path or ``None``."""
p = Path(path)
start_dir = p.parent if p.is_file() else p
@@ -1978,6 +1980,9 @@ def detect_mmproj_file(
scan_order.append(resolved)
_add(start_dir)
+ # Hermes stages the projector for a one-click download under models/assets/ so its own
+ # router never lists it as a model; the weight sits one level up as a flat file.
+ _add(start_dir / "assets")
# Ollama's .studio_links/foo.gguf -> blobs/sha256-...: also scan target dir.
try:
@@ -2018,6 +2023,8 @@ def detect_mmproj_file(
except OSError:
continue
for f in files:
+ if accept is not None and not accept(str(f)):
+ continue
try:
resolved = f.resolve()
# Interrupted download: llama-server can't open it and it must not shadow a real projector.
@@ -2067,12 +2074,13 @@ def detect_mmproj_file(
if not scored:
return None
- # Score first, then longest shared prefix, then shorter stem.
+ # Score first, then longest shared prefix, then shorter stem. The prefix is read past
+ # the ``mmproj-`` marker, or every projector in a shared pool ties at zero.
best = max(
scored,
key = lambda sc: (
sc[0],
- _shared_prefix_len(model_stem, sc[1].stem.lower()),
+ _shared_prefix_len(model_stem, _re.sub(r"^mmproj[-_]", "", sc[1].stem.lower())),
-len(sc[1].stem),
),
)
@@ -2173,7 +2181,8 @@ def detect_mtp_file(
p = Path(path)
weight_name = p.name.lower() if p.suffix.lower() == ".gguf" else None
start_dir = p.parent if p.is_file() else p
- dirs = [start_dir]
+ # Hermes stages a download's drafter under models/assets/, like its projector.
+ dirs = [start_dir, start_dir / "assets"]
if search_root is not None:
dirs.append(Path(search_root))
# Both tiers are collected before either is emitted: two sidecars can
@@ -2321,7 +2330,8 @@ def detect_dspark_file(
p = Path(path)
weight_name = p.name if p.suffix.lower() == ".gguf" else None
start_dir = p.parent if p.is_file() else p
- dirs = [start_dir]
+ # Hermes stages a download's drafter under models/assets/, like its projector.
+ dirs = [start_dir, start_dir / "assets"]
if search_root is not None:
dirs.append(Path(search_root))
@@ -3977,6 +3987,7 @@ class ModelConfig:
gguf_variant: Optional[str] = None,
drafter_accept: Optional[Callable[[str, str, str, str], bool]] = None,
gguf_companion_roots: Optional[Tuple[str, ...]] = None,
+ mmproj_accept: Optional[Callable[[str, str], bool]] = None,
) -> Optional["ModelConfig"]:
"""Create ModelConfig from a clean model identifier (HF repo or local
path), for FastAPI routes that send sanitized paths.
@@ -4000,6 +4011,8 @@ class ModelConfig:
gguf_companion_roots: Trusted snapshot directories belonging to the
resolver-selected local cache entry. Used only to locate a
compatible mmproj without changing the selected main weights.
+ mmproj_accept: ``(candidate, gguf_file) -> bool`` admission rule
+ applied before reading projector metadata for native loads.
Returns:
ModelConfig or None if it cannot be created.
@@ -4089,6 +4102,11 @@ class ModelConfig:
gguf_file,
search_root = root,
allow_disjoint_search_root = gguf_companion_roots is not None,
+ accept = (
+ (lambda candidate: mmproj_accept(candidate, gguf_file))
+ if mmproj_accept is not None
+ else None
+ ),
)
)
),
diff --git a/studio/backend/utils/paths/__init__.py b/studio/backend/utils/paths/__init__.py
index 3602c5c9581..594488a18aa 100644
--- a/studio/backend/utils/paths/__init__.py
+++ b/studio/backend/utils/paths/__init__.py
@@ -40,6 +40,7 @@ from .storage_roots import (
hf_default_cache_dir,
lmstudio_model_dirs,
ollama_model_dirs,
+ hermes_model_dirs,
well_known_model_dirs,
ensure_dir,
ensure_studio_directories,
@@ -91,6 +92,7 @@ __all__ = [
"hf_default_cache_dir",
"lmstudio_model_dirs",
"ollama_model_dirs",
+ "hermes_model_dirs",
"well_known_model_dirs",
"ensure_dir",
"ensure_studio_directories",
diff --git a/studio/backend/utils/paths/storage_roots.py b/studio/backend/utils/paths/storage_roots.py
index 2e8f53960b3..87002f22a29 100644
--- a/studio/backend/utils/paths/storage_roots.py
+++ b/studio/backend/utils/paths/storage_roots.py
@@ -325,17 +325,68 @@ def ollama_model_dirs() -> list[Path]:
return _existing_dirs(candidates, resolve = False)
+def _hermes_native_home() -> Path:
+ """Hermes' platform-native home, ignoring HERMES_HOME."""
+ if sys.platform == "win32":
+ local_appdata = os.environ.get("LOCALAPPDATA", "").strip()
+ base = Path(local_appdata) if local_appdata else Path.home() / "AppData" / "Local"
+ return base / "hermes"
+ return Path.home() / ".hermes"
+
+
+def _hermes_root() -> Path:
+ """The Hermes root a download hangs off, mirroring its own resolution.
+
+ HERMES_HOME under the native home (the normal and profile layouts) still
+ means the native home; a ``<root>/profiles/<name>`` path elsewhere means
+ ``<root>``; anything else IS the root (Docker / custom deployments).
+ """
+ env_home = os.environ.get("HERMES_HOME", "").strip()
+ native = _hermes_native_home()
+ if not env_home:
+ return native
+ env_path = Path(env_home)
+ try:
+ env_path.resolve().relative_to(native.resolve())
+ return native
+ except (OSError, ValueError):
+ pass
+ if env_path.parent.name == "profiles":
+ return env_path.parent.parent
+ return env_path
+
+
+def hermes_model_dirs() -> list[Path]:
+ """Return Hermes model directories that exist on disk.
+
+ Hermes Desktop's one-click GGUF downloads land in ``<root>/models``. That is
+ machine-scoped upstream, never profile-scoped -- a 20 GB GGUF is a machine
+ asset and every profile shares the one server that runs it -- so it hangs off
+ the root, not off HERMES_HOME when that names a profile.
+
+ The native root is scanned as well, because ``unsloth start hermes`` points
+ HERMES_HOME at a throwaway session dir while the user's real downloads stay
+ under the native home; scanning only the resolved root would lose them for the
+ duration of a session Studio launched itself.
+ """
+ return _existing_dirs(
+ [_hermes_root() / "models", _hermes_native_home() / "models"],
+ resolve = False,
+ )
+
+
def well_known_model_dirs() -> list[Path]:
"""Return directories commonly used by other local LLM tools.
Backs the folder browser's quick-pick chips. Returns only paths that
exist on disk, so the UI never shows dead chips. Order reflects rough
- likelihood of models being there -- LM Studio and Ollama first, then
- generic fallbacks.
+ likelihood of models being there -- LM Studio, Ollama and Hermes first,
+ then generic fallbacks.
"""
candidates: list[str | Path] = []
candidates.extend(lmstudio_model_dirs())
candidates.extend(ollama_model_dirs())
+ candidates.extend(hermes_model_dirs())
# HF hub cache root, separate from the explicit HF cache chip.
candidates.append(Path.home() / ".cache" / "huggingface" / "hub")
diff --git a/studio/frontend/src/features/chat/api/chat-adapter.ts b/studio/frontend/src/features/chat/api/chat-adapter.ts
index f6ad91a01a4..cff84c27541 100644
--- a/studio/frontend/src/features/chat/api/chat-adapter.ts
+++ b/studio/frontend/src/features/chat/api/chat-adapter.ts
@@ -2382,10 +2382,12 @@ const NON_CHAT_TASKS: ReadonlySet<string> = new Set([
]);
// ollama stays out by policy: local_model_resolver.py skips its scanner, so auto-loading one
-// promises an API identity that cannot be reached.
+// promises an API identity that cannot be reached. hermes is in: its scan is read-only, so the
+// resolver indexes it like LM Studio, and the name Hermes asks for resolves.
const AUTO_LOAD_LOCAL_SOURCES: ReadonlySet<string> = new Set([
"models_dir",
"lmstudio",
+ "hermes",
"custom",
]);
diff --git a/studio/frontend/src/features/chat/api/chat-api.ts b/studio/frontend/src/features/chat/api/chat-api.ts
index f14bdd365b4..27693be2288 100644
--- a/studio/frontend/src/features/chat/api/chat-api.ts
+++ b/studio/frontend/src/features/chat/api/chat-api.ts
@@ -576,7 +576,7 @@ export interface LocalModelInfo {
id: string;
display_name: string;
path: string;
- source: "models_dir" | "hf_cache" | "lmstudio" | "ollama" | "custom";
+ source: "models_dir" | "hf_cache" | "lmstudio" | "ollama" | "hermes" | "custom";
model_id?: string | null;
// Backend-detected weights format ("gguf" when known), for folders whose name lacks -GGUF.
model_format?: string | null;
diff --git a/studio/frontend/src/features/chat/local-model-options.ts b/studio/frontend/src/features/chat/local-model-options.ts
index edad6d574c6..c28542bb4f7 100644
--- a/studio/frontend/src/features/chat/local-model-options.ts
+++ b/studio/frontend/src/features/chat/local-model-options.ts
@@ -12,6 +12,7 @@ const CHAT_LOCAL_SOURCES: ReadonlySet<LocalModelInfo["source"]> = new Set([
"lmstudio",
"models_dir",
"ollama",
+ "hermes",
"custom",
]);
@@ -21,6 +22,8 @@ function baseModelLabel(source: LocalModelInfo["source"]): string {
return "LM Studio";
case "ollama":
return "Ollama";
+ case "hermes":
+ return "Hermes";
case "custom":
return "Custom Folders";
default:
diff --git a/studio/frontend/src/features/hub/inventory/api.ts b/studio/frontend/src/features/hub/inventory/api.ts
index bd59503ac9d..2a12c85c637 100644
--- a/studio/frontend/src/features/hub/inventory/api.ts
+++ b/studio/frontend/src/features/hub/inventory/api.ts
@@ -131,6 +131,7 @@ export interface LocalModelListResponse {
hf_cache_dir?: string | null;
lmstudio_dirs: string[];
ollama_dirs?: string[];
+ hermes_dirs?: string[];
models: LocalModelInfo[];
}
diff --git a/studio/frontend/src/features/hub/inventory/constants.ts b/studio/frontend/src/features/hub/inventory/constants.ts
index 6482f5f6029..0c0fbcbcc5b 100644
--- a/studio/frontend/src/features/hub/inventory/constants.ts
+++ b/studio/frontend/src/features/hub/inventory/constants.ts
@@ -6,6 +6,7 @@ export const LOCAL_MODEL_SOURCE = {
HF_CACHE: "hf_cache",
LMSTUDIO: "lmstudio",
OLLAMA: "ollama",
+ HERMES: "hermes",
CUSTOM: "custom",
} as const;
@@ -14,6 +15,7 @@ export const LOCAL_MODEL_SOURCES = [
LOCAL_MODEL_SOURCE.HF_CACHE,
LOCAL_MODEL_SOURCE.LMSTUDIO,
LOCAL_MODEL_SOURCE.OLLAMA,
+ LOCAL_MODEL_SOURCE.HERMES,
LOCAL_MODEL_SOURCE.CUSTOM,
] as const;
export type LocalSource = (typeof LOCAL_MODEL_SOURCES)[number];
diff --git a/studio/frontend/src/features/hub/inventory/view-models.ts b/studio/frontend/src/features/hub/inventory/view-models.ts
index 5bb72c15510..34d82ba49d7 100644
--- a/studio/frontend/src/features/hub/inventory/view-models.ts
+++ b/studio/frontend/src/features/hub/inventory/view-models.ts
@@ -22,6 +22,8 @@ export function localSourceLabel(source: LocalModelInfo["source"]): string {
return "LM Studio";
case "ollama":
return "Ollama";
+ case "hermes":
+ return "Hermes";
case "custom":
return "Custom folder";
case "models_dir":
@@ -235,10 +237,12 @@ function sourceSortWeight(source: LocalModelInfo["source"]): number {
return 2;
case "ollama":
return 3;
- case "hf_cache":
+ case "hermes":
return 4;
- default:
+ case "hf_cache":
return 5;
+ default:
+ return 6;
}
}
diff --git a/studio/frontend/src/features/model-picker/components/model-selector/pickers.tsx b/studio/frontend/src/features/model-picker/components/model-selector/pickers.tsx
index 760d1c7e86b..1f48fb128cd 100644
--- a/studio/frontend/src/features/model-picker/components/model-selector/pickers.tsx
+++ b/studio/frontend/src/features/model-picker/components/model-selector/pickers.tsx
@@ -2924,10 +2924,14 @@ export function HubModelPicker({
);
// Ollama rows list alongside custom folders: both are user-managed stores outside ./models,
// and an Ollama root added as a custom folder is where the rows were expected (#9226).
+ // Hermes' one-click downloads are the same kind of store; a source in no bucket never renders.
const customFolderModels = useMemo(
() =>
pickerInventory.localModels.filter(
- (m) => m.source === "custom" || m.source === "ollama",
+ (m) =>
+ m.source === "custom" ||
+ m.source === "ollama" ||
+ m.source === "hermes",
),
[pickerInventory.localModels],
);
diff --git a/studio/frontend/src/features/model-picker/inventory/use-chat-picker-inventory.ts b/studio/frontend/src/features/model-picker/inventory/use-chat-picker-inventory.ts
index 954db47d4db..a4145e65e8e 100644
--- a/studio/frontend/src/features/model-picker/inventory/use-chat-picker-inventory.ts
+++ b/studio/frontend/src/features/model-picker/inventory/use-chat-picker-inventory.ts
@@ -22,6 +22,7 @@ const PICKER_LOCAL_SOURCES: ReadonlySet<LocalSource> = new Set([
"lmstudio",
"models_dir",
"ollama",
+ "hermes",
"custom",
]);
diff --git a/studio/frontend/src/features/recipe-studio/dialogs/models/local-recipe-model-selector.tsx b/studio/frontend/src/features/recipe-studio/dialogs/models/local-recipe-model-selector.tsx
index 68e9f71d84c..4aa9bbb3c1c 100644
--- a/studio/frontend/src/features/recipe-studio/dialogs/models/local-recipe-model-selector.tsx
+++ b/studio/frontend/src/features/recipe-studio/dialogs/models/local-recipe-model-selector.tsx
@@ -77,6 +77,8 @@ function sourceLabel(model: LocalModelInfo): string {
return "LM Studio";
case "ollama":
return "Ollama";
+ case "hermes":
+ return "Hermes";
case "custom":
return "Custom folder";
default:
diff --git a/studio/frontend/src/features/train-model-picker/components/train-model-picker-view-model.ts b/studio/frontend/src/features/train-model-picker/components/train-model-picker-view-model.ts
index 6231b197377..a0fffbb6984 100644
--- a/studio/frontend/src/features/train-model-picker/components/train-model-picker-view-model.ts
+++ b/studio/frontend/src/features/train-model-picker/components/train-model-picker-view-model.ts
@@ -40,8 +40,10 @@ function trainModelSourceWeight(source: LocalSource): number {
return 3;
case "ollama":
return 4;
- default:
+ case "hermes":
return 5;
+ default:
+ return 6;
}
}
diff --git a/studio/frontend/src/features/train-model-picker/components/train-model-selector.tsx b/studio/frontend/src/features/train-model-picker/components/train-model-selector.tsx
index dbef18bb79f..c2334eeb75b 100644
--- a/studio/frontend/src/features/train-model-picker/components/train-model-selector.tsx
+++ b/studio/frontend/src/features/train-model-picker/components/train-model-selector.tsx
@@ -105,6 +105,8 @@ function localModelSourceLabelKey(source: LocalSource): TranslationKey {
return "studio.modelPicker.sourceLmStudio";
case "ollama":
return "studio.modelPicker.sourceOllama";
+ case "hermes":
+ return "studio.modelPicker.sourceHermes";
case "custom":
return "studio.modelPicker.sourceCustomFolder";
default:
diff --git a/studio/frontend/src/features/training/api/models-api.ts b/studio/frontend/src/features/training/api/models-api.ts
index 4d77d010e48..0b484ef2acd 100644
--- a/studio/frontend/src/features/training/api/models-api.ts
+++ b/studio/frontend/src/features/training/api/models-api.ts
@@ -93,7 +93,7 @@ export interface LocalModelInfo {
id: string;
display_name: string;
path: string;
- source: "models_dir" | "hf_cache" | "lmstudio" | "ollama" | "custom";
+ source: "models_dir" | "hf_cache" | "lmstudio" | "ollama" | "hermes" | "custom";
model_id?: string | null;
updated_at?: number | null;
}
diff --git a/studio/frontend/src/i18n/locales/ar.ts b/studio/frontend/src/i18n/locales/ar.ts
index 91d9adfd82b..81debf6e72c 100644
--- a/studio/frontend/src/i18n/locales/ar.ts
+++ b/studio/frontend/src/i18n/locales/ar.ts
@@ -1897,6 +1897,7 @@ export const ar = {
sourceHfCache: "ذاكرة HF المؤقتة",
sourceLmStudio: "LM Studio",
sourceOllama: "Ollama",
+ sourceHermes: "Hermes",
sourceCustomFolder: "مجلد مخصّص",
sourceLocalModel: "نموذج محلي",
vramOomBadge: "OOM",
diff --git a/studio/frontend/src/i18n/locales/de.ts b/studio/frontend/src/i18n/locales/de.ts
index 7428c35f04c..3012133a888 100644
--- a/studio/frontend/src/i18n/locales/de.ts
+++ b/studio/frontend/src/i18n/locales/de.ts
@@ -1950,6 +1950,7 @@ export const de = {
sourceHfCache: "HF-Cache",
sourceLmStudio: "LM Studio",
sourceOllama: "Ollama",
+ sourceHermes: "Hermes",
sourceCustomFolder: "Benutzerdefinierter Ordner",
sourceLocalModel: "Lokales Modell",
vramOomBadge: "OOM",
diff --git a/studio/frontend/src/i18n/locales/en.ts b/studio/frontend/src/i18n/locales/en.ts
index 5d4046d0598..ec86ef4725a 100644
--- a/studio/frontend/src/i18n/locales/en.ts
+++ b/studio/frontend/src/i18n/locales/en.ts
@@ -1879,6 +1879,7 @@ export const en = {
sourceHfCache: "HF cache",
sourceLmStudio: "LM Studio",
sourceOllama: "Ollama",
+ sourceHermes: "Hermes",
sourceCustomFolder: "Custom folder",
sourceLocalModel: "Local model",
vramOomBadge: "OOM",
diff --git a/studio/frontend/src/i18n/locales/es.ts b/studio/frontend/src/i18n/locales/es.ts
index 65e2e1e5ba2..f60df4227b6 100644
--- a/studio/frontend/src/i18n/locales/es.ts
+++ b/studio/frontend/src/i18n/locales/es.ts
@@ -1941,6 +1941,7 @@ export const es = {
sourceHfCache: "Caché de HF",
sourceLmStudio: "LM Studio",
sourceOllama: "Ollama",
+ sourceHermes: "Hermes",
sourceCustomFolder: "Carpeta personalizada",
sourceLocalModel: "Modelo local",
vramOomBadge: "OOM",
diff --git a/studio/frontend/src/i18n/locales/fr.ts b/studio/frontend/src/i18n/locales/fr.ts
index d49f44e427b..e99c88e7fe6 100644
--- a/studio/frontend/src/i18n/locales/fr.ts
+++ b/studio/frontend/src/i18n/locales/fr.ts
@@ -1952,6 +1952,7 @@ export const fr = {
sourceHfCache: "Cache HF",
sourceLmStudio: "LM Studio",
sourceOllama: "Ollama",
+ sourceHermes: "Hermes",
sourceCustomFolder: "Dossier personnalisé",
sourceLocalModel: "Modèle local",
vramOomBadge: "OOM",
diff --git a/studio/frontend/src/i18n/locales/hi.ts b/studio/frontend/src/i18n/locales/hi.ts
index 887cdc601b1..a2e3102acda 100644
--- a/studio/frontend/src/i18n/locales/hi.ts
+++ b/studio/frontend/src/i18n/locales/hi.ts
@@ -1906,6 +1906,7 @@ export const hi = {
sourceHfCache: "HF कैश",
sourceLmStudio: "LM Studio",
sourceOllama: "Ollama",
+ sourceHermes: "Hermes",
sourceCustomFolder: "कस्टम फ़ोल्डर",
sourceLocalModel: "स्थानीय मॉडल",
vramOomBadge: "OOM",
diff --git a/studio/frontend/src/i18n/locales/it.ts b/studio/frontend/src/i18n/locales/it.ts
index d1cbd3ae3eb..fc031cde974 100644
--- a/studio/frontend/src/i18n/locales/it.ts
+++ b/studio/frontend/src/i18n/locales/it.ts
@@ -1948,6 +1948,7 @@ export const it = {
sourceHfCache: "Cache HF",
sourceLmStudio: "LM Studio",
sourceOllama: "Ollama",
+ sourceHermes: "Hermes",
sourceCustomFolder: "Cartella personalizzata",
sourceLocalModel: "Modello locale",
vramOomBadge: "OOM",
diff --git a/studio/frontend/src/i18n/locales/ja.ts b/studio/frontend/src/i18n/locales/ja.ts
index 8efb2169099..9ed1b02469f 100644
--- a/studio/frontend/src/i18n/locales/ja.ts
+++ b/studio/frontend/src/i18n/locales/ja.ts
@@ -1841,6 +1841,7 @@ export const ja = {
sourceHfCache: "HF キャッシュ",
sourceLmStudio: "LM Studio",
sourceOllama: "Ollama",
+ sourceHermes: "Hermes",
sourceCustomFolder: "カスタムフォルダ",
sourceLocalModel: "ローカルモデル",
scanningLocal: "ローカルモデルをスキャン中…",
diff --git a/studio/frontend/src/i18n/locales/ko.ts b/studio/frontend/src/i18n/locales/ko.ts
index 66f2a8d0b5b..681cd7c315e 100644
--- a/studio/frontend/src/i18n/locales/ko.ts
+++ b/studio/frontend/src/i18n/locales/ko.ts
@@ -1865,6 +1865,7 @@ export const ko = {
sourceHfCache: "HF 캐시",
sourceLmStudio: "LM Studio",
sourceOllama: "Ollama",
+ sourceHermes: "Hermes",
sourceCustomFolder: "사용자 지정 폴더",
sourceLocalModel: "로컬 모델",
scanningLocal: "로컬 모델을 스캔하는 중…",
diff --git a/studio/frontend/src/i18n/locales/pt-br.ts b/studio/frontend/src/i18n/locales/pt-br.ts
index b3a29866f38..ec8ac26daf4 100644
--- a/studio/frontend/src/i18n/locales/pt-br.ts
+++ b/studio/frontend/src/i18n/locales/pt-br.ts
@@ -1923,6 +1923,7 @@ export const ptBR = {
sourceHfCache: "Cache do HF",
sourceLmStudio: "LM Studio",
sourceOllama: "Ollama",
+ sourceHermes: "Hermes",
sourceCustomFolder: "Pasta personalizada",
sourceLocalModel: "Modelo local",
vramOomBadge: "OOM",
diff --git a/studio/frontend/src/i18n/locales/ru.ts b/studio/frontend/src/i18n/locales/ru.ts
index be94a074dcf..f117aef1e1d 100644
--- a/studio/frontend/src/i18n/locales/ru.ts
+++ b/studio/frontend/src/i18n/locales/ru.ts
@@ -1893,6 +1893,7 @@ export const ru = {
sourceHfCache: "Кэш HF",
sourceLmStudio: "LM Studio",
sourceOllama: "Ollama",
+ sourceHermes: "Hermes",
sourceCustomFolder: "Пользовательская папка",
sourceLocalModel: "Локальная модель",
scanningLocal: "Сканирование локальных моделей…",
diff --git a/studio/frontend/src/i18n/locales/zh-CN.ts b/studio/frontend/src/i18n/locales/zh-CN.ts
index 3bf805e3f6c..dd40ebbcfc3 100644
--- a/studio/frontend/src/i18n/locales/zh-CN.ts
+++ b/studio/frontend/src/i18n/locales/zh-CN.ts
@@ -1818,6 +1818,7 @@ export const zhCN = {
sourceHfCache: "HF 缓存",
sourceLmStudio: "LM Studio",
sourceOllama: "Ollama",
+ sourceHermes: "Hermes",
sourceCustomFolder: "自定义文件夹",
sourceLocalModel: "本地模型",
scanningLocal: "正在扫描本地模型…",
diff --git a/studio/frontend/tests/chat-local-model-options.test.ts b/studio/frontend/tests/chat-local-model-options.test.ts
index 8aac26f455e..eb120403fd8 100644
--- a/studio/frontend/tests/chat-local-model-options.test.ts
+++ b/studio/frontend/tests/chat-local-model-options.test.ts
@@ -54,6 +54,28 @@ test("Ollama rows are offered under their own label", () => {
assert.equal(localGgufKindFor(option, true), "direct");
});
+test("Hermes downloads are offered under their own label", () => {
+ // Hermes Desktop stages one-click downloads as flat GGUFs in ~/.hermes/models. The row is a
+ // plain file path, loadable as-is; it must clear CHAT_LOCAL_SOURCES or the model Hermes
+ // just fetched is missing from the very picker it should show up in.
+ const options = chatLocalModelOptions([
+ row({
+ id: "/home/u/.hermes/models/Qwen3.8-27B-UD-Q4_K_M.gguf",
+ path: "/home/u/.hermes/models/Qwen3.8-27B-UD-Q4_K_M.gguf",
+ display_name: "Qwen3.8-27B-UD-Q4_K_M",
+ source: "hermes",
+ model_format: "gguf",
+ }),
+ ]);
+ assert.equal(options.length, 1);
+ const option = options[0];
+ assert.ok(option);
+ assert.equal(option.name, "Qwen3.8-27B-UD-Q4_K_M");
+ assert.equal(option.baseModel, "Hermes");
+ assert.equal(option.isGguf, true);
+ assert.equal(option.isDirectGguf, true);
+});
+
test("a directory with two weight formats yields one option per load id", () => {
// The shared inventory keys a row on (format, path), so this arrives as two rows with the
// same `id`. The selector keys on `id`, so both would share a React key and read as
diff --git a/studio/frontend/tests/hub-inventory-hermes-source.test.ts b/studio/frontend/tests/hub-inventory-hermes-source.test.ts
new file mode 100644
index 00000000000..f7d5331fc2e
--- /dev/null
+++ b/studio/frontend/tests/hub-inventory-hermes-source.test.ts
@@ -0,0 +1,70 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import { registerStoreStubResolver } from "./helpers/kit.ts";
+
+registerStoreStubResolver();
+
+const { LOCAL_MODEL_SOURCES } = await import(
+ "../src/features/hub/inventory/constants.ts"
+);
+const { buildLocalInventoryRows, localSourceLabel } = await import(
+ "../src/features/hub/inventory/view-models.ts"
+);
+
+function hermesModel(overrides: Record<string, unknown> = {}) {
+ return {
+ id: "/home/u/.hermes/models/Qwen3-8B-UD-Q4_K_M.gguf",
+ load_id: "/home/u/.hermes/models/Qwen3-8B-UD-Q4_K_M.gguf",
+ display_name: "Qwen3-8B-UD-Q4_K_M",
+ path: "/home/u/.hermes/models/Qwen3-8B-UD-Q4_K_M.gguf",
+ source: "hermes",
+ model_format: "gguf",
+ runtime: "llama_cpp",
+ updated_at: 1_756_000_000,
+ ...overrides,
+ };
+}
+
+test("hermes is a known local source", () => {
+ assert.ok(LOCAL_MODEL_SOURCES.includes("hermes"));
+});
+
+test("a Hermes download is labelled by the app that fetched it", () => {
+ assert.equal(localSourceLabel("hermes"), "Hermes");
+});
+
+test("a Hermes GGUF becomes a loadable local row", () => {
+ // eslint-disable-next-line @typescript-eslint/no-explicit-any
+ const rows = buildLocalInventoryRows([hermesModel() as any]);
+ assert.equal(rows.length, 1);
+ assert.equal(rows[0].source, "hermes");
+ assert.equal(rows[0].sourceLabel, "Hermes");
+ assert.equal(rows[0].isGguf, true);
+ assert.equal(rows[0].title, "Qwen3-8B-UD-Q4_K_M");
+});
+
+test("the chat picker allowlist admits Hermes rows", async () => {
+ // PICKER_LOCAL_SOURCES and CHAT_LOCAL_SOURCES are documented as the same set; a source
+ // present in one and not the other shows a model in Chat that the picker cannot pick.
+ const fs = await import("node:fs/promises");
+ const picker = await fs.readFile(
+ new URL(
+ "../src/features/model-picker/inventory/use-chat-picker-inventory.ts",
+ import.meta.url,
+ ),
+ "utf8",
+ );
+ const chat = await fs.readFile(
+ new URL("../src/features/chat/local-model-options.ts", import.meta.url),
+ "utf8",
+ );
+ const listed = (src: string): string[] =>
+ [...src.matchAll(/new Set\(\[([^\]]*)\]\)/g)][0]?.[1].match(/"[a-z_]+"/g) ?? [];
+ assert.deepEqual(listed(picker), listed(chat));
+ assert.ok(listed(picker).includes('"hermes"'));
+});
+