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: list, reveal and delete audio.cpp umbrella models by folder (#13519)

Etherl3207f044e928
diff --git a/studio/backend/core/inference/audio_cpp_models.py b/studio/backend/core/inference/audio_cpp_models.py
index e7167fe8283..d018233b303 100644
--- a/studio/backend/core/inference/audio_cpp_models.py
+++ b/studio/backend/core/inference/audio_cpp_models.py
@@ -2269,6 +2269,7 @@ def resolve(
)
with _resolve_lock:
hit = _resolve_cache.get(key)
+ generation = _forget_generation
if hit is not None and time.monotonic() - hit[0] < (_RESOLVE_TTL_SECONDS if network else 20.0):
return hit[1]
if gguf_hint and ref.repo_id and not is_umbrella_id(ref.id):
@@ -2281,7 +2282,8 @@ def resolve(
with _resolve_lock:
if len(_resolve_cache) > 256:
_resolve_cache.clear()
- _resolve_cache[key] = (time.monotonic(), model)
+ if generation == _forget_generation:
+ _resolve_cache[key] = (time.monotonic(), model)
if model is not None:
_known_audio_cpp_ids.add(model.id.lower())
return model
@@ -2289,7 +2291,10 @@ def resolve(
def forget(identifier: Optional[str] = None) -> None:
"""Drop memoized resolutions (after a download or delete changed the cache)."""
+ global _forget_generation
with _resolve_lock:
+ # A lookup already reading the old cache must not store its answer after this.
+ _forget_generation += 1
# What is downloaded changed too, so the next status poll must not reuse the old listing.
_downloaded_cache.clear()
if identifier is None:
@@ -2657,6 +2662,182 @@ def folder_row_for_download(repo_id: str, variant: Optional[str]) -> Optional[tu
return row_id, "/".join([*parts[1:-1], quant_label(f"{parts[-1]}.gguf")])
+def cached_folder_target(
+ identifier: Optional[str], variant: Optional[str] = None
+) -> Optional[tuple[str, list[str]]]:
+ """``(umbrella repo, path-qualified variant keys)`` a cache action on an umbrella folder row
+ works on, from the cache only; None for any other id.
+
+ With a variant, only that folder's own variant (a bare ``Q8_0`` would name another folder's file
+ at repo scope); without one, every variant of the folder with its GGUF on disk. Never the whole
+ repo: an empty list means nothing of this folder is cached.
+ """
+ if not is_umbrella_id(identifier):
+ return None
+ base, inline = split_variant_ref(str(identifier))
+ ref = parse_identifier(base)
+ if ref is None or not ref.folder:
+ return None
+ # No Hub folder name holds a colon; on Windows ``snapshot / "C:"`` would name the snapshot root.
+ if ":" in ref.folder:
+ return AUDIO_CPP_REPO, []
+ wanted = (variant or "").strip() or inline or ref.variant_hint
+ model = resolve(ref.id, wanted, network = False)
+ chosen: list[AudioCppVariant] = []
+ if model is not None and model.repo_id:
+ if wanted:
+ chosen = _cached_variants_named(model.variants, wanted, ref.folder)
+ else:
+ snapshots = snapshot_dirs(model.repo_id)
+ chosen = [
+ v
+ for v in model.variants
+ if v.primary
+ and any((s / v.primary).exists() or (s / v.primary).is_symlink() for s in snapshots)
+ ]
+ from hub.utils.gguf import gguf_variant_key
+
+ keys = [gguf_variant_key(v.primary) for v in chosen if v.primary]
+ if wanted and keys:
+ return AUDIO_CPP_REPO, keys
+ if wanted and model is not None and _on_disk_quant_named(model.variants, wanted, ref.folder):
+ return AUDIO_CPP_REPO, []
+ # A quant cancelled before any file finished has only download state; the variant delete clears it.
+ partial = _folder_state_keys(ref.folder)
+ if wanted:
+ partial = [k for k in partial if _state_key_named(k, wanted, ref.folder)]
+ return AUDIO_CPP_REPO, partial if len(partial) == 1 else []
+ seen = {k.lower() for k in keys}
+ return AUDIO_CPP_REPO, keys + [k for k in partial if k.lower() not in seen]
+
+
+def _on_disk_quant_named(variants: Sequence[AudioCppVariant], wanted: str, folder: str) -> bool:
+ """Whether ``wanted`` is ambiguous on disk: its quant and scope words fit several variants."""
+ found, quant_given = _variants_matching(variants, wanted, folder)
+ return quant_given and len(found) > 1
+
+
+def _folder_state_keys(folder: str) -> list[str]:
+ """Planner keys under ``<folder>/`` with a download manifest or cancel marker in the active cache."""
+ try:
+ from hub.utils import download_manifest
+ found = {
+ key
+ for listing in (
+ download_manifest.iter_variant_manifests(
+ "model", AUDIO_CPP_REPO, hub_cache = _hub_cache()
+ ),
+ download_manifest.iter_variant_markers(
+ "model", AUDIO_CPP_REPO, hub_cache = _hub_cache()
+ ),
+ )
+ for key, _path in listing
+ }
+ except Exception: # noqa: BLE001 - unreadable state names nothing more
+ return []
+ prefix = f"{folder.lower()}/"
+ return sorted(k for k in found if k.lower().startswith(prefix) and len(k) > len(prefix))
+
+
+def _state_key_named(key: str, wanted: str, folder: str) -> bool:
+ """Whether a folder's planner key (``<Folder>/<dirs>/<file stem>``) is the variant ``wanted``
+ names, by the same rules as a cached variant: the key itself, its file, or its quant plus scope
+ words."""
+ low = wanted.strip().replace("\\", "/").strip("/").lower()
+ path = key.lower()
+ stem = path.rsplit("/", 1)[-1]
+ if not low or low in (path, stem, f"{stem}.gguf") or f"{folder.lower()}/{low}" == path:
+ return bool(low)
+ parts = [p for p in low.split("/") if p]
+ if quant_label(f"{stem}.gguf").lower() != parts[-1]:
+ return False
+ dirs = set(path.split("/")[1:-1])
+ folder_words = set(re.split(r"[-_.]+", folder.lower()))
+ words = dirs | (set(re.split(r"[-_.]+", stem)) - folder_words)
+ return all(_scope_word_matches(w, words, stem) for w in parts[:-1])
+
+
+def _scope_word_matches(word: str, scope: set[str], stem: str) -> bool:
+ """A scope word is one of ``scope``, or a compound (``v4-small``) whose every part is a word of the
+ file stem: its parts can all be folder words, which ``scope`` leaves out."""
+ if word in scope:
+ return True
+ parts = [p for p in re.split(r"[-_.]+", word) if p]
+ return len(parts) > 1 and set(parts) <= set(re.split(r"[-_.]+", stem))
+
+
+def _cached_variants_named(
+ variants: Sequence[AudioCppVariant], wanted: str, folder: str
+) -> list[AudioCppVariant]:
+ """The cached variants ``wanted`` names. The picker keys a multi-size folder's quants from the Hub
+ listing (``tiny/Q8_0``) while a cache holding one size keys it ``Q8_0``, so scope words also
+ match the file path; a quant must still pick exactly one, never a fallback default (``match_variant``
+ would rank a bare ``Q8_0`` onto one of ``tiny/Q8_0`` and ``small/Q8_0``)."""
+ found, quant_given = _variants_matching(variants, wanted, folder)
+ return found if not quant_given or len(found) == 1 else []
+
+
+def _variants_matching(
+ variants: Sequence[AudioCppVariant], wanted: str, folder: str
+) -> tuple[list[AudioCppVariant], bool]:
+ """Every variant ``wanted`` could name, and whether it named a quant (which must be unique)."""
+ low = wanted.strip().replace("\\", "/").strip("/").lower()
+ for exact in (
+ [v for v in variants if v.key.lower() == low],
+ [v for v in variants if v.main_file.lower() in (low, f"{folder}/{low}".lower())],
+ [v for v in variants if v.main_file.rsplit("/", 1)[-1].lower() in (low, f"{low}.gguf")],
+ ):
+ if len(exact) == 1:
+ return exact, False
+ if exact:
+ return [], False
+ parts = [p for p in low.split("/") if p]
+ if not parts:
+ return [], False
+ quants = {quant_label(v.main_file).lower() for v in variants}
+ quant = parts[-1] if parts[-1] in quants else None
+ words = parts[:-1] if quant else parts
+ folder_words = set(re.split(r"[-_.]+", folder.lower()))
+
+ def stem_of(v: AudioCppVariant) -> str:
+ return v.main_file.rsplit("/", 1)[-1].lower().removesuffix(".gguf")
+
+ def scope(v: AudioCppVariant) -> set[str]:
+ # A size or edition: a directory of the key, or a word of the file name the folder's own
+ # name does not supply (``tiny`` in ``moonshine-streaming-tiny-q8_0``).
+ return set(v.key.lower().split("/")[:-1]) | (
+ set(re.split(r"[-_.]+", stem_of(v))) - folder_words
+ )
+
+ found = [
+ v
+ for v in variants
+ if (quant is None or quant_label(v.main_file).lower() == quant)
+ and all(_scope_word_matches(w, scope(v), stem_of(v)) for w in words)
+ ]
+ return found, quant is not None
+
+
+def folder_snapshot_dir(identifier: Optional[str]) -> Optional[Path]:
+ """``<snapshot>/<Folder>`` of the first cached snapshot holding an umbrella folder row."""
+ ref = parse_identifier(split_variant_ref(str(identifier or ""))[0])
+ if ref is None or not ref.folder or not ref.repo_id or ":" in ref.folder:
+ return None
+ snapshots = [s for s in snapshot_dirs(ref.repo_id) if (s / ref.folder).is_dir()]
+ # The snapshot holding a variant's weights, not a newer metadata-only or partial one.
+ from core.inference.audio_cpp_files import _file_complete
+
+ model = resolve(ref.id, network = False)
+ variants = [v for v in (model.variants if model is not None else ()) if v.files]
+ for snapshot in snapshots:
+ if any(all(_file_complete(snapshot / f.path, f.size) for f in v.files) for v in variants):
+ return snapshot / ref.folder
+ for snapshot in snapshots:
+ if any(p.suffix.lower() == ".gguf" for p in (snapshot / ref.folder).rglob("*")):
+ return snapshot / ref.folder
+ return snapshots[0] / ref.folder if snapshots else None
+
+
def require_runnable(model: AudioCppModel, task: Optional[str] = None) -> None:
"""Raise ``AudioCppModelError`` when Studio cannot run ``model`` (for ``task`` when given)."""
if model.unsupported:
@@ -2695,6 +2876,7 @@ RECOMMENDED_STT_MODELS: tuple[str, ...] = tuple(
_downloaded_cache: dict[Optional[str], tuple[float, list[AudioCppModel]]] = {}
+_forget_generation = 0
_DOWNLOADED_TTL_SECONDS = 10.0
@@ -2706,11 +2888,13 @@ def downloaded_models(task: Optional[str] = None) -> list[AudioCppModel]:
"""
with _resolve_lock:
hit = _downloaded_cache.get(task)
+ generation = _forget_generation
if hit is not None and time.monotonic() - hit[0] < _DOWNLOADED_TTL_SECONDS:
return list(hit[1])
out = _scan_downloaded(task)
with _resolve_lock:
- _downloaded_cache[task] = (time.monotonic(), out)
+ if generation == _forget_generation:
+ _downloaded_cache[task] = (time.monotonic(), out)
return list(out)
diff --git a/studio/backend/hub/schemas/inventory.py b/studio/backend/hub/schemas/inventory.py
index 909548ca065..c2229707d37 100644
--- a/studio/backend/hub/schemas/inventory.py
+++ b/studio/backend/hub/schemas/inventory.py
@@ -334,6 +334,7 @@ class CachedGgufRepo(CachedRepoBase):
"watching for on-disk change need this to notice it."
),
)
+ umbrella_folder: bool = False
class CachedGgufResponse(BaseModel):
diff --git a/studio/backend/hub/services/models/cache_inventory.py b/studio/backend/hub/services/models/cache_inventory.py
index 133058c70f3..a0a320078ff 100644
--- a/studio/backend/hub/services/models/cache_inventory.py
+++ b/studio/backend/hub/services/models/cache_inventory.py
@@ -745,7 +745,71 @@ def _scan_cached_gguf(
and row["task"] in CHAT_GGUF_TASKS
):
row["load_id"] = row["repo_id"]
- return sorted(seen_lower.values(), key = lambda c: c["repo_id"])
+ rows = list(seen_lower.values())
+ umbrella = next((row for row in rows if is_audio_cpp_repo_id(row["repo_id"])), None)
+ if umbrella is not None:
+ rows.extend(_umbrella_folder_rows(umbrella, cache_scans, active_hub_cache))
+ return sorted(rows, key = lambda c: c["repo_id"])
+
+
+def _umbrella_folder_rows(umbrella: dict, cache_scans, active_hub_cache) -> list[dict]:
+ """One row per downloaded folder of the audio.cpp umbrella repo, so an Audio page can list its own
+ models On Device. Flagged ``umbrella_folder``: the Model Hub keeps managing the repo as one row."""
+ try:
+ from core.inference import audio_cpp_models as acm
+
+ active = Path(active_hub_cache).resolve(strict = False)
+ repo_info = next(
+ (
+ repo
+ for scan in cache_scans
+ for repo in scan.repos
+ if str(repo.repo_type) == "model"
+ and is_audio_cpp_repo_id(repo.repo_id)
+ and Path(repo.repo_path).parent.resolve(strict = False) == active
+ ),
+ None,
+ )
+ if repo_info is None:
+ return []
+ sizes: dict[str, int] = {}
+ seen_blobs: set[str] = set()
+ for rev in repo_info.revisions:
+ for f in rev.files:
+ try:
+ folder = Path(f.file_path).relative_to(rev.snapshot_path).parts[0]
+ except (ValueError, IndexError):
+ continue
+ blob = str(getattr(f, "blob_path", "") or f.file_path)
+ if blob in seen_blobs:
+ continue
+ seen_blobs.add(blob)
+ sizes[folder.lower()] = sizes.get(folder.lower(), 0) + (f.size_on_disk or 0)
+ rows: dict[str, dict] = {}
+ for model in acm.downloaded_models():
+ # A companion with no page of its own (the forced aligner) stays under the repo row.
+ if not acm.is_umbrella_id(model.id) or not model.workflows or model.id.lower() in rows:
+ continue
+ row = {
+ **umbrella,
+ "repo_id": model.id,
+ "load_id": model.id,
+ "inventory_id": _local_inventory_id("cache", "gguf", model.id),
+ "cache_path": str(repo_info.repo_path),
+ "size_bytes": sizes.get(model.folder.lower(), 0),
+ "task": model.hub_task,
+ "audio_type": model.audio_type,
+ "audio_workflows": list(model.workflows),
+ "partial": False,
+ "has_variant_state": False,
+ "capabilities": {**umbrella["capabilities"], "can_chat": False},
+ "umbrella_folder": True,
+ }
+ rows[model.id.lower()] = row
+ return list(rows.values())
+ except Exception as e: # noqa: BLE001 - never hide the umbrella row itself
+ logger.warning("Could not list audio.cpp folder rows: %s", scrub_paths(e))
+ return []
class _CacheSourceChanged(RuntimeError):
diff --git a/studio/backend/hub/services/models/companion_cleanup.py b/studio/backend/hub/services/models/companion_cleanup.py
index ae229803abc..30fd484dd48 100644
--- a/studio/backend/hub/services/models/companion_cleanup.py
+++ b/studio/backend/hub/services/models/companion_cleanup.py
@@ -89,10 +89,17 @@ def _variant_keys(repo_info, variant: str) -> set[str]:
def _variant_bytes(repo_info, variant: str) -> int:
+ from hub.services.models.deletion import _audio_cpp_package_scope
+
wanted = _variant_keys(repo_info, variant)
+ own, protected = _audio_cpp_package_scope(repo_info, variant)
def _matches(name: str) -> bool:
- return _is_main_gguf_filename(name) and gguf_variant_key(name).lower() in wanted
+ if name in protected:
+ return False
+ return name in own or (
+ _is_main_gguf_filename(name) and gguf_variant_key(name).lower() in wanted
+ )
return _repo_blob_bytes(repo_info, only = _matches)
@@ -229,12 +236,92 @@ class _SingleRepoScan:
self.repos = repos
+def _folder_delete_impact_blocking(
+ repo_id: str, variant: Optional[str], umbrella: str, keys: list[str], cache_path: Optional[str]
+) -> dict:
+ """The impact of deleting an umbrella folder row: the sum over its own variant keys."""
+ impacts = [_delete_impact_blocking(umbrella, key, cache_path) for key in keys]
+
+ def merged(field: str) -> list[dict]:
+ rows = {row["repo_id"]: row for impact in impacts for row in impact[field]}
+ return list(rows.values())
+
+ return {
+ "repo_id": repo_id,
+ "variant": variant,
+ "reclaimed_bytes": sum(impact["reclaimed_bytes"] for impact in impacts)
+ + (_shared_folder_extra_bytes(repo_id, keys) if len(keys) > 1 else 0),
+ "cache_path": impacts[0]["cache_path"],
+ "retained_companions": merged("retained_companions"),
+ "freeable_companions": merged("freeable_companions"),
+ "blocked_by": sorted({name for impact in impacts for name in impact["blocked_by"]}),
+ }
+
+
+def _shared_folder_extra_bytes(repo_id: str, keys: list[str]) -> int:
+ """Bytes of the files several deleted variants of one folder share and no kept variant lists
+ (a voice embedding beside two quants). Each per-variant preview counts them as still needed by
+ the other, but deleting the variants in turn removes them with the last."""
+ from core.inference.audio_cpp_models import resolve, snapshot_dirs
+
+ model = resolve(repo_id, network = False)
+ if model is None or not model.repo_id:
+ return 0
+ from hub.services.models import downloads
+
+ # The delete keeps a variant's extras while a sibling in its directory downloads; so does this.
+ busy = {
+ key.rsplit("/", 1)[0].lower() + "/"
+ for key in keys
+ if downloads.registry.has_active_peer_variant(
+ model.repo_id, key, prefix = key.rsplit("/", 1)[0] + "/"
+ )
+ }
+ deleting = {key.lower() for key in keys}
+ listed: dict[str, int] = {}
+ kept: set[str] = set()
+ for candidate in model.variants:
+ files = {f.path for f in candidate.files}
+ if candidate.primary and gguf_variant_key(candidate.primary).lower() in deleting:
+ for path in files:
+ listed[path] = listed.get(path, 0) + 1
+ else:
+ kept |= files
+ total = 0
+ seen: set[Path] = set()
+ shared = (
+ p
+ for p, count in listed.items()
+ if count > 1 and p not in kept and not any(p.lower().startswith(d) for d in busy)
+ )
+ for path in sorted(shared):
+ for snapshot in snapshot_dirs(model.repo_id):
+ try:
+ blob = (snapshot / path).resolve(strict = True)
+ except OSError:
+ continue
+ if blob not in seen:
+ seen.add(blob)
+ total += blob.stat().st_size
+ return total
+
+
async def delete_impact_response(
repo_id: str,
variant: Optional[str] = None,
cache_path: Optional[str] = None,
) -> dict:
"""What a delete of *repo_id* (/*variant*) would reclaim, retain, and be blocked by."""
+ from core.inference.audio_cpp_models import cached_folder_target
+
+ folder = await asyncio.to_thread(cached_folder_target, repo_id, (variant or "").strip() or None)
+ if folder is not None:
+ umbrella, keys = folder
+ if not keys:
+ raise HTTPException(status_code = 404, detail = "Model not found in cache")
+ return await asyncio.to_thread(
+ _folder_delete_impact_blocking, repo_id, variant, umbrella, keys, cache_path
+ )
if not _is_valid_repo_id(repo_id):
raise HTTPException(status_code = 400, detail = "Invalid repo_id format")
variant = (variant or "").strip() or None
diff --git a/studio/backend/hub/services/models/deletion.py b/studio/backend/hub/services/models/deletion.py
index d138e78cdfc..39d92846847 100644
--- a/studio/backend/hub/services/models/deletion.py
+++ b/studio/backend/hub/services/models/deletion.py
@@ -275,13 +275,39 @@ def _audio_cpp_package_scope(target_repo, variant: str) -> tuple[frozenset[str],
names = [name for _snap, _blob, name in _repo_file_matches(target_repo, lambda name: True)]
packages = package_variant_files(names)
if not packages:
- return frozenset(), frozenset()
+ return _umbrella_variant_scope(target_repo, variant)
wanted = (variant or "").strip().lower()
own = next((files for key, files in packages.items() if key.lower() == wanted), ())
protected = {path for key, files in packages.items() if key.lower() != wanted for path in files}
return frozenset(own), frozenset(protected)
+def _umbrella_variant_scope(target_repo, variant: str) -> tuple[frozenset[str], frozenset[str]]:
+ """``(own files, protected files)`` of one umbrella folder variant (``<Folder>/<file>`` key): its
+ voice embeddings and configs go with it, unless another cached variant of the folder lists them.
+ A sibling in the same directory still downloading is not listed yet, so its extras stay."""
+ from core.inference.audio_cpp_models import folder_row_for_download, resolve
+
+ repo_id = str(getattr(target_repo, "repo_id", ""))
+ row = folder_row_for_download(repo_id, variant)
+ model = resolve(row[0], network = False) if row else None
+ if model is None:
+ return frozenset(), frozenset()
+ # Every umbrella folder downloads on the same repo, so only a peer under this directory counts.
+ sibling_active = downloads.registry.has_active_peer_variant(
+ repo_id, variant, prefix = variant.rsplit("/", 1)[0] + "/"
+ )
+ own: set[str] = set()
+ protected: set[str] = set()
+ for candidate in model.variants:
+ files = {f.path for f in candidate.files}
+ if candidate.primary and gguf_variant_key(candidate.primary).lower() == variant.lower():
+ own |= files if not sibling_active else {candidate.primary}
+ else:
+ protected |= files
+ return frozenset(own - protected), frozenset(protected)
+
+
def _delete_gguf_variant_from_repos(
repo_id: str,
variant: str,
@@ -917,6 +943,38 @@ async def delete_cached_model_response(
become an installed checkpoint since the list the caller is acting on was built.
"""
account_access.require_installation_owner()
+ from core.inference.audio_cpp_models import cached_folder_target, folder_row_for_download
+
+ # Delete an umbrella folder's own variant keys, never the repo, which holds every other folder.
+ folder = await asyncio.to_thread(cached_folder_target, repo_id, (variant or "").strip() or None)
+ if folder is not None:
+ umbrella, keys = folder
+ if not keys:
+ raise HTTPException(status_code = 404, detail = "Model not found in cache")
+ # Reserve every key first, so a later key's download cannot start midway.
+ repo_key = await asyncio.to_thread(resolve_cached_repo_id_case, umbrella, repo_type = "model")
+ reserved: list[str] = []
+ try:
+ for key in keys:
+ if not downloads.registry.begin_delete(repo_key, key):
+ raise HTTPException(
+ status_code = 400,
+ detail = "Cancel the active downloads before deleting.",
+ )
+ reserved.append(key)
+ result: dict = {}
+ for key in keys:
+ result = await delete_cached_model_response(
+ umbrella,
+ key,
+ hf_token,
+ cache_path,
+ only_if_orphan = only_if_orphan,
+ )
+ finally:
+ for key in reserved:
+ downloads.registry.end_delete(repo_key, key)
+ return {**result, "repo_id": repo_id, "variant": variant}
if not _is_valid_repo_id(repo_id):
raise HTTPException(status_code = 400, detail = "Invalid repo_id format")
variant = (variant or "").strip() or None
@@ -925,16 +983,17 @@ async def delete_cached_model_response(
status_code = 400,
detail = f"Invalid gguf_variant: {variant!r}",
)
+ guard_id = (await asyncio.to_thread(folder_row_for_download, repo_id, variant) or (repo_id,))[0]
# Fail closed with 503 rather than unlink weights under a running process.
def _load_state_blocks_delete() -> Optional[str]:
- if _llama_cpp_blocks_delete(repo_id, variant) or (
- _inference_backend_blocks_delete(repo_id)
+ if _llama_cpp_blocks_delete(guard_id, variant) or (
+ _inference_backend_blocks_delete(guard_id)
):
return "Unload the model before deleting"
- if _audio_cpp_blocks_delete(repo_id):
+ if _audio_cpp_blocks_delete(guard_id):
return "Unload the audio model before deleting"
- return _diffusion_blocks_delete(repo_id) or _video_blocks_delete(repo_id)
+ return _diffusion_blocks_delete(guard_id) or _video_blocks_delete(guard_id)
try:
blocks_detail = await asyncio.to_thread(_load_state_blocks_delete)
@@ -1005,15 +1064,31 @@ async def delete_cached_model_response(
def _audio_cpp_blocks_delete(repo_id: str) -> bool:
"""Whether an audio.cpp model from this repo is resident or loading. An umbrella id names a
subfolder of the repo, so the id comparisons of the other guards never match it."""
- from core.inference.audio_cpp_models import repo_of
+ from core.inference.audio_cpp_models import (
+ is_umbrella_id,
+ parse_identifier,
+ resolve,
+ split_variant_ref,
+ )
from core.inference.orchestrator import peek_inference_backend
from core.inference.stt_audiocpp_sidecar import get_audio_cpp_stt_sidecar
wanted = (repo_id or "").strip().lower()
def holds(name) -> bool:
- repo = repo_of(name) if isinstance(name, str) else None
- return bool(repo and repo.lower() == wanted)
+ if not isinstance(name, str):
+ return False
+ base = split_variant_ref(name)[0]
+ ref = parse_identifier(base) if not base.lower().endswith(".gguf") else None
+ if ref is None or not ref.repo_id:
+ return False
+ # A folder is also held by a model loading it as a companion (MioTTS opens MioCodec).
+ if wanted in (ref.repo_id.lower(), ref.id.lower()):
+ return True
+ if not is_umbrella_id(wanted):
+ return False
+ model = resolve(base, network = False)
+ return bool(model and any(c.id.lower() == wanted for c in model.companions))
backend = peek_inference_backend()
active = getattr(backend, "active_model_name", None) if backend is not None else None
diff --git a/studio/backend/hub/services/models/gguf_variants.py b/studio/backend/hub/services/models/gguf_variants.py
index a682dc0a89a..c8551f019ea 100644
--- a/studio/backend/hub/services/models/gguf_variants.py
+++ b/studio/backend/hub/services/models/gguf_variants.py
@@ -1237,7 +1237,10 @@ async def get_gguf_variants_answer(
account_access.require_model_access, local_path, **access_options
)
hf_token = account_access.account_hf_token(hf_token)
- if not local_path:
+ from core.inference.audio_cpp_models import is_umbrella_id
+
+ # An umbrella folder row is never a directory: its On Device row sends the row id as local_path.
+ if not local_path or is_umbrella_id(repo_id):
audio_cpp_answer = await _audio_cpp_variants_answer(repo_id, hf_token, offline)
if audio_cpp_answer is not None:
return audio_cpp_answer
diff --git a/studio/backend/hub/utils/download_registry.py b/studio/backend/hub/utils/download_registry.py
index 6c4289e2634..1c7eeef43a2 100644
--- a/studio/backend/hub/utils/download_registry.py
+++ b/studio/backend/hub/utils/download_registry.py
@@ -1791,17 +1791,29 @@ class DownloadRegistry:
if not scopes:
self._deleting.pop(repo_id, None)
- def has_active_peer_variant(self, repo_id: str, variant: Optional[str]) -> bool:
+ def has_active_peer_variant(
+ self,
+ repo_id: str,
+ variant: Optional[str],
+ *,
+ prefix: Optional[str] = None,
+ ) -> bool:
"""Whether a DIFFERENT quantization of *repo_id* is downloading while *variant* is being deleted. When one is, the delete reclaims only this variant's files and leaves the shared companion (mmproj) for the live sibling. Point-in-time, but safe: the finalized companion is held by deletion's reference-count walk and a sibling starting mid-delete re-fetches it, so protection never depends on the sibling having resolved its blob hashes."""
repo_id = normalize_repo_key(repo_id)
target = (variant or "").strip().lower() or None
+ scope = (prefix or "").strip().lower()
+
+ def is_peer(key: str) -> bool:
+ peer = self._active_job_variant_locked(key)
+ return peer != target and (not scope or (peer or "").startswith(scope))
+
with self._lock:
active_keys = self._repo_active.get(repo_id, set())
for key in active_keys:
job = self._jobs.get(key)
if job is None or job.state not in _ACTIVE_STATES:
continue
- if self._active_job_variant_locked(key) != target:
+ if is_peer(key):
return True
# A retry peer between release_active_slot() and its reclaim is briefly absent from _repo_active while it still owns the shared companion, so mirror the released-but-active scan.
for key, job in self._jobs.items():
@@ -1809,7 +1821,7 @@ class DownloadRegistry:
continue
if job.state not in _ACTIVE_STATES:
continue
- if self._active_job_variant_locked(key) != target:
+ if is_peer(key):
return True
return False
diff --git a/studio/backend/hub/utils/inventory_scan.py b/studio/backend/hub/utils/inventory_scan.py
index a5940be0a4e..62349d47630 100644
--- a/studio/backend/hub/utils/inventory_scan.py
+++ b/studio/backend/hub/utils/inventory_scan.py
@@ -98,6 +98,11 @@ def invalidate_hf_cache_scans() -> None:
_hf_cache_scans_result = None
_hf_cache_scans_cached_at = 0.0
_hf_cache_scans_epoch += 1
+ try:
+ from core.inference.audio_cpp_models import forget
+ except Exception: # noqa: BLE001 - no audio.cpp support, nothing memoized
+ return
+ forget()
def hf_cache_scans_epoch() -> int:
diff --git a/studio/backend/routes/models.py b/studio/backend/routes/models.py
index d27633242c0..8940c8c9491 100644
--- a/studio/backend/routes/models.py
+++ b/studio/backend/routes/models.py
@@ -5740,6 +5740,27 @@ def _resolve_cached_model_path(repo_id: str, variant: Optional[str]) -> Path:
raise HTTPException(status_code = 404, detail = "Cached model path not found")
+def _resolve_cached_path_for_row(repo_id: str, variant: Optional[str]) -> Path:
+ """``_resolve_cached_model_path`` for a picker row id. An audio.cpp umbrella folder row resolves
+ to its own variant's file, or without a variant to its folder, never the repo's snapshot root."""
+ from core.inference.audio_cpp_models import cached_folder_target, folder_snapshot_dir
+
+ folder = cached_folder_target(repo_id, variant)
+ if folder is None:
+ if not _is_valid_repo_id(repo_id):
+ raise HTTPException(status_code = 400, detail = "Invalid repo_id format")
+ return _resolve_cached_model_path(repo_id, variant)
+ umbrella, keys = folder
+ if not keys:
+ raise HTTPException(status_code = 404, detail = "Model not found in cache")
+ if variant:
+ return _resolve_cached_model_path(umbrella, keys[0])
+ path = folder_snapshot_dir(repo_id)
+ if path is None:
+ raise HTTPException(status_code = 404, detail = "Cached model path not found")
+ return path
+
+
class CachedModelPathResponse(BaseModel):
path: str
is_dir: bool
@@ -5754,9 +5775,7 @@ async def get_cached_model_path(
"""Absolute on-disk path of a cached repo or one of its GGUF variants."""
if account_access.managed_account():
await asyncio.to_thread(account_access.require_model_access, repo_id)
- if not _is_valid_repo_id(repo_id):
- raise HTTPException(status_code = 400, detail = "Invalid repo_id format")
- path = await asyncio.to_thread(_resolve_cached_model_path, repo_id, variant.strip() or None)
+ path = await asyncio.to_thread(_resolve_cached_path_for_row, repo_id, variant.strip() or None)
return {"path": str(path), "is_dir": path.is_dir()}
@@ -5772,10 +5791,8 @@ async def reveal_cached_model(
await asyncio.to_thread(account_access.require_model_access, repo_id)
from utils.paths.path_utils import reveal_in_file_manager
- if not _is_valid_repo_id(repo_id):
- raise HTTPException(status_code = 400, detail = "Invalid repo_id format")
variant = (variant or "").strip() or None
- path = await asyncio.to_thread(_resolve_cached_model_path, repo_id, variant)
+ path = await asyncio.to_thread(_resolve_cached_path_for_row, repo_id, variant)
try:
await asyncio.to_thread(reveal_in_file_manager, path)
except Exception as e:
diff --git a/studio/backend/tests/test_audio_cpp_umbrella_ids.py b/studio/backend/tests/test_audio_cpp_umbrella_ids.py
new file mode 100644
index 00000000000..1b4db65cd2f
--- /dev/null
+++ b/studio/backend/tests/test_audio_cpp_umbrella_ids.py
@@ -0,0 +1,804 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+"""Cache actions on an audio.cpp umbrella folder row (``audio-cpp/audio.cpp-gguf/<Folder>``):
+delete, delete impact, cached path and reveal act on that folder alone, and the cached GGUF
+inventory lists each downloaded folder for the Audio pages."""
+
+import asyncio
+import hashlib
+import os
+import struct
+from pathlib import Path
+from types import SimpleNamespace
+
+import pytest
+from fastapi import HTTPException
+
+from core.inference import audio_cpp_files
+from core.inference import audio_cpp_models as acm
+from core.inference.audio_cpp_models import AUDIO_CPP_REPO
+
+QWEN = f"{AUDIO_CPP_REPO}/Qwen3-TTS-12Hz-0.6B-Base-GGUF"
+KOKORO = f"{AUDIO_CPP_REPO}/Kokoro-82M-GGUF"
+ASR = f"{AUDIO_CPP_REPO}/Qwen3-ASR-0.6B-GGUF"
+QWEN_FILE = "Qwen3-TTS-12Hz-0.6B-Base-GGUF/qwen3-tts-12hz-0.6b-base-q8_0.gguf"
+SNAPSHOT = Path("models--audio-cpp--audio.cpp-gguf") / "snapshots" / ("a" * 40)
+QWEN_KEY = "Qwen3-TTS-12Hz-0.6B-Base-GGUF/qwen3-tts-12hz-0.6b-base-q8_0"
+FILES = {
+ QWEN_FILE: "qwen3_tts",
+ "Qwen3-ASR-0.6B-GGUF/qwen3-asr-0.6b-q8_0.gguf": "qwen3_asr",
+ "Kokoro-82M-GGUF/kokoro-82m-q8_0.gguf": "kokoro_tts",
+}
+
+
+def _gguf(family: str, pad: int) -> bytes:
+ kv = [
+ ("general.architecture", 8, "audiocpp"),
+ ("general.name", 8, "t"),
+ ("audiocpp.model_spec.version", 4, 1),
+ ("audiocpp.model_spec.family", 8, family),
+ ]
+ out = bytearray(struct.pack("<IIQQ", 0x46554747, 3, 0, len(kv)))
+ for key, vtype, value in kv:
+ k = key.encode()
+ out += struct.pack("<Q", len(k)) + k + struct.pack("<I", vtype)
+ if vtype == 8:
+ v = value.encode()
+ out += struct.pack("<Q", len(v)) + v
+ else:
+ out += struct.pack("<I", value)
+ return bytes(out) + b"\0" * pad
+
+
+def _add_snapshot(hub: Path, sha: str, files: dict, *, main: bool) -> Path:
+ repo_dir = hub / ("models--" + AUDIO_CPP_REPO.replace("/", "--"))
+ snap = repo_dir / "snapshots" / sha
+ (repo_dir / "blobs").mkdir(parents = True, exist_ok = True)
+ if main:
+ (repo_dir / "refs").mkdir(exist_ok = True)
+ (repo_dir / "refs" / "main").write_text(sha)
+ for index, (rel, family) in enumerate(files.items()):
+ data = _gguf(family, 4096 * (index + 1)) + rel.encode()
+ blob = repo_dir / "blobs" / hashlib.sha256(data).hexdigest()
+ blob.write_bytes(data)
+ path = snap / rel
+ path.parent.mkdir(parents = True, exist_ok = True)
+ os.symlink(os.path.relpath(blob, path.parent), path)
+ return snap
+
+
+def hub(tmp_path, monkeypatch):
+ """A three-folder umbrella repo in an HF cache that is the only one any lookup can see."""
+ from hub.services.models import cache_inventory, deletion
+ from hub.utils import hf_cache_state, state_dir
+ from utils import hf_cache_settings
+
+ hf_home = tmp_path / "hf"
+ root = hf_home / "hub"
+ root.mkdir(parents = True)
+ paths = hf_cache_settings.HuggingFaceCachePaths(hf_home, root, hf_home / "xet", "studio")
+ monkeypatch.setattr(hf_cache_settings, "get_hf_cache_paths", lambda: paths)
+ monkeypatch.setattr(hf_cache_settings, "known_hf_cache_homes", lambda: [hf_home])
+ monkeypatch.setattr(hf_cache_settings, "known_hf_hub_caches", lambda: [root])
+ monkeypatch.setattr(hf_cache_settings, "active_hf_hub_cache", lambda: str(root))
+ monkeypatch.setattr(hf_cache_state, "hf_cache_roots", lambda **_kwargs: [root])
+ monkeypatch.setattr(state_dir, "cache_root", lambda: tmp_path / "studio-cache")
+ monkeypatch.setattr(acm, "_hub_cache", lambda: root)
+ monkeypatch.setattr(audio_cpp_files, "_hub_cache", lambda: root)
+ monkeypatch.setattr(acm, "runtime_spec", lambda family: None)
+ monkeypatch.setattr(acm, "runtime_knows_family", lambda family: None)
+ monkeypatch.setenv("HF_HUB_OFFLINE", "1")
+ monkeypatch.setenv("HF_HUB_CACHE", str(root))
+ monkeypatch.setattr(deletion.account_access, "require_installation_owner", lambda: None)
+ acm.forget()
+ cache_inventory.invalidate_hf_cache_scans()
+ _add_snapshot(root, "a" * 40, FILES, main = True)
+ yield root
+ acm.forget()
+ cache_inventory.invalidate_hf_cache_scans()
+
+
+def _path(repo_id: str, variant: str) -> dict:
+ import routes.models as rm
+ return asyncio.run(
+ rm.get_cached_model_path(repo_id = repo_id, variant = variant, current_subject = "x")
+ )
+
+
+def _left(hub: Path) -> list[str]:
+ repo_dir = hub / ("models--" + AUDIO_CPP_REPO.replace("/", "--"))
+ return sorted(
+ p.relative_to(s).as_posix()
+ for s in (repo_dir / "snapshots").iterdir()
+ for p in s.rglob("*.gguf")
+ )
+
+
+def _idle(
+ monkeypatch,
+ *,
+ active = None,
+ loading = (),
+ stt = None,
+):
+ from core.inference import orchestrator, stt_audiocpp_sidecar
+
+ side = stt_audiocpp_sidecar.AudioCppSttSidecar()
+ if stt:
+ side._loading, side._loading_model = True, stt
+ backend = SimpleNamespace(active_model_name = active, loading_models = set(loading))
+ monkeypatch.setattr(stt_audiocpp_sidecar, "get_audio_cpp_stt_sidecar", lambda: side)
+ monkeypatch.setattr(orchestrator, "peek_inference_backend", lambda: backend)
+
+
+def test_cached_folder_target_scopes_keys_to_the_folder(hub):
+ assert acm.cached_folder_target(QWEN, "Q8_0") == (AUDIO_CPP_REPO, [QWEN_KEY])
+ assert acm.cached_folder_target(QWEN, None) == (AUDIO_CPP_REPO, [QWEN_KEY])
+ assert acm.cached_folder_target(f"{QWEN}:Q8_0") == (AUDIO_CPP_REPO, [QWEN_KEY])
+ assert acm.cached_folder_target(QWEN, "Q4_K_M") == (AUDIO_CPP_REPO, [])
+ assert acm.cached_folder_target(f"{AUDIO_CPP_REPO}/Missing-GGUF", None) == (AUDIO_CPP_REPO, [])
+ assert acm.cached_folder_target(AUDIO_CPP_REPO, "Q8_0") is None
+ assert acm.cached_folder_target("unsloth/Qwen3-0.6B-GGUF", "Q8_0") is None
+
+
[email protected]("variant", ["Q8_0", None])
+def test_deleting_a_folder_row_keeps_every_other_folder(hub, monkeypatch, variant):
+ from hub.services.models import deletion
+
+ _idle(monkeypatch)
+ calls = []
+ real = deletion._delete_cached_model_blocking
+ monkeypatch.setattr(
+ deletion,
+ "_delete_cached_model_blocking",
+ lambda repo_id, v, *a, **k: calls.append((repo_id, v)) or real(repo_id, v, *a, **k),
+ )
+ result = asyncio.run(deletion.delete_cached_model_response(QWEN, variant))
+ assert result["repo_id"] == QWEN
+ assert calls == [(AUDIO_CPP_REPO, QWEN_KEY)]
+ assert _left(hub) == [
+ "Kokoro-82M-GGUF/kokoro-82m-q8_0.gguf",
+ "Qwen3-ASR-0.6B-GGUF/qwen3-asr-0.6b-q8_0.gguf",
+ ]
+
+
+def test_deleting_an_uncached_quant_of_a_folder_changes_nothing(hub, monkeypatch):
+ from hub.services.models import deletion
+
+ _idle(monkeypatch)
+ with pytest.raises(HTTPException) as err:
+ asyncio.run(deletion.delete_cached_model_response(QWEN, "Q4_K_M"))
+ assert err.value.status_code == 404
+ assert len(_left(hub)) == 3
+
+
+def test_a_loaded_folder_blocks_only_its_own_delete(hub, monkeypatch):
+ from hub.services.models import deletion
+
+ _idle(monkeypatch, active = f"{KOKORO}:Q8_0")
+ asyncio.run(deletion.delete_cached_model_response(QWEN, "Q8_0"))
+ assert QWEN_FILE not in _left(hub)
+ with pytest.raises(HTTPException) as err:
+ asyncio.run(deletion.delete_cached_model_response(KOKORO, "Q8_0"))
+ assert err.value.status_code == 400
+ assert "Unload" in err.value.detail
+ assert "Kokoro-82M-GGUF/kokoro-82m-q8_0.gguf" in _left(hub)
+
+
+ "loaded",
+ [
+ {"active": QWEN},
+ {"active": f"{QWEN}:Q8_0"},
+ {"loading": [QWEN]},
+ {"stt": ASR},
+ ],
+)
+def test_folder_guard_matches_the_folder_however_it_was_loaded(monkeypatch, loaded):
+ from hub.services.models import deletion
+
+ _idle(monkeypatch, **loaded)
+ held = loaded.get("stt") or (loaded.get("loading") or [loaded.get("active")])[0]
+ held_row = acm.split_variant_ref(held)[0]
+ other = KOKORO
+ assert deletion._audio_cpp_blocks_delete(held_row) is True
+ assert deletion._audio_cpp_blocks_delete(other) is False
+ # The whole repo is still held while any of its folders is.
+ assert deletion._audio_cpp_blocks_delete(AUDIO_CPP_REPO) is True
+
+
+def test_folder_guard_maps_a_legacy_dictation_key_to_its_folder(monkeypatch):
+ from hub.services.models import deletion
+
+ legacy = acm.legacy_keys()[0]
+ row = acm.parse_identifier(legacy).id
+ _idle(monkeypatch, stt = legacy)
+ assert deletion._audio_cpp_blocks_delete(row) is True
+ assert deletion._audio_cpp_blocks_delete(f"{AUDIO_CPP_REPO}/Not-That-Folder-GGUF") is False
+
+
+def test_delete_impact_of_a_folder_row_counts_only_its_files(hub):
+ from hub.services.models import companion_cleanup
+
+ qwen_bytes = hub / SNAPSHOT / QWEN_FILE
+ size = qwen_bytes.stat().st_size
+ for variant in ("Q8_0", None):
+ impact = asyncio.run(companion_cleanup.delete_impact_response(QWEN, variant))
+ assert impact["repo_id"] == QWEN
+ assert impact["reclaimed_bytes"] == size
+ whole = asyncio.run(companion_cleanup.delete_impact_response(AUDIO_CPP_REPO, None))
+ assert whole["reclaimed_bytes"] > size
+ with pytest.raises(HTTPException) as err:
+ asyncio.run(companion_cleanup.delete_impact_response(QWEN, "Q4_K_M"))
+ assert err.value.status_code == 404
+
+
+def test_cached_path_and_reveal_of_a_folder_row(hub, monkeypatch):
+ import routes.models as rm
+ from utils.paths import path_utils
+
+ snap = hub / SNAPSHOT
+ got = _path(QWEN, "Q8_0")
+ assert Path(got["path"]) == snap / QWEN_FILE
+ got = _path(QWEN, "")
+ assert Path(got["path"]) == snap / "Qwen3-TTS-12Hz-0.6B-Base-GGUF"
+ assert got["is_dir"] is True
+ revealed = []
+ monkeypatch.setattr(rm.account_access, "require_installation_owner", lambda: None)
+ monkeypatch.setattr(path_utils, "reveal_in_file_manager", lambda path: revealed.append(path))
+ asyncio.run(rm.reveal_cached_model(repo_id = QWEN, variant = None, current_subject = "x"))
+ assert revealed == [snap / "Qwen3-TTS-12Hz-0.6B-Base-GGUF"]
+ with pytest.raises(HTTPException) as err:
+ _path(QWEN, "Q4_K_M")
+ assert err.value.status_code == 404
+ with pytest.raises(HTTPException) as err:
+ _path("a/b/c", "")
+ assert err.value.status_code == 400
+
+
+def test_cached_path_of_a_folder_only_in_an_older_snapshot(hub):
+ kokoro_q4 = {"Kokoro-82M-GGUF/kokoro-82m-q4_0.gguf": "kokoro_tts"}
+ newer = _add_snapshot(hub, "b" * 40, kokoro_q4, main = True)
+ older = hub / SNAPSHOT
+ acm.forget()
+ got = _path(QWEN, "")
+ assert Path(got["path"]) == older / "Qwen3-TTS-12Hz-0.6B-Base-GGUF"
+ assert Path(got["path"]).parent != newer
+
+
+def test_cached_gguf_lists_each_umbrella_folder_beside_the_repo_row(hub):
+ from hub.schemas.inventory import CachedGgufResponse
+ from hub.services.models import cache_inventory
+
+ aligner = "Qwen3-ForcedAligner-0.6B-GGUF/qwen3-forced-aligner-0.6b-q8_0.gguf"
+ _add_snapshot(hub, "a" * 40, {aligner: "qwen3_forced_aligner"}, main = True)
+ rows = {row["repo_id"]: row for row in cache_inventory._scan_cached_gguf()}
+ # A companion with no Audio page of its own is managed through the repo row only.
+ assert f"{AUDIO_CPP_REPO}/Qwen3-ForcedAligner-0.6B-GGUF" not in rows
+ assert AUDIO_CPP_REPO in rows
+ assert not rows[AUDIO_CPP_REPO].get("umbrella_folder")
+ assert {QWEN, KOKORO, ASR} <= set(rows)
+ qwen, kokoro, asr = rows[QWEN], rows[KOKORO], rows[ASR]
+ assert qwen["umbrella_folder"] is True
+ assert qwen["load_id"] == QWEN
+ assert qwen["task"] == "text-to-speech"
+ assert qwen["audio_type"] == "audiocpp_tts"
+ assert qwen["audio_workflows"] == ["clone"]
+ assert kokoro["audio_workflows"] == ["speak"]
+ assert asr["task"] == "automatic-speech-recognition"
+ assert qwen["capabilities"]["can_chat"] is False
+ assert qwen["inventory_id"] != rows[AUDIO_CPP_REPO]["inventory_id"]
+ qwen_size = (hub / SNAPSHOT / QWEN_FILE).stat().st_size
+ assert qwen["size_bytes"] == qwen_size
+ folders = sum(rows[r]["size_bytes"] for r in (QWEN, KOKORO, ASR))
+ assert folders <= rows[AUDIO_CPP_REPO]["size_bytes"]
+ dumped = CachedGgufResponse(cached = list(rows.values())).model_dump()
+ flags = {row["repo_id"]: row["umbrella_folder"] for row in dumped["cached"]}
+ assert flags[QWEN] is True and flags[AUDIO_CPP_REPO] is False
+
+
[email protected]("local_path", [None, QWEN, "cache"])
+def test_variants_of_a_folder_row_list_whatever_local_path_the_picker_sends(hub, local_path):
+ from hub.services.models import gguf_variants
+
+ if local_path == "cache":
+ local_path = str(hub / "models--audio-cpp--audio.cpp-gguf")
+ answer = asyncio.run(
+ gguf_variants.get_gguf_variants_answer(QWEN, offline = True, local_path = local_path)
+ )
+ assert [(v.quant, v.downloaded) for v in answer.response.variants] == [("Q8_0", True)]
+
+
+def test_a_multi_size_folder_matches_the_hub_key_against_its_one_cached_size(hub):
+ moon = f"{AUDIO_CPP_REPO}/Moonshine-Streaming-GGUF"
+ key = "Moonshine-Streaming-GGUF/moonshine-streaming-tiny-q8_0"
+ _add_snapshot(hub, "a" * 40, {f"{key}.gguf": "moonshine_asr"}, main = True)
+ acm.forget()
+ # The picker names the quant from the Hub listing; the cache holds only the tiny size.
+ assert acm.cached_folder_target(moon, "tiny/Q8_0") == (AUDIO_CPP_REPO, [key])
+ assert acm.cached_folder_target(moon, "Q8_0") == (AUDIO_CPP_REPO, [key])
+ assert acm.cached_folder_target(moon, "small/Q8_0") == (AUDIO_CPP_REPO, [])
+ assert acm.cached_folder_target(f"{moon}/tiny", None) == (AUDIO_CPP_REPO, [key])
+
+
+def test_a_loaded_model_holds_the_folder_it_loads_as_a_companion(monkeypatch):
+ from hub.services.models import deletion
+
+ codec = acm.FAMILIES["miotts"].companions[0].id
+ miotts = f"{AUDIO_CPP_REPO}/MioTTS-1.7B-GGUF"
+ monkeypatch.setattr(
+ acm,
+ "resolve",
+ lambda identifier, *a, **k: SimpleNamespace(companions = acm.FAMILIES["miotts"].companions)
+ if identifier.startswith(miotts)
+ else None,
+ )
+ _idle(monkeypatch, active = f"{miotts}:Q8_0")
+ assert deletion._audio_cpp_blocks_delete(codec) is True
+ assert deletion._audio_cpp_blocks_delete(KOKORO) is False
+
+
+def test_a_finished_download_lists_its_folder_on_the_next_scan(hub):
+ from hub.services.models import cache_inventory
+
+ moon = f"{AUDIO_CPP_REPO}/Moonshine-Streaming-GGUF"
+ assert moon not in {row["repo_id"] for row in cache_inventory._scan_cached_gguf()}
+ key = "Moonshine-Streaming-GGUF/moonshine-streaming-tiny-q8_0"
+ _add_snapshot(hub, "a" * 40, {f"{key}.gguf": "moonshine_asr"}, main = True)
+ cache_inventory.invalidate_hf_cache_scans()
+ assert moon in {row["repo_id"] for row in cache_inventory._scan_cached_gguf()}
+
+
+def test_a_folder_variant_delete_takes_its_own_voice_files(hub, monkeypatch):
+ from hub.services.models import companion_cleanup, deletion
+
+ _idle(monkeypatch)
+ snap = hub / SNAPSHOT
+ blobs = hub / "models--audio-cpp--audio.cpp-gguf" / "blobs"
+ pocket = f"{AUDIO_CPP_REPO}/PocketTTS-GGUF"
+ for lang in ("english", "french"):
+ rel = f"PocketTTS-GGUF/{lang}/pocket-tts-{lang}-q8_0.gguf"
+ _add_snapshot(hub, "a" * 40, {rel: "pocket_tts"}, main = True)
+ voice = blobs / f"voice-{lang}"
+ voice.write_bytes(lang.encode() * 100)
+ path = snap / f"PocketTTS-GGUF/{lang}/embeddings/alba.safetensors"
+ path.parent.mkdir(parents = True, exist_ok = True)
+ os.symlink(os.path.relpath(voice, path.parent), path)
+ acm.forget()
+ english = snap / "PocketTTS-GGUF/english"
+ gguf = (english / "pocket-tts-english-q8_0.gguf").stat().st_size
+ voice = (english / "embeddings/alba.safetensors").stat().st_size
+ impact = asyncio.run(companion_cleanup.delete_impact_response(pocket, "english/Q8_0"))
+ assert impact["reclaimed_bytes"] == gguf + voice
+ asyncio.run(deletion.delete_cached_model_response(pocket, "english/Q8_0"))
+ assert not (english / "pocket-tts-english-q8_0.gguf").exists()
+ assert not (english / "embeddings/alba.safetensors").exists()
+ assert not (blobs / "voice-english").exists()
+ assert (snap / "PocketTTS-GGUF/french/embeddings/alba.safetensors").exists()
+ assert (snap / "PocketTTS-GGUF/french/pocket-tts-french-q8_0.gguf").exists()
+ assert len(_left(hub)) == 4
+
+
+def test_a_folder_delete_preview_counts_extras_its_variants_share(hub, monkeypatch):
+ from hub.services.models import companion_cleanup, deletion
+
+ _idle(monkeypatch)
+ snap = hub / SNAPSHOT
+ blobs = hub / "models--audio-cpp--audio.cpp-gguf" / "blobs"
+ pocket = f"{AUDIO_CPP_REPO}/PocketTTS-GGUF"
+ for quant in ("q8_0", "f16"):
+ rel = f"PocketTTS-GGUF/english/pocket-tts-english-{quant}.gguf"
+ _add_snapshot(hub, "a" * 40, {rel: "pocket_tts"}, main = True)
+ voice = blobs / "voice-english"
+ voice.write_bytes(b"v" * 900)
+ path = snap / "PocketTTS-GGUF/english/embeddings/alba.safetensors"
+ path.parent.mkdir(parents = True, exist_ok = True)
+ os.symlink(os.path.relpath(voice, path.parent), path)
+ acm.forget()
+ ggufs = sum(p.stat().st_size for p in (snap / "PocketTTS-GGUF/english").glob("*.gguf"))
+ impact = asyncio.run(companion_cleanup.delete_impact_response(pocket, None))
+ assert impact["reclaimed_bytes"] == ggufs + 900
+ asyncio.run(deletion.delete_cached_model_response(pocket, None))
+ assert not path.exists() and not voice.exists()
+ assert len(_left(hub)) == 3
+
+
+ "peer, kept",
+ [
+ # english BF16 is downloading: its voices landed first, its GGUF is not listed yet.
+ ("PocketTTS-GGUF/english/pocket-tts-english-bf16", True),
+ ("Kokoro-82M-GGUF/kokoro-82m-q4_0", False),
+ ],
+)
+def test_a_variant_delete_keeps_voice_files_only_a_downloading_sibling_needs(
+ hub, monkeypatch, peer, kept
+):
+ from hub.services.models import companion_cleanup, deletion
+ from hub.utils import download_registry
+
+ _idle(monkeypatch)
+ registry = download_registry.DownloadRegistry()
+ registry.claim(
+ f"{AUDIO_CPP_REPO}::{peer}",
+ download_registry.TRANSPORT_HTTP,
+ repo_type = "model",
+ repo_id = AUDIO_CPP_REPO,
+ variant = peer,
+ blob_hashes = frozenset({"peer"}),
+ progress_blob_hashes = frozenset({"peer"}),
+ )
+ monkeypatch.setattr(deletion.downloads, "registry", registry)
+ snap = hub / SNAPSHOT
+ blobs = hub / "models--audio-cpp--audio.cpp-gguf" / "blobs"
+ pocket = f"{AUDIO_CPP_REPO}/PocketTTS-GGUF"
+ rel = "PocketTTS-GGUF/english/pocket-tts-english-q8_0.gguf"
+ _add_snapshot(hub, "a" * 40, {rel: "pocket_tts"}, main = True)
+ voice = blobs / "voice-english"
+ voice.write_bytes(b"v" * 900)
+ path = snap / "PocketTTS-GGUF/english/embeddings/alba.safetensors"
+ path.parent.mkdir(parents = True, exist_ok = True)
+ os.symlink(os.path.relpath(voice, path.parent), path)
+ acm.forget()
+ gguf = (snap / rel).stat().st_size
+ impact = asyncio.run(companion_cleanup.delete_impact_response(pocket, "english/Q8_0"))
+ assert impact["reclaimed_bytes"] == gguf + (0 if kept else 900)
+ asyncio.run(deletion.delete_cached_model_response(pocket, "english/Q8_0"))
+ assert not (snap / rel).exists()
+ assert path.exists() is kept and voice.exists() is kept
+
+
[email protected]("folder", ["C:", "C:Qwen3-TTS-GGUF"])
+def test_a_drive_like_folder_id_names_nothing(hub, monkeypatch, folder):
+ from hub.services.models import companion_cleanup, deletion
+
+ _idle(monkeypatch)
+ row = f"{AUDIO_CPP_REPO}/{folder}"
+ assert acm.cached_folder_target(row, None) == (AUDIO_CPP_REPO, [])
+ assert acm.folder_snapshot_dir(row) is None
+ for call in (
+ lambda: _path(row, ""),
+ lambda: asyncio.run(deletion.delete_cached_model_response(row, None)),
+ lambda: asyncio.run(companion_cleanup.delete_impact_response(row, None)),
+ ):
+ with pytest.raises(HTTPException) as err:
+ call()
+ assert err.value.status_code == 404
+ assert len(_left(hub)) == 3
+
+
+def test_a_bare_quant_two_cached_sizes_share_names_nothing(hub, monkeypatch):
+ from hub.services.models import deletion
+
+ _idle(monkeypatch)
+ moon = f"{AUDIO_CPP_REPO}/Moonshine-Streaming-GGUF"
+ tiny = "Moonshine-Streaming-GGUF/moonshine-streaming-tiny-q8_0"
+ small = "Moonshine-Streaming-GGUF/moonshine-streaming-small-q8_0"
+ files = {f"{tiny}.gguf": "moonshine_asr", f"{small}.gguf": "moonshine_asr"}
+ _add_snapshot(hub, "a" * 40, files, main = True)
+ acm.forget()
+ assert acm.cached_folder_target(moon, "Q8_0") == (AUDIO_CPP_REPO, [])
+ assert acm.cached_folder_target(moon, "tiny/Q8_0") == (AUDIO_CPP_REPO, [tiny])
+ assert acm.cached_folder_target(moon, "small/Q8_0") == (AUDIO_CPP_REPO, [small])
+ assert sorted(acm.cached_folder_target(moon, None)[1]) == sorted([small, tiny])
+ with pytest.raises(HTTPException) as err:
+ asyncio.run(deletion.delete_cached_model_response(moon, "Q8_0"))
+ assert err.value.status_code == 404
+ assert len(_left(hub)) == 5
+
+
+def test_a_folder_delete_reserves_every_variant_before_removing_any(hub, monkeypatch):
+ from hub.services.models import deletion
+ from hub.utils import download_registry
+
+ _idle(monkeypatch)
+ moon = f"{AUDIO_CPP_REPO}/Moonshine-Streaming-GGUF"
+ tiny = "Moonshine-Streaming-GGUF/moonshine-streaming-tiny-q8_0"
+ small = "Moonshine-Streaming-GGUF/moonshine-streaming-small-q8_0"
+ files = {f"{tiny}.gguf": "moonshine_asr", f"{small}.gguf": "moonshine_asr"}
+ _add_snapshot(hub, "a" * 40, files, main = True)
+ acm.forget()
+ registry = download_registry.DownloadRegistry()
+ monkeypatch.setattr(deletion.downloads, "registry", registry)
+ keys = acm.cached_folder_target(moon, None)[1]
+ assert sorted(keys) == sorted([tiny, small])
+ later = keys[-1]
+ # A re-download of the folder's second variant is running.
+ registry.claim(
+ f"{AUDIO_CPP_REPO}::{later.lower()}",
+ download_registry.TRANSPORT_HTTP,
+ repo_type = "model",
+ repo_id = AUDIO_CPP_REPO,
+ variant = later,
+ blob_hashes = frozenset({"later"}),
+ progress_blob_hashes = frozenset({"later"}),
+ )
+ with pytest.raises(HTTPException) as err:
+ asyncio.run(deletion.delete_cached_model_response(moon, None))
+ assert err.value.status_code == 400
+ assert len(_left(hub)) == 5
+ assert not registry._deleting
+
+
[email protected]("variant", ["/", "//", " / "])
+def test_an_empty_variant_path_names_no_folder_variant(hub, monkeypatch, variant):
+ from hub.services.models import deletion
+
+ _idle(monkeypatch)
+ assert acm.cached_folder_target(QWEN, variant) == (AUDIO_CPP_REPO, [])
+ with pytest.raises(HTTPException) as err:
+ asyncio.run(deletion.delete_cached_model_response(QWEN, variant))
+ assert err.value.status_code == 404
+ assert len(_left(hub)) == 3
+
+
+ "variant, picks",
+ [
+ (".", []),
+ ("./", []),
+ ("Moonshine-Streaming-GGUF", []),
+ ("gguf", []),
+ ("-", []),
+ ("q8_0.gguf", []),
+ ("TINY/Q8_0", ["tiny"]),
+ ("tiny/Q8_0/", ["tiny"]),
+ ("moonshine-streaming-small-q8_0", ["small"]),
+ ("moonshine-streaming-small-q8_0.gguf", ["small"]),
+ ("tiny", ["tiny"]),
+ ],
+)
+def test_a_folder_variant_names_only_what_it_says(hub, variant, picks):
+ moon = f"{AUDIO_CPP_REPO}/Moonshine-Streaming-GGUF"
+ keys = {
+ size: f"Moonshine-Streaming-GGUF/moonshine-streaming-{size}-q8_0"
+ for size in ("tiny", "small")
+ }
+ _add_snapshot(hub, "a" * 40, {f"{k}.gguf": "moonshine_asr" for k in keys.values()}, main = True)
+ acm.forget()
+ assert acm.cached_folder_target(moon, variant) == (AUDIO_CPP_REPO, [keys[p] for p in picks])
+
+
+def test_cached_path_of_a_folder_skips_a_newer_snapshot_with_only_metadata(hub):
+ newer = _add_snapshot(hub, "c" * 40, {}, main = True)
+ (newer / "Qwen3-TTS-12Hz-0.6B-Base-GGUF").mkdir(parents = True)
+ (newer / "Qwen3-TTS-12Hz-0.6B-Base-GGUF" / "README.md").write_text("card")
+ acm.forget()
+ got = _path(QWEN, "")
+ assert Path(got["path"]) == hub / SNAPSHOT / "Qwen3-TTS-12Hz-0.6B-Base-GGUF"
+
+
+def test_cached_path_of_a_folder_finds_weights_with_an_uppercase_extension(hub):
+ older = _add_snapshot(hub, "0" * 40, {}, main = False)
+ (older / "Upper-GGUF").mkdir(parents = True)
+ (older / "Upper-GGUF" / "MODEL-Q8_0.GGUF").write_bytes(b"GGUF")
+ newer = hub / SNAPSHOT
+ (newer / "Upper-GGUF").mkdir()
+ (newer / "Upper-GGUF" / "README.md").write_text("card")
+ assert acm.folder_snapshot_dir(f"{AUDIO_CPP_REPO}/Upper-GGUF") == older / "Upper-GGUF"
+
+
+def test_a_folder_delete_preview_keeps_shared_extras_a_downloading_sibling_needs(hub, monkeypatch):
+ from hub.services.models import companion_cleanup, deletion
+ from hub.utils import download_registry
+
+ _idle(monkeypatch)
+ snap = hub / SNAPSHOT
+ blobs = hub / "models--audio-cpp--audio.cpp-gguf" / "blobs"
+ pocket = f"{AUDIO_CPP_REPO}/PocketTTS-GGUF"
+ for quant in ("q8_0", "f16"):
+ rel = f"PocketTTS-GGUF/english/pocket-tts-english-{quant}.gguf"
+ _add_snapshot(hub, "a" * 40, {rel: "pocket_tts"}, main = True)
+ voice = blobs / "voice-english"
+ voice.write_bytes(b"v" * 900)
+ path = snap / "PocketTTS-GGUF/english/embeddings/alba.safetensors"
+ path.parent.mkdir(parents = True, exist_ok = True)
+ os.symlink(os.path.relpath(voice, path.parent), path)
+ acm.forget()
+ registry = download_registry.DownloadRegistry()
+ peer = "PocketTTS-GGUF/english/pocket-tts-english-bf16"
+ registry.claim(
+ f"{AUDIO_CPP_REPO}::{peer}",
+ download_registry.TRANSPORT_HTTP,
+ repo_type = "model",
+ repo_id = AUDIO_CPP_REPO,
+ variant = peer,
+ blob_hashes = frozenset({"peer"}),
+ progress_blob_hashes = frozenset({"peer"}),
+ )
+ monkeypatch.setattr(deletion.downloads, "registry", registry)
+ ggufs = sum(p.stat().st_size for p in (snap / "PocketTTS-GGUF/english").glob("*.gguf"))
+ impact = asyncio.run(companion_cleanup.delete_impact_response(pocket, None))
+ assert impact["reclaimed_bytes"] == ggufs
+ asyncio.run(deletion.delete_cached_model_response(pocket, None))
+ assert path.exists() and voice.exists()
+
+
+def test_a_folder_delete_preview_keeps_only_the_busy_directory_s_extras(hub, monkeypatch):
+ from hub.services.models import companion_cleanup, deletion
+ from hub.utils import download_registry
+
+ _idle(monkeypatch)
+ snap = hub / SNAPSHOT
+ blobs = hub / "models--audio-cpp--audio.cpp-gguf" / "blobs"
+ pocket = f"{AUDIO_CPP_REPO}/PocketTTS-GGUF"
+ voices = {}
+ for lang in ("english", "french"):
+ for quant in ("q8_0", "f16"):
+ rel = f"PocketTTS-GGUF/{lang}/pocket-tts-{lang}-{quant}.gguf"
+ _add_snapshot(hub, "a" * 40, {rel: "pocket_tts"}, main = True)
+ voices[lang] = blobs / f"voice-{lang}"
+ voices[lang].write_bytes(lang[:1].encode() * 900)
+ path = snap / f"PocketTTS-GGUF/{lang}/embeddings/alba.safetensors"
+ path.parent.mkdir(parents = True, exist_ok = True)
+ os.symlink(os.path.relpath(voices[lang], path.parent), path)
+ acm.forget()
+ registry = download_registry.DownloadRegistry()
+ peer = "PocketTTS-GGUF/english/pocket-tts-english-bf16"
+ registry.claim(
+ f"{AUDIO_CPP_REPO}::{peer}",
+ download_registry.TRANSPORT_HTTP,
+ repo_type = "model",
+ repo_id = AUDIO_CPP_REPO,
+ variant = peer,
+ blob_hashes = frozenset({"peer"}),
+ progress_blob_hashes = frozenset({"peer"}),
+ )
+ monkeypatch.setattr(deletion.downloads, "registry", registry)
+ ggufs = sum(p.stat().st_size for p in (snap / "PocketTTS-GGUF").rglob("*.gguf"))
+ impact = asyncio.run(companion_cleanup.delete_impact_response(pocket, None))
+ assert impact["reclaimed_bytes"] == ggufs + 900
+ asyncio.run(deletion.delete_cached_model_response(pocket, None))
+ assert voices["english"].exists() and not voices["french"].exists()
+
+
+def test_a_listing_read_before_a_download_finished_is_not_memoized(hub, monkeypatch):
+ real = acm._scan_downloaded
+ calls = []
+
+ def scan(task):
+ found = real(task)
+ calls.append(task)
+ if len(calls) == 1:
+ acm.forget()
+ return found
+
+ monkeypatch.setattr(acm, "_scan_downloaded", scan)
+ acm.forget()
+ acm.downloaded_models()
+ acm.downloaded_models()
+ assert len(calls) == 2
+ acm.downloaded_models()
+ assert len(calls) == 2
+
+
+def _partial(hub, monkeypatch, tmp_path, keys):
+ """Download state only (cancel marker and manifest) for planner keys of the umbrella repo."""
+ from hub.utils import download_manifest
+ for key in keys:
+ assert download_manifest.write_cancel_marker("model", AUDIO_CPP_REPO, key, hub_cache = hub)
+ download_manifest.write_manifest("model", AUDIO_CPP_REPO, key, [], hub_cache = hub)
+
+
+def _states(hub):
+ from hub.utils import download_manifest
+ return sorted(
+ {
+ key
+ for listing in (
+ download_manifest.iter_variant_manifests("model", AUDIO_CPP_REPO, hub_cache = hub),
+ download_manifest.iter_variant_markers("model", AUDIO_CPP_REPO, hub_cache = hub),
+ )
+ for key, _ in listing
+ }
+ )
+
+
+QWEN_F16 = "Qwen3-TTS-12Hz-0.6B-Base-GGUF/qwen3-tts-12hz-0.6b-base-f16"
+KOKORO_Q4 = "Kokoro-82M-GGUF/kokoro-82m-q4_0"
+
+
+def test_a_folder_delete_also_clears_a_partial_only_sibling(hub, monkeypatch, tmp_path):
+ from hub.services.models import deletion
+
+ _idle(monkeypatch)
+ _partial(hub, monkeypatch, tmp_path, [QWEN_F16, KOKORO_Q4])
+ assert acm.cached_folder_target(QWEN, None) == (AUDIO_CPP_REPO, [QWEN_KEY, QWEN_F16])
+ asyncio.run(deletion.delete_cached_model_response(QWEN, None))
+ assert QWEN_FILE not in _left(hub)
+ assert _states(hub) == [KOKORO_Q4]
+ assert len(_left(hub)) == 2
+
+
+def test_deleting_a_partial_only_quant_of_a_folder_clears_its_state(hub, monkeypatch, tmp_path):
+ from hub.services.models import deletion
+
+ _idle(monkeypatch)
+ _partial(hub, monkeypatch, tmp_path, [QWEN_F16, KOKORO_Q4])
+ assert acm.cached_folder_target(QWEN, "F16") == (AUDIO_CPP_REPO, [QWEN_F16])
+ assert acm.cached_folder_target(QWEN, "Q4_0") == (AUDIO_CPP_REPO, [])
+ asyncio.run(deletion.delete_cached_model_response(QWEN, "F16"))
+ assert _states(hub) == [KOKORO_Q4]
+ assert len(_left(hub)) == 3
+
+
+def test_an_ambiguous_bare_quant_never_falls_back_to_download_state(hub, monkeypatch, tmp_path):
+ moon = f"{AUDIO_CPP_REPO}/Moonshine-Streaming-GGUF"
+ files = {
+ f"Moonshine-Streaming-GGUF/moonshine-streaming-{size}-q8_0.gguf": "moonshine_asr"
+ for size in ("tiny", "small")
+ }
+ _add_snapshot(hub, "a" * 40, files, main = True)
+ medium = "Moonshine-Streaming-GGUF/moonshine-streaming-medium-q8_0"
+ _partial(hub, monkeypatch, tmp_path, [medium])
+ acm.forget()
+ assert acm.cached_folder_target(moon, "Q8_0") == (AUDIO_CPP_REPO, [])
+ assert medium in acm.cached_folder_target(moon, None)[1]
+
+
+def test_a_state_only_size_is_named_even_when_another_size_shares_its_quant(
+ hub, monkeypatch, tmp_path
+):
+ moon = f"{AUDIO_CPP_REPO}/Moonshine-Streaming-GGUF"
+ tiny = "Moonshine-Streaming-GGUF/moonshine-streaming-tiny-q8_0"
+ _add_snapshot(hub, "a" * 40, {f"{tiny}.gguf": "moonshine_asr"}, main = True)
+ medium = "Moonshine-Streaming-GGUF/moonshine-streaming-medium-q8_0"
+ _partial(hub, monkeypatch, tmp_path, [medium])
+ acm.forget()
+ assert acm.cached_folder_target(moon, "medium/Q8_0") == (AUDIO_CPP_REPO, [medium])
+ assert acm.cached_folder_target(moon, "tiny/Q8_0") == (AUDIO_CPP_REPO, [tiny])
+ # One size on disk: a bare quant still names it, not the cancelled one.
+ assert acm.cached_folder_target(moon, "Q8_0") == (AUDIO_CPP_REPO, [tiny])
+
+
+def test_cached_path_of_a_folder_skips_a_newer_snapshot_with_only_an_adapter(hub):
+ newer = _add_snapshot(hub, "c" * 40, {}, main = True)
+ (newer / "Qwen3-TTS-12Hz-0.6B-Base-GGUF").mkdir(parents = True)
+ (newer / "Qwen3-TTS-12Hz-0.6B-Base-GGUF" / "mmproj-f16.gguf").write_bytes(b"GGUF")
+ acm.forget()
+ assert _path(QWEN, "")["path"] == str(hub / SNAPSHOT / "Qwen3-TTS-12Hz-0.6B-Base-GGUF")
+
+
+def test_a_file_name_two_directories_share_names_neither(hub):
+ variants = [
+ acm.AudioCppVariant(f"{size}/Q8_0", (), f"Moon-GGUF/{size}/model-Q8_0.gguf")
+ for size in ("tiny", "small")
+ ]
+ assert acm._cached_variants_named(variants, "model-Q8_0.gguf", "Moon-GGUF") == []
+ assert acm._cached_variants_named(variants, "tiny/model-Q8_0.gguf", "Moon-GGUF") == [
+ variants[0]
+ ]
+ assert acm._cached_variants_named(variants, "small/Q8_0", "Moon-GGUF") == [variants[1]]
+
+
+def test_a_compound_scope_names_the_one_cached_size(hub):
+ # Irodori-TTS-v4-Small-GGUF: the Hub keys `v4-small/Q8_0` and `v4.1-anime/Q8_0`, every part of
+ # `v4-small` is also a folder word, and a cache holding one size keys it bare `Q8_0`.
+ folder = "Irodori-TTS-v4-Small-GGUF"
+ small = acm.AudioCppVariant("Q8_0", (), f"{folder}/irodori-tts-v4-small-q8_0.gguf")
+ anime = acm.AudioCppVariant("Q8_0", (), f"{folder}/irodori-tts-v4.1-anime-q8_0.gguf")
+ assert acm._cached_variants_named([small], "v4-small/Q8_0", folder) == [small]
+ assert acm._cached_variants_named([small], "v4.1-anime/Q8_0", folder) == []
+ assert acm._cached_variants_named([anime], "v4.1-anime/Q8_0", folder) == [anime]
+ assert acm._cached_variants_named([anime], "v4-small/Q8_0", folder) == []
+ assert acm._state_key_named(f"{folder}/irodori-tts-v4-small-q8_0", "v4-small/Q8_0", folder)
+ assert not acm._state_key_named(
+ f"{folder}/irodori-tts-v4.1-anime-q8_0", "v4-small/Q8_0", folder
+ )
+
+
+def test_cached_path_of_a_folder_skips_a_newer_snapshot_missing_voice_files(hub):
+ blobs = hub / "models--audio-cpp--audio.cpp-gguf" / "blobs"
+ rel = "PocketTTS-GGUF/english/pocket-tts-english-q8_0.gguf"
+ older = _add_snapshot(hub, "0" * 40, {rel: "pocket_tts"}, main = False)
+ voice = blobs / "voice-english"
+ voice.write_bytes(b"v" * 900)
+ path = older / "PocketTTS-GGUF/english/embeddings/alba.safetensors"
+ path.parent.mkdir(parents = True, exist_ok = True)
+ os.symlink(os.path.relpath(voice, path.parent), path)
+ # refs/main's snapshot got the GGUF again but not its voices.
+ _add_snapshot(hub, "a" * 40, {rel: "pocket_tts"}, main = True)
+ acm.forget()
+ assert acm.folder_snapshot_dir(f"{AUDIO_CPP_REPO}/PocketTTS-GGUF") == older / "PocketTTS-GGUF"
diff --git a/studio/frontend/src/features/audio/audio-cpp-catalog.ts b/studio/frontend/src/features/audio/audio-cpp-catalog.ts
index 02f4d9974e9..07ffd2253ee 100644
--- a/studio/frontend/src/features/audio/audio-cpp-catalog.ts
+++ b/studio/frontend/src/features/audio/audio-cpp-catalog.ts
@@ -333,6 +333,14 @@ export function audioCppDisplayName(id: string): string {
return trimmed.split("/").pop() || trimmed;
}
+/** Hub path of an umbrella folder (`<repo>/tree/main/<Folder>`); null for any other id. */
+export function audioCppHubPath(id: string): string | null {
+ if (!isAudioCppFolderId(id)) {
+ return null;
+ }
+ return `${AUDIO_CPP_REPO}/tree/main/${audioCppDisplayName(id)}`;
+}
+
export function audioCppModelFor(id: string | null | undefined): AudioCppModel | null {
return BY_ID.get(normalizedId(id)) ?? null;
}
diff --git a/studio/frontend/src/features/audio/audio-page.tsx b/studio/frontend/src/features/audio/audio-page.tsx
index c3cb8ca7193..e950f0ddf72 100644
--- a/studio/frontend/src/features/audio/audio-page.tsx
+++ b/studio/frontend/src/features/audio/audio-page.tsx
@@ -16,6 +16,7 @@ import { buildAudioTourSteps } from "./tour";
import { useSidebar } from "@/components/ui/sidebar";
import { usePlatformStore } from "@/config/env";
import { type InferenceStatusResponse, getInferenceStatus } from "@/features/chat";
+import { useInventoryVersion } from "@/features/hub/stores/inventory-events";
import { ModelSelector } from "@/features/model-picker/components/model-selector";
import { AUDIO_CATALOG } from "@/features/model-picker/components/model-selector/model-catalog";
import { PillTabs } from "@/features/model-picker/components/model-selector/pill-tabs";
@@ -463,6 +464,15 @@ export function AudioPage({
});
}, [active, refreshStatus, refreshSttStatus]);
+ // Transcribe lists On Device from the STT status, not the picker inventory: refresh it on cache changes.
+ const inventoryVersion = useInventoryVersion();
+ const seenInventoryVersion = useRef(inventoryVersion);
+ useEffect(() => {
+ if (!active || seenInventoryVersion.current === inventoryVersion) return;
+ seenInventoryVersion.current = inventoryVersion;
+ void refreshSttStatus();
+ }, [active, inventoryVersion, refreshSttStatus]);
+
const {
replayQueuedTtsPick,
transitionMode,
diff --git a/studio/frontend/src/features/chat/api/chat-api.ts b/studio/frontend/src/features/chat/api/chat-api.ts
index 1974e649e1d..ab03bbd1236 100644
--- a/studio/frontend/src/features/chat/api/chat-api.ts
+++ b/studio/frontend/src/features/chat/api/chat-api.ts
@@ -642,6 +642,7 @@ export interface CachedGgufRepo {
task?: string | null;
audio_type?: string | null;
audio_workflows?: string[] | null;
+ umbrella_folder?: boolean;
/** True when some quant has a download manifest or cancel marker. Optional for older-backend compatibility. */
has_variant_state?: boolean;
partial?: boolean;
diff --git a/studio/frontend/src/features/hub/inventory/api.ts b/studio/frontend/src/features/hub/inventory/api.ts
index a52eb0af033..0af84bef5ae 100644
--- a/studio/frontend/src/features/hub/inventory/api.ts
+++ b/studio/frontend/src/features/hub/inventory/api.ts
@@ -62,6 +62,8 @@ export interface CachedGgufRepo {
pipeline_tag?: string | null;
task?: string | null;
audio_type?: string | null;
+ audio_workflows?: string[] | null;
+ umbrella_folder?: boolean;
tags?: string[];
library_name?: string | null;
}
diff --git a/studio/frontend/src/features/hub/inventory/types.ts b/studio/frontend/src/features/hub/inventory/types.ts
index fbd05146109..1c95a28e894 100644
--- a/studio/frontend/src/features/hub/inventory/types.ts
+++ b/studio/frontend/src/features/hub/inventory/types.ts
@@ -56,6 +56,8 @@ export interface CachedInventoryRow {
// Inferred pipeline task from the backend. The task-scoped pickers filter On Device rows on it.
task?: string | null;
audioType?: string | null;
+ audioWorkflows?: string[] | null;
+ umbrellaFolder?: boolean;
// Diffusion repo with no pipeline index: loadable only via from_single_file + a filename, so the task pickers must not offer it as a pipeline load.
singleFile?: boolean;
// sd.cpp companion mirror: VAE / text encoders with no denoiser. Still listed, because these
diff --git a/studio/frontend/src/features/hub/inventory/use-hub-inventory.ts b/studio/frontend/src/features/hub/inventory/use-hub-inventory.ts
index 8b5f254f6c3..9793f18765e 100644
--- a/studio/frontend/src/features/hub/inventory/use-hub-inventory.ts
+++ b/studio/frontend/src/features/hub/inventory/use-hub-inventory.ts
@@ -45,6 +45,7 @@ import {
buildLocalInventoryRows,
cachedInventoryId,
defaultCapabilities,
+ withUmbrellaFolderRows,
} from "./view-models";
import { normalizeTimestamp } from "./inventory-timestamps";
import {
@@ -72,6 +73,7 @@ type HubInventoryOptions = {
kind?: HubInventoryKind;
enabled?: boolean;
includeLocal?: boolean;
+ includeUmbrellaFolders?: boolean;
};
const MODEL_HUB_CACHE_SOURCES = [
@@ -290,6 +292,7 @@ export function useHubInventory(
const isDatasetMode = (options.kind ?? "models") === "datasets";
const enabled = options.enabled ?? true;
const includeLocal = options.includeLocal ?? true;
+ const includeUmbrellaFolders = options.includeUmbrellaFolders ?? false;
const modelInventory = useDeviceInventorySources(MODEL_HUB_CACHE_SOURCES, {
hfToken,
enabled: enabled && !isDatasetMode,
@@ -501,12 +504,21 @@ export function useHubInventory(
() =>
[
...(isDatasetMode ? [] : liveDownloadRows),
- ...cachedGguf.map((row) => buildCachedInventoryRow(row, "gguf")),
+ ...withUmbrellaFolderRows(
+ cachedGguf.map((row) => buildCachedInventoryRow(row, "gguf")),
+ includeUmbrellaFolders,
+ ),
...cachedModels.map((row) =>
buildCachedInventoryRow(row, "safetensors"),
),
].sort(compareCachedRows),
- [cachedGguf, cachedModels, isDatasetMode, liveDownloadRows],
+ [
+ cachedGguf,
+ cachedModels,
+ includeUmbrellaFolders,
+ isDatasetMode,
+ liveDownloadRows,
+ ],
);
const cachedDatasetRows = useMemo<CachedInventoryRow[]>(
diff --git a/studio/frontend/src/features/hub/inventory/view-models.ts b/studio/frontend/src/features/hub/inventory/view-models.ts
index 76eb93b5f43..ecf0eb58951 100644
--- a/studio/frontend/src/features/hub/inventory/view-models.ts
+++ b/studio/frontend/src/features/hub/inventory/view-models.ts
@@ -163,6 +163,8 @@ export function buildCachedInventoryRow(
pipeline_tag?: string | null;
task?: string | null;
audio_type?: string | null;
+ audio_workflows?: string[] | null;
+ umbrella_folder?: boolean;
single_file?: boolean;
companion?: boolean;
companion_prefetch?: boolean;
@@ -223,6 +225,8 @@ export function buildCachedInventoryRow(
pipelineTag: row.pipeline_tag ?? null,
task: row.task ?? null,
audioType: row.audio_type ?? null,
+ audioWorkflows: row.audio_workflows ?? null,
+ umbrellaFolder: row.umbrella_folder === true,
singleFile: row.single_file ?? false,
companion: row.companion ?? false,
companionPrefetch: row.companion_prefetch ?? false,
@@ -233,6 +237,14 @@ export function buildCachedInventoryRow(
};
}
+/** Folder rows of the audio.cpp umbrella repo belong to the Audio pages; everyone else sees the one umbrella row. */
+export function withUmbrellaFolderRows(
+ rows: CachedInventoryRow[],
+ include: boolean,
+): CachedInventoryRow[] {
+ return include ? rows : rows.filter((row) => !row.umbrellaFolder);
+}
+
function sourceSortWeight(source: LocalModelInfo["source"]): number {
switch (source) {
case "models_dir":
diff --git a/studio/frontend/src/features/hub/lib/model-identity.ts b/studio/frontend/src/features/hub/lib/model-identity.ts
index f94a9223734..91cf9789180 100644
--- a/studio/frontend/src/features/hub/lib/model-identity.ts
+++ b/studio/frontend/src/features/hub/lib/model-identity.ts
@@ -1,6 +1,10 @@
// 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 {
+ AUDIO_CPP_REPO,
+ isAudioCppFolderId,
+} from "../../audio/audio-cpp-catalog.ts";
import { looksLikeLocalPath } from "./local-path.ts";
const WINDOWS_DRIVE_PATH_RE = /^[A-Za-z]:/;
@@ -86,6 +90,18 @@ function looksLikeModelPath(identifier: string): boolean {
if (GGUF_SUFFIX_RE.test(identifier)) {
return true;
}
+ // An audio.cpp umbrella id names a folder of one Hub repo; mirrors model_ids._looks_like_path.
+ if (isAudioCppFolderId(identifier)) {
+ const parts = identifier
+ .trim()
+ .slice(AUDIO_CPP_REPO.length + 1)
+ .replace(BACKSLASHES_RE, "/")
+ .split("/")
+ .filter(Boolean);
+ if (parts.length > 0 && !parts.some((part) => part === "." || part === "..")) {
+ return false;
+ }
+ }
if (PUBLIC_ID_PATH_PREFIX_RE.test(identifier)) {
return true;
}
diff --git a/studio/frontend/src/features/model-picker/components/model-selector/audio-picker-policy.ts b/studio/frontend/src/features/model-picker/components/model-selector/audio-picker-policy.ts
index 6c114b49e3f..6eab91af3d1 100644
--- a/studio/frontend/src/features/model-picker/components/model-selector/audio-picker-policy.ts
+++ b/studio/frontend/src/features/model-picker/components/model-selector/audio-picker-policy.ts
@@ -399,6 +399,17 @@ export function allowedHiddenModelIdMatches(
);
}
+/** An audio.cpp umbrella folder row lists only on a task page that passed its exact id. */
+export function umbrellaFolderRowAllowed(
+ row: { repoId: string; umbrellaFolder?: boolean },
+ allowedHiddenModelIds: ReadonlySet<string> | undefined,
+): boolean {
+ return (
+ !row.umbrellaFolder ||
+ allowedHiddenModelIdMatches(allowedHiddenModelIds, row.repoId)
+ );
+}
+
/** Backend tag for a diffusion GGUF the Images backend cannot assemble; both pickers hide these rows. */
const UNSUPPORTED_DIFFUSION_TASK = "image-diffusion-unsupported";
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 27bb762a6f0..286f7bf3038 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
@@ -160,6 +160,10 @@ import {
useState,
useSyncExternalStore,
} from "react";
+import {
+ audioCppHubPath,
+ isAudioCppFolderId,
+} from "../../../audio/audio-cpp-catalog.ts";
import { audioPickSearch } from "../../../audio/route-search.ts";
import { useChatPickerInventory } from "../../inventory/use-chat-picker-inventory";
import {
@@ -250,7 +254,9 @@ import {
} from "./row-identity";
import {
type FormatTone,
+ isFeaturedOnDeviceRepoId,
isUnslothOwner,
+ onDeviceRepoLabel,
parseMetaTokens,
splitRepoLabel,
} from "./row-meta";
@@ -300,7 +306,7 @@ function isUnslothRepoId(repoId: string): boolean {
/** Official publisher namespaces used only for visual On Device grouping. */
function isUnslothPublisherRepoId(repoId: string): boolean {
- return isUnslothOwner(splitRepoLabel(repoId).owner);
+ return isFeaturedOnDeviceRepoId(repoId);
}
function normalizeForSearch(s: string): string {
@@ -2967,7 +2973,9 @@ function localDirectGgufMeta(
* row shows no empty address line. */
function hubRepoUrl(id: string | null | undefined): string | undefined {
const trimmed = id?.trim();
- return trimmed ? `huggingface.co/${trimmed}` : undefined;
+ return trimmed
+ ? `huggingface.co/${audioCppHubPath(trimmed) ?? trimmed}`
+ : undefined;
}
/** Whether a local model is an MLX build (name hint). MLX runs on Mac only, so callers gate
@@ -6489,7 +6497,7 @@ export function HubModelPicker({
>
<div className="min-w-0 flex-1">
<ModelRow
- label={c.repo_id}
+ label={onDeviceRepoLabel(c.repo_id)}
tooltipText={localPathTooltip(
c.repo_id,
c.cache_path,
@@ -6527,12 +6535,12 @@ export function HubModelPicker({
<span className={ROW_ACTIONS_CLASS}>
{onConfigure && (
<ModelLoadSettingsAction
- ariaLabel={`Inference settings for ${c.repo_id} ${variant.quant}`}
+ ariaLabel={`Inference settings for ${onDeviceRepoLabel(c.repo_id)} ${variant.quant}`}
onConfigure={() => onConfigure(c.repo_id, selectMeta)}
/>
)}
<ModelRowMenu
- ariaLabel={`More options for ${c.repo_id} ${variant.quant}`}
+ ariaLabel={`More options for ${onDeviceRepoLabel(c.repo_id)} ${variant.quant}`}
cachePath={{ repoId: c.repo_id, variant: variant.quant }}
items={ejectMenuItems(c.repo_id)}
pin={{
@@ -6555,12 +6563,12 @@ export function HubModelPicker({
<>
This will remove{" "}
<span className="font-medium text-foreground">
- {c.repo_id} ({variant.quant})
+ {onDeviceRepoLabel(c.repo_id)} ({variant.quant})
</span>{" "}
from disk. You can re-download it later.
</>
),
- successMessage: `Deleted ${c.repo_id} ${variant.quant}`,
+ successMessage: `Deleted ${onDeviceRepoLabel(c.repo_id)} ${variant.quant}`,
disabled: deleteDisabled,
onConfirm: async () => {
await deleteCachedModel(
@@ -6608,7 +6616,7 @@ export function HubModelPicker({
<div className={downloadedRowShellClassName(isSelected)}>
<div className="min-w-0 flex-1">
<ModelRow
- label={c.repo_id}
+ label={onDeviceRepoLabel(c.repo_id)}
tooltipText={localPathTooltip(c.repo_id, c.cache_path)}
meta="GGUF"
quantChip={loadedQuants.map(ggufQuantChipLabel).join(", ") || undefined}
@@ -6645,7 +6653,7 @@ export function HubModelPicker({
{isPartialRepo ? (
<span className={ROW_ACTIONS_PINNED_CLASS}>
<ModelRowMenu
- ariaLabel={`More options for ${c.repo_id}`}
+ ariaLabel={`More options for ${onDeviceRepoLabel(c.repo_id)}`}
cachePath={{ repoId: c.repo_id }}
del={{
title: "Delete cached model?",
@@ -6657,13 +6665,13 @@ export function HubModelPicker({
<>
This will remove{" "}
<span className="font-medium text-foreground">
- {c.repo_id}
+ {onDeviceRepoLabel(c.repo_id)}
</span>{" "}
and everything downloaded under it from disk. You can
download it again later.
</>
),
- successMessage: `Deleted ${c.repo_id}`,
+ successMessage: `Deleted ${onDeviceRepoLabel(c.repo_id)}`,
disabled: deleteDisabled,
onConfirm: async () => {
await deleteCachedModel(
@@ -6886,7 +6894,7 @@ export function HubModelPicker({
<div key={model.id} className={downloadedRowShellClassName(isSelected)}>
<div className="min-w-0 flex-1">
<ModelRow
- label={isLocalPath ? model.name : model.id}
+ label={isLocalPath ? model.name : onDeviceRepoLabel(model.id)}
hubUrl={isLocalPath ? undefined : hubRepoUrl(model.id)}
meta={
isLocalPath
@@ -6916,7 +6924,35 @@ export function HubModelPicker({
className={downloadedRowButtonClassName}
/>
</div>
- <span aria-hidden="true" className={cn(ROW_ACTIONS_CLASS, "h-6")} />
+ {isAudioCppFolderId(model.id) ? (
+ <span className={ROW_ACTIONS_CLASS}>
+ <ModelRowMenu
+ ariaLabel={`More options for ${onDeviceRepoLabel(model.id)}`}
+ cachePath={{ repoId: model.id }}
+ del={{
+ title: "Delete cached model?",
+ impact: { repoId: model.id },
+ description: (
+ <>
+ This will remove{" "}
+ <span className="font-medium text-foreground">
+ {onDeviceRepoLabel(model.id)}
+ </span>{" "}
+ from disk. You can re-download it later.
+ </>
+ ),
+ successMessage: `Deleted ${onDeviceRepoLabel(model.id)}`,
+ disabled: deleteDisabled,
+ onConfirm: async () => {
+ await deleteCachedModel(model.id, undefined, hfToken || undefined);
+ },
+ onDeleted: refreshCachedLists,
+ }}
+ />
+ </span>
+ ) : (
+ <span aria-hidden="true" className={cn(ROW_ACTIONS_CLASS, "h-6")} />
+ )}
</div>
);
};
diff --git a/studio/frontend/src/features/model-picker/components/model-selector/row-meta.ts b/studio/frontend/src/features/model-picker/components/model-selector/row-meta.ts
index 2c69ef96233..fe8e344d7f7 100644
--- a/studio/frontend/src/features/model-picker/components/model-selector/row-meta.ts
+++ b/studio/frontend/src/features/model-picker/components/model-selector/row-meta.ts
@@ -4,6 +4,10 @@
// Pure helpers for model-row presentation: owner/name split, lora trigger label, format pills,
// param chip, tabular size. No React/DOM deps so they stay easy to test.
+import {
+ audioCppDisplayName,
+ isAudioCppFolderId,
+} from "../../../audio/audio-cpp-catalog.ts";
import type { LoraModelOption } from "./types";
export type FormatTone = "gguf" | "mlx" | "checkpoint" | "adapter" | "npu";
@@ -42,6 +46,16 @@ export function isUnslothOwner(owner: string | null | undefined): boolean {
return normalized === "unsloth" || normalized === "unslothai";
}
+/** On Device label: an audio.cpp umbrella folder reads as its folder, any other id as itself. */
+export function onDeviceRepoLabel(id: string): string {
+ return isAudioCppFolderId(id) ? audioCppDisplayName(id) : id;
+}
+
+/** On Device rows grouped with Unsloth's: our Hub owners and the audio.cpp catalog folders. */
+export function isFeaturedOnDeviceRepoId(id: string): boolean {
+ return isUnslothOwner(splitRepoLabel(id).owner) || isAudioCppFolderId(id);
+}
+
/** Selector trigger label. Training and exported runs are named "<run>/<model>", so the run is the
* label; local inventory rows keep theirs, since an Ollama repo name carries real slashes. */
export function loraOptionLabel(
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 5ac0a262018..195cb81517d 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
@@ -16,7 +16,10 @@ import {
useHubInventory,
} from "@/features/hub";
import { useMemo } from "react";
-import { allowedHiddenModelIdMatches } from "../components/model-selector/audio-picker-policy";
+import {
+ allowedHiddenModelIdMatches,
+ umbrellaFolderRowAllowed,
+} from "../components/model-selector/audio-picker-policy";
import {
type FamilyOverrideArtifactKind,
taskOpaqueArtifactSupportsFamilyOverride,
@@ -54,6 +57,7 @@ function toCachedGgufRepo(row: CachedInventoryRow): CachedGgufRepo {
partial_resumable: row.partialResumable,
task: row.task ?? null,
audio_type: row.audioType ?? null,
+ audio_workflows: row.audioWorkflows ?? null,
has_variant_state: row.hasVariantState ?? false,
};
}
@@ -118,6 +122,7 @@ export function useChatPickerInventory(
kind: "models",
enabled: options.enabled,
includeLocal: true,
+ includeUmbrellaFolders: true,
});
const cachedGguf = useMemo(
@@ -127,6 +132,7 @@ export function useChatPickerInventory(
(row) =>
row.modelFormat === "gguf" &&
isListableCachedRow(row) &&
+ umbrellaFolderRowAllowed(row, options.allowedHiddenModelIds) &&
(!isHiddenModelId(row.repoId) ||
allowedHiddenModelIdMatches(
options.allowedHiddenModelIds,
diff --git a/studio/frontend/src/features/settings/tabs/agents-tab.tsx b/studio/frontend/src/features/settings/tabs/agents-tab.tsx
index a173618d619..849187c76c8 100644
--- a/studio/frontend/src/features/settings/tabs/agents-tab.tsx
+++ b/studio/frontend/src/features/settings/tabs/agents-tab.tsx
@@ -764,7 +764,9 @@ export function AgentsTab() {
}
const localEntries = localGgufEntries(local?.models ?? []);
const discovered = discoverGgufModels(info?.models ?? [], [
- ...cachedGgufs.map((cached) => cached.repo_id),
+ ...cachedGgufs
+ .filter((cached) => !cached.umbrella_folder)
+ .map((cached) => cached.repo_id),
...localEntries.map((entry) => entry.id),
]);
// Keep the snapshot load_id for --model while listing the model by repo id.
diff --git a/studio/frontend/tests/audio-cpp-catalog.test.ts b/studio/frontend/tests/audio-cpp-catalog.test.ts
index 4f2a74fece5..dc9173db414 100644
--- a/studio/frontend/tests/audio-cpp-catalog.test.ts
+++ b/studio/frontend/tests/audio-cpp-catalog.test.ts
@@ -19,6 +19,7 @@ import {
AUDIO_CPP_UNOFFERED_FOLDERS,
audioCppDictationModelFor,
audioCppDisplayName,
+ audioCppHubPath,
audioCppModelFor,
audioCppSizeLabel,
audioCppWorkflowsFor,
@@ -138,6 +139,17 @@ test("recommended ids are unique and name their Hub repo or package folder", ()
assert.equal(isAudioCppFolderId(AUDIO_CPP_REPO), false);
assert.equal(isAudioCppFolderId(`${AUDIO_CPP_REPO}/`), false);
assert.equal(isAudioCppFolderId("unslothai/Qwen3-ASR-0.6B-GGUF"), false);
+ assert.equal(
+ audioCppHubPath(`${AUDIO_CPP_REPO}/Qwen3-TTS-12Hz-0.6B-Base-GGUF`),
+ `${AUDIO_CPP_REPO}/tree/main/Qwen3-TTS-12Hz-0.6B-Base-GGUF`,
+ );
+ assert.equal(
+ audioCppHubPath(`${ACE_STEP}/turbo`),
+ `${AUDIO_CPP_REPO}/tree/main/ACE-Step1.5-GGUF`,
+ );
+ assert.equal(audioCppHubPath(AUDIO_CPP_REPO), null);
+ assert.equal(audioCppHubPath(MINIMAX_GGUF), null);
+ assert.equal(audioCppHubPath("unsloth/Qwen3-8B-GGUF"), null);
assert.equal(audioCppModelFor("OpenMOSS-Team/MOSS-TTS-Nano-100M"), null);
assert.equal(audioCppModelFor(""), null);
assert.equal(audioCppSizeLabel(57.6 * 1024 * 1024), "58 MB");
diff --git a/studio/frontend/tests/audio-umbrella-on-device-rows.test.ts b/studio/frontend/tests/audio-umbrella-on-device-rows.test.ts
new file mode 100644
index 00000000000..e2a25551427
--- /dev/null
+++ b/studio/frontend/tests/audio-umbrella-on-device-rows.test.ts
@@ -0,0 +1,178 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+// Umbrella folder rows list only on Audio pages that offer them.
+
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import type { CachedInventoryRow } from "../src/features/hub/inventory/types.ts";
+
+import { readSrc, registerBundlerResolver } from "./helpers/kit.ts";
+
+registerBundlerResolver();
+
+const { umbrellaFolderRowAllowed } =
+ await import("../src/features/model-picker/components/model-selector/audio-picker-policy.ts");
+const { isFeaturedOnDeviceRepoId, onDeviceRepoLabel } =
+ await import("../src/features/model-picker/components/model-selector/row-meta.ts");
+const { buildCachedInventoryRow, withUmbrellaFolderRows } =
+ await import("../src/features/hub/inventory/view-models.ts");
+
+const UMBRELLA = "audio-cpp/audio.cpp-gguf";
+const CLONE_FOLDER = `${UMBRELLA}/Qwen3-TTS-12Hz-0.6B-Base-GGUF`;
+const ASR_FOLDER = `${UMBRELLA}/Qwen3-ASR-0.6B-GGUF`;
+
+const PICKERS = readSrc(
+ "features/model-picker/components/model-selector/pickers.tsx",
+);
+const HUB_INVENTORY = readSrc("features/hub/inventory/use-hub-inventory.ts");
+const PICKER_INVENTORY = readSrc(
+ "features/model-picker/inventory/use-chat-picker-inventory.ts",
+);
+
+function folderRow(repoId: string): CachedInventoryRow {
+ return buildCachedInventoryRow(
+ {
+ repo_id: repoId,
+ load_id: repoId,
+ size_bytes: 1024,
+ cache_path: "/c/hub/models--audio-cpp--audio.cpp-gguf",
+ task: "text-to-speech",
+ audio_type: "audiocpp_tts",
+ audio_workflows: ["clone"],
+ umbrella_folder: true,
+ model_format: "gguf",
+ capabilities: { can_chat: false },
+ },
+ "gguf",
+ );
+}
+
+test("a folder row keeps its folder flag and workflows through the view model", () => {
+ const row = folderRow(CLONE_FOLDER);
+ assert.equal(row.umbrellaFolder, true);
+ assert.deepEqual(row.audioWorkflows, ["clone"]);
+ assert.equal(row.capabilities.canChat, false);
+ const plain = buildCachedInventoryRow(
+ { repo_id: UMBRELLA, size_bytes: 1, model_format: "gguf" },
+ "gguf",
+ );
+ assert.equal(plain.umbrellaFolder, false);
+ assert.equal(plain.audioWorkflows, null);
+});
+
+test("hub inventory drops folder rows unless a caller opts in", () => {
+ const umbrella = buildCachedInventoryRow(
+ { repo_id: UMBRELLA, size_bytes: 1, model_format: "gguf" },
+ "gguf",
+ );
+ const rows = [umbrella, folderRow(CLONE_FOLDER)];
+ assert.deepEqual(
+ withUmbrellaFolderRows(rows, false).map((row) => row.repoId),
+ [UMBRELLA],
+ );
+ assert.equal(withUmbrellaFolderRows(rows, true).length, 2);
+ assert.match(
+ HUB_INVENTORY,
+ /const includeUmbrellaFolders = options\.includeUmbrellaFolders \?\? false;/,
+ );
+ assert.match(
+ HUB_INVENTORY,
+ /withUmbrellaFolderRows\(\s*cachedGguf\.map\(\(row\) => buildCachedInventoryRow\(row, "gguf"\)\),\s*includeUmbrellaFolders,\s*\)/,
+ );
+});
+
+test("the picker lists a folder row only for a page that passed its exact id", () => {
+ const row = folderRow(CLONE_FOLDER);
+ assert.equal(
+ umbrellaFolderRowAllowed(row, undefined),
+ false,
+ "chat passes none",
+ );
+ assert.equal(umbrellaFolderRowAllowed(row, new Set()), false);
+ assert.equal(
+ umbrellaFolderRowAllowed(row, new Set([ASR_FOLDER.toLowerCase()])),
+ false,
+ "another page's folder",
+ );
+ assert.equal(
+ umbrellaFolderRowAllowed(row, new Set([CLONE_FOLDER.toLowerCase()])),
+ true,
+ );
+ assert.equal(
+ umbrellaFolderRowAllowed({ repoId: UMBRELLA }, undefined),
+ true,
+ "any other row is left to the hidden-model gate",
+ );
+ assert.match(PICKER_INVENTORY, /includeUmbrellaFolders: true,/);
+ assert.match(
+ PICKER_INVENTORY,
+ /row\.modelFormat === "gguf" &&\s*isListableCachedRow\(row\) &&\s*umbrellaFolderRowAllowed\(row, options\.allowedHiddenModelIds\) &&/,
+ );
+ assert.match(
+ PICKER_INVENTORY,
+ /audio_workflows: row\.audioWorkflows \?\? null,/,
+ );
+});
+
+test("On Device rows name a folder by its folder and group it with Unsloth's", () => {
+ assert.equal(
+ onDeviceRepoLabel(CLONE_FOLDER),
+ "Qwen3-TTS-12Hz-0.6B-Base-GGUF",
+ );
+ assert.equal(onDeviceRepoLabel(UMBRELLA), UMBRELLA);
+ assert.equal(onDeviceRepoLabel("someone/Model-GGUF"), "someone/Model-GGUF");
+ assert.equal(isFeaturedOnDeviceRepoId(CLONE_FOLDER), true);
+ assert.equal(isFeaturedOnDeviceRepoId(ASR_FOLDER), true);
+ assert.equal(isFeaturedOnDeviceRepoId("unsloth/Qwen3-8B-GGUF"), true);
+ assert.equal(isFeaturedOnDeviceRepoId("unslothai/Foo"), true);
+ assert.equal(isFeaturedOnDeviceRepoId(UMBRELLA), false);
+ assert.equal(isFeaturedOnDeviceRepoId("someone/Model-GGUF"), false);
+});
+
+test("pickers render folder rows through the label, group, link and menu helpers", () => {
+ assert.match(
+ PICKERS,
+ /function isUnslothPublisherRepoId\(repoId: string\): boolean \{\n\s*return isFeaturedOnDeviceRepoId\(repoId\);\n\}/,
+ );
+ assert.match(
+ PICKERS,
+ /huggingface\.co\/\$\{audioCppHubPath\(trimmed\) \?\? trimmed\}/,
+ );
+ for (const fn of [
+ "const renderSoleQuantGgufRow",
+ "const renderDownloadedGgufRow",
+ "const renderAdditionalOnDeviceModelRow",
+ ]) {
+ const start = PICKERS.indexOf(fn);
+ assert.ok(start > 0, fn);
+ const body = PICKERS.slice(start, PICKERS.indexOf("\n };\n", start));
+ assert.match(body, /label=\{[^}]*onDeviceRepoLabel\(/, fn);
+ }
+ const start = PICKERS.indexOf("const renderAdditionalOnDeviceModelRow");
+ const body = PICKERS.slice(start, PICKERS.indexOf("\n };\n", start));
+ assert.match(
+ body,
+ /isAudioCppFolderId\(model\.id\) \? \(\s*<span className=\{ROW_ACTIONS_CLASS\}>\s*<ModelRowMenu[\s\S]*cachePath=\{\{ repoId: model\.id \}\}[\s\S]*deleteCachedModel\(model\.id, undefined, hfToken \|\| undefined\)/,
+ );
+ assert.match(
+ body,
+ /<span aria-hidden="true" className=\{cn\(ROW_ACTIONS_CLASS, "h-6"\)\} \/>/,
+ );
+});
+
+test("Transcribe re-reads its STT On Device list when a cached model is deleted", () => {
+ const api = readSrc("features/hub/inventory/api.ts");
+ const start = api.indexOf("export async function deleteCachedModel(");
+ assert.ok(start > 0);
+ assert.match(
+ api.slice(start, api.indexOf("\n}\n", start)),
+ /bumpInventoryVersion\(\);/,
+ );
+ const page = readSrc("features/audio/audio-page.tsx");
+ assert.match(
+ page,
+ /const inventoryVersion = useInventoryVersion\(\);\s*const seenInventoryVersion = useRef\(inventoryVersion\);\s*useEffect\(\(\) => \{\s*if \(!active \|\| seenInventoryVersion\.current === inventoryVersion\) return;\s*seenInventoryVersion\.current = inventoryVersion;\s*void refreshSttStatus\(\);\s*\}, \[active, inventoryVersion, refreshSttStatus\]\);/,
+ );
+});
diff --git a/studio/frontend/tests/model-identity.test.ts b/studio/frontend/tests/model-identity.test.ts
index 050437524db..9a71604bd8a 100644
--- a/studio/frontend/tests/model-identity.test.ts
+++ b/studio/frontend/tests/model-identity.test.ts
@@ -478,3 +478,30 @@ test("keeps .gguf on Hub repo ids, which are not file paths", () => {
assert.equal(modelDisplayName("/srv/Qwen3-Q4.gguf"), "Qwen3-Q4");
assert.equal(modelDisplayName(String.raw`C:\models\Qwen3-Q4.gguf`), "Qwen3-Q4");
});
+
+test("an audio.cpp umbrella folder id is a Hub id, not a path", () => {
+ // Mirrors the umbrella exemption in model_ids._looks_like_path.
+ const folder = "audio-cpp/audio.cpp-gguf/Qwen3-TTS-12Hz-0.6B-Base-GGUF";
+ assert.equal(publicModelId(folder), folder);
+ assert.equal(modelDisplayName(folder), "Qwen3-TTS-12Hz-0.6B-Base-GGUF");
+ assert.equal(residentModelIdMatches(folder, folder), true);
+ assert.equal(
+ residentModelIdMatches(folder.toUpperCase(), folder),
+ true,
+ );
+ assert.equal(
+ residentModelIdMatches(folder, "audio-cpp/audio.cpp-gguf/Kokoro-82M-GGUF"),
+ false,
+ );
+ const snapshot =
+ "/c/hub/models--audio-cpp--audio.cpp-gguf/snapshots/abc123";
+ assert.equal(residentModelIdMatches(folder, snapshot), false);
+ assert.equal(residentModelIdMatches("audio-cpp/audio.cpp-gguf", folder), false);
+ assert.equal(residentModelIdMatches("audio-cpp/audio.cpp-gguf", snapshot), true);
+ // Still a path once it names a file or climbs out of the repo.
+ assert.equal(
+ publicModelId("audio-cpp/audio.cpp-gguf/Kokoro-82M-GGUF/kokoro-Q8_0.gguf"),
+ "kokoro-Q8_0",
+ );
+ assert.equal(publicModelId("audio-cpp/audio.cpp-gguf/../x"), "x");
+});