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.

236 KB
Raw Blame
# 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 asyncio
import json
import os
import shutil
import sys
import time
import weakref
from pathlib import Path
from fastapi import APIRouter, Body, Depends, Header, HTTPException, Query, Request
from pydantic import BaseModel
from typing import List, NamedTuple, Optional
from loggers import get_logger
from utils.scan_memo import in_scan_memo

# Dependency-light leaf (PEP 562 package init): no llama.cpp / torch import chain.
from core.inference.memory_contract import (
    EMPTY_BREAKDOWN,
    build_memory_estimate,
    project_kv_cache_estimate,
)
from core.inference.model_ids import display_model_name
from hub.schemas.inventory import LocalArtifactKind
from hub.services.models import account_access
from hub.services.models import catalog_classification as _catalog_classification
from utils import gguf_archs as _gguf_archs
from hub.services.models.catalog_classification import (
    _cached_repo_task,
    _is_sd_cpp_companion_repo,
    _local_model_task,
    _repo_gguf_task,
    _repo_has_pipeline_index,
    _repo_is_diffusers,
)
from hub.services.models.common import _diffusers_pipeline_artifact_kind

# Compat aliases for moved names; assigned via the module to satisfy verify_import_hoist.py.
_AMBIGUOUS_DIFFUSION_GGUF_ARCHS = _catalog_classification._AMBIGUOUS_DIFFUSION_GGUF_ARCHS
_DIFFUSION_GGUF_ARCHS = _catalog_classification._DIFFUSION_GGUF_ARCHS
_TASK_CLASSIFY_WALK_SECONDS = _catalog_classification._TASK_CLASSIFY_WALK_SECONDS
_UNSUPPORTED_DIFFUSION_GGUF_ARCHS = _catalog_classification._UNSUPPORTED_DIFFUSION_GGUF_ARCHS
_UNSUPPORTED_DIFFUSION_TASK = _catalog_classification._UNSUPPORTED_DIFFUSION_TASK
_SPEECH_GGUF_ARCHS = _catalog_classification._SPEECH_GGUF_ARCHS
_SPEECH_TASK = _catalog_classification._SPEECH_TASK
_VIDEO_GEN_TASK = _catalog_classification._VIDEO_GEN_TASK
_VIDEO_GGUF_ARCHS = _catalog_classification._VIDEO_GGUF_ARCHS
_arch_to_task = _catalog_classification._arch_to_task
_gguf_architecture = _catalog_classification._gguf_architecture
_gguf_folder_task = _catalog_classification._gguf_folder_task
_hf_cache_snapshot_repo_id = _catalog_classification._hf_cache_snapshot_repo_id
_is_trailing_split_shard = _catalog_classification._is_trailing_split_shard
_local_family_needles = _catalog_classification._local_family_needles
_local_is_diffusers = _catalog_classification._local_is_diffusers
_local_model_can_chat = _catalog_classification._local_model_can_chat
_task_classify_sort_key = _catalog_classification._task_classify_sort_key
# core.inference.llama_cpp imports this; without it the probe would wrongly report buildable.
_video_family_buildable = _catalog_classification._video_family_buildable
# Kept importable for downstream users of routes.models.
_H3_DENOISER_GGUF_PREFIXES = _catalog_classification._H3_DENOISER_GGUF_PREFIXES
_LOADABLE_MEDIA_GGUF_TASKS = _catalog_classification._LOADABLE_MEDIA_GGUF_TASKS
_MAX_TASK_CLASSIFY_GGUFS = _catalog_classification._MAX_TASK_CLASSIFY_GGUFS
_PLACEHOLDER_DIFFUSION_GGUF_ARCHS = _catalog_classification._PLACEHOLDER_DIFFUSION_GGUF_ARCHS
_TASK_CLASSIFY_READ_SECONDS = _catalog_classification._TASK_CLASSIFY_READ_SECONDS
_gguf_family_buildable = _catalog_classification._gguf_family_buildable
_diffusion_gguf_family_hints = _catalog_classification._diffusion_gguf_family_hints
_is_h3_bundle_gguf_hint = _catalog_classification._is_h3_bundle_gguf_hint
SPEECH_GGUF_ARCHS = _gguf_archs.SPEECH_GGUF_ARCHS
is_speech_gguf_architecture = _gguf_archs.is_speech_gguf_architecture
from utils.account_context import account_thread
from utils.utils import canonical_model_repo_id, log_and_http_error

import re as _re

_VALID_REPO_ID = _re.compile(r"^[A-Za-z0-9._-]+/[A-Za-z0-9._-]+$")


class CachedModelRepo(BaseModel):
    repo_id: str
    size_bytes: int
    last_modified: Optional[float] = None
    # "text-to-image" for cached diffusers image repos; declared here or response_model drops it.
    task: Optional[str] = None
    audio_type: Optional[str] = None
    # Snapshot incomplete (cancelled/partial download): the picker must not treat it as usable.
    partial: Optional[bool] = None
    # Diffusion-tagged repo with NO top-level model_index.json: needs from_single_file + a filename.
    single_file: Optional[bool] = None
    # Undeclared fields are dropped by response_model; pickers filter on these.
    companion: Optional[bool] = None
    # Snapshot path for a copy the bare repo id cannot reach (legacy cache while another is active).
    load_id: Optional[str] = None
    # "adapter" for a cached LoRA/PEFT repo; pickers that offer whole models filter on it.
    model_format: Optional[str] = None
    artifact_kind: Optional[LocalArtifactKind] = None
    # False for an encoder-only repo (embedding/CLIP/ViT); undeclared, response_model drops it.
    can_chat: Optional[bool] = None
    # Not the same as task, which only says whether this backend loads it as a pipeline.
    diffusers: Optional[bool] = None


class CachedModelsResponse(BaseModel):
    cached: List[CachedModelRepo]


def _is_valid_repo_id(repo_id: str) -> bool:
    return bool(_VALID_REPO_ID.fullmatch(repo_id))


def _normalize_hf_token(hf_token) -> Optional[str]:
    if not isinstance(hf_token, str):
        return None
    # Not str.strip(): that returns a plain str, dropping the UI-session marker.
    return normalize_token(hf_token)


def _safe_is_dir(path) -> bool:
    """``Path.is_dir()`` returning ``False`` instead of raising: Python >= 3.12 propagates
    ``PermissionError``, and folder-scan endpoints probe root-owned system locations."""
    try:
        return Path(path).is_dir()
    except OSError:
        return False


from utils.paths.scan_folder_health import (
    annotate_scan_folders,
    note_scan_folder_scanned,
    record_scan_failure,
    refresh_failed_scan_folders,
)

# Shared with hub scans; _HF_REPO_ID_RE is the "owner/name" shape, anything else is a path.
from utils.hidden_models import (
    _HF_REPO_ID_RE,
    _existing_resolved_path,
    _safe_resolve,
    decision_api_repo_ids,
    is_hidden_model as _is_hidden_model,
)


def hidden_model_matchers() -> tuple[list[str], list[str], list[str]]:
    """Substring needles, exact repo ids, and exact resolved paths identifying infra models (the RAG embedder,
    the llama.cpp install validation probe, and Decision API models) that pickers hide. A configured HF-repo embedder is
    published as its exact lowercased repo id and a local-path embedder as its exact resolved path only: a
    generic basename like "model" must not substring-hide unrelated chat models."""
    from core.rag import config as rag_config

    needles = [
        # Validation probe repo + exact filename; .gguf so it won't hide unrelated *-GGUF repos.
        "ggml-org/models",
        "stories260k.gguf",
    ]
    exact_ids = sorted(decision_api_repo_ids())
    exact_paths: list[str] = []
    for model in (
        rag_config.effective_embedding_model(),
        rag_config.effective_gguf_repo(),
    ):
        # Resolve a local path before the repo-id regex: "models/embedder" is a path, not a repo id.
        existing_path = _existing_resolved_path(model)
        if existing_path:
            exact_paths.append(existing_path.lower())
        elif _HF_REPO_ID_RE.match(model):
            exact_ids.append(model.lower())
        else:
            resolved = _safe_resolve(Path(model).expanduser())
            if resolved:
                exact_paths.append(resolved.lower())
    return needles, exact_ids, exact_paths


backend_path = Path(__file__).parent.parent.parent
if str(backend_path) not in sys.path:
    sys.path.insert(0, str(backend_path))

from auth.authentication import (
    allow_ambient_hf_token,
    authenticated_via_api_key,
    get_current_subject,
)
from hub.dependencies import get_hf_token, get_request_hf_token
from hub.utils.hf_tokens import (
    HfTokenArg,
    cache_reads_authorized,
    cached_read_refused,
    hf_token_arg,
    is_anonymous,
    normalize_token,
)
from hub.utils.host_paths import (
    redact_host_paths,
    redact_inventory_host_paths,
    resolve_host_path_reference,
    scrub_paths,
)
from hub.utils.mlx_variants import looks_like_mlx_repo
from utils.utils import anonymous_and_offline


# Says both halves, or operators go looking for a credential problem that is not there.
_UNAUTHORIZED_OFFLINE = (
    "This request cannot be authorized without network access, and this repository is not in "
    "the local cache."
)

# "unauthorized" alone reads as a broken credential, which a repo refusing this caller is not.
_UNAUTHORIZED_CACHED_MODEL = (
    "This model is cached on this host, but this repository does not authorize this caller to "
    "read it."
)


def _resolve_hub_token(header_token: HfTokenArg, query_token: Optional[str]) -> HfTokenArg:
    """Header wins over query token; rebuild sentinel, never the raw parameter, or ambient token returns"""
    header_token = account_access.account_hf_token(header_token)
    header_explicit = _normalize_hf_token(header_token)
    if header_explicit:
        return header_explicit
    query_explicit = _normalize_hf_token(query_token)
    if query_explicit:
        # normalize_token cannot create the UI-session marker; rebuild it from the header's caller class.
        return hf_token_arg(query_explicit, allow_ambient_token = not is_anonymous(header_token))
    return False if is_anonymous(header_token) else None


try:
    from utils.models import (
        scan_trained_models,
        scan_exported_models,
        get_base_model_from_checkpoint,
        load_model_defaults,
        get_base_model_from_lora,
        is_vision_model,
        is_embedding_model,
        scan_checkpoints,
        ModelConfig,
    )
    from utils.models.model_config import (
        _extract_quant_label,
        _is_big_endian_gguf_path,
        _is_imatrix_path,
        _is_mtp_drafter,
        is_audio_input_type,
        decision_layout,
        is_decision_model,
    )
    from core.inference.orchestrator import peek_inference_backend
    from utils.paths import (
        is_local_path,
        normalize_path,
        outputs_root,
        exports_root,
        resolve_cached_repo_id_case,
        resolve_output_dir,
        resolve_export_dir,
    )
except ImportError:
    parent_backend = backend_path.parent / "backend"
    if str(parent_backend) not in sys.path:
        sys.path.insert(0, str(parent_backend))
    from utils.models import (
        scan_trained_models,
        scan_exported_models,
        get_base_model_from_checkpoint,
        load_model_defaults,
        get_base_model_from_lora,
        is_vision_model,
        is_embedding_model,
        scan_checkpoints,
        ModelConfig,
    )
    from utils.models.model_config import (
        _extract_quant_label,
        _is_big_endian_gguf_path,
        _is_imatrix_path,
        _is_mtp_drafter,
        is_audio_input_type,
        decision_layout,
        is_decision_model,
    )
    from core.inference.orchestrator import peek_inference_backend
    from utils.paths import (
        is_local_path,
        normalize_path,
        outputs_root,
        exports_root,
        resolve_cached_repo_id_case,
        resolve_output_dir,
        resolve_export_dir,
    )

from models import (
    CheckpointInfo,
    CheckpointListResponse,
    LocalModelInfo,
    LocalModelListResponse,
    ModelCheckpoints,
    ModelDetails,
    LoRAScanResponse,
    LoRAInfo,
    ModelListResponse,
)
from models.models import (
    BrowseEntry,
    BrowseFoldersResponse,
    ExportSizeResponse,
    GgufVariantDetail,
    GgufVariantsResponse,
    LocalModelSource,
    ModelType,
    ScanFolderInfo,
    AddScanFolderRequest,
)
from models.responses import (
    LoRABaseModelResponse,
    VisionCheckResponse,
    EmbeddingCheckResponse,
)
from utils.paths.path_utils import is_appledouble_metadata, is_network_or_device_path

router = APIRouter()
logger = get_logger(__name__)

# Smallest context worth pricing; zero means native length, and llama.cpp pads KV to 256.
_MIN_PRICED_CONTEXT = 256


def derive_model_type(
    is_vision: bool,
    audio_type: Optional[str],
    is_embedding: bool = False,
    is_decision: bool = False,
) -> ModelType:
    if is_decision:
        return "decision"
    if is_embedding:
        return "embeddings"
    if audio_type is not None:
        return "audio"
    if is_vision:
        return "vision"
    return "text"


def _resolve_hf_cache_dir() -> Path:
    from utils.hf_cache_settings import get_hf_cache_paths
    return get_hf_cache_paths().hub_cache


def _is_model_directory(d: Path) -> bool:
    """True when *d* looks like a model directory: both a config (``config.json`` /
    ``adapter_config.json``) and weight files, excluding ``mmproj`` GGUFs (vision projectors),
    calibration imatrices and non-weight ``.bin`` files (``tokenizer.bin`` etc.)."""

    def _is_weight_file(f: Path) -> bool:
        if is_appledouble_metadata(f):
            return False
        suffix = f.suffix.lower()
        if suffix == ".safetensors":
            return True
        if suffix == ".gguf":
            return "mmproj" not in f.name.lower() and not _is_imatrix_path(f.name)
        if suffix == ".bin":
            name = f.name.lower()
            return (
                name.startswith("pytorch_model")
                or name.startswith("model")
                or name.startswith("adapter_model")
                or name.startswith("consolidated")
            )
        return False

    try:
        has_config = (d / "config.json").exists() or (d / "adapter_config.json").exists()
        if not has_config:
            return False
        return any(_is_weight_file(f) for f in d.iterdir() if f.is_file())
    except OSError:
        return False


# Weight .bin prefixes scanners accept, not companions like tokenizer.bin; mirrors _is_weight_file
_WEIGHT_BIN_PREFIXES = ("pytorch_model", "model", "adapter_model", "consolidated")


def _is_weight_bin(name: str) -> bool:
    low = name.lower()
    return low.endswith(".bin") and low.startswith(_WEIGHT_BIN_PREFIXES)


def _has_non_gguf_weights(path: Path) -> bool:
    """True if *path* holds non-GGUF weight files (``.safetensors`` or a weight ``.bin``), ignoring
    companion ``.bin`` files such as ``tokenizer.bin`` so a GGUF-only folder is not misread as a plain
    checkpoint."""
    try:
        # Only the safetensors arm needs the check: a weight ".bin" is recognised by its name prefix, which a
        # "._" already fails.
        from core.inference.diffusion_lora import is_image_lora_file
        if any(
            not is_appledouble_metadata(f) and not is_image_lora_file(f)
            for f in path.glob("*.safetensors")
        ):
            return True
        return any(_is_weight_bin(f.name) for f in path.glob("*.bin"))
    except OSError:
        return False


def _local_pipeline_index(d: Path) -> bool:
    from hub.services.models.common import _is_diffusers_pipeline_dir
    return _is_diffusers_pipeline_dir(d)


def _servable_gguf_names(directory: Path) -> list[str]:
    """The ``.gguf`` names in *directory* that count as a model being present there. An imatrix is
    calibration data, not a model artifact; mmproj and MTP drafters DO count, since they are
    companions of a real model and presence is all they decide."""
    from core.inference.diffusion_lora import is_image_lora_file
    return [
        p.name
        for p in directory.glob("*.gguf")
        if not is_appledouble_metadata(p)
        and not _is_imatrix_path(p.name)
        and not is_image_lora_file(p)
    ]


def _is_gguf_companion_only_dir(path: Path) -> bool:
    """Folders holding only mmproj or MTP drafter GGUFs are not loadable models and must not be listed."""
    try:
        if not path.is_dir():
            return False
        if (path / "config.json").exists() or (path / "adapter_config.json").exists():
            return False
        return any(path.glob("*.gguf")) and not _has_non_gguf_weights(path)
    except OSError:
        return False


def _scan_models_dir(
    models_dir: Path,
    *,
    limit: int | None = None,
    loose_files: bool = False,
) -> List[LocalModelInfo]:
    if not models_dir.exists() or not models_dir.is_dir():
        return []

    # A scan folder can point at a diffusers PIPELINE dir, which _is_model_directory rejects but the load path accepts.
    _is_self_model = _is_model_directory(models_dir) or _local_pipeline_index(models_dir)

    if _is_self_model:
        try:
            updated_at = models_dir.stat().st_mtime
        except OSError:
            updated_at = None
        return [
            LocalModelInfo(
                id = str(models_dir),
                display_name = models_dir.name,
                path = str(models_dir),
                source = "models_dir",
                model_format = _dir_model_format(models_dir),
                updated_at = updated_at,
            ),
        ]

    found: List[LocalModelInfo] = []
    for child in models_dir.iterdir():
        if limit is not None and len(found) >= limit:
            break
        try:
            if not child.is_dir():
                continue

            gguf_names = _servable_gguf_names(child)
            has_gguf = bool(gguf_names)
            # mmproj alone is a vision adapter, not servable weights: decides presence, never format.
            has_main_gguf = any(_is_main_gguf_filename(n) for n in gguf_names)
            has_non_gguf_weights = _has_non_gguf_weights(child)
            has_config = (child / "config.json").exists() or (
                child / "adapter_config.json"
            ).exists()
            # A diffusers PIPELINE folder (weights in component subdirs) is missed above but loadable.
            has_pipeline_index = _local_pipeline_index(child)
            has_model_files = has_gguf or has_non_gguf_weights or has_config or has_pipeline_index
        except OSError:
            continue
        if not has_model_files:
            continue
        try:
            updated_at = child.stat().st_mtime
        except OSError:
            updated_at = None
        # A folder whose only weights are .gguf is GGUF-format even with a config.json; the name is no guide.
        model_format = "gguf" if has_main_gguf and not has_non_gguf_weights else None
        found.append(
            LocalModelInfo(
                id = str(child),
                display_name = child.name,
                path = str(child),
                source = "models_dir",
                model_format = model_format,
                updated_at = updated_at,
            ),
        )
    if limit is None or len(found) < limit:
        from core.inference.diffusion_lora import is_image_lora_file
        for gguf_file in models_dir.glob("*.gguf"):
            if limit is not None and len(found) >= limit:
                break
            # A standalone mmproj is a vision adapter, not servable weights.
            if (
                gguf_file.is_file()
                and _is_main_gguf_filename(gguf_file.name)
                and not is_appledouble_metadata(gguf_file)
                and not is_image_lora_file(gguf_file)
            ):
                try:
                    updated_at = gguf_file.stat().st_mtime
                except OSError:
                    updated_at = None
                found.append(
                    LocalModelInfo(
                        id = str(gguf_file),
                        display_name = gguf_file.stem,
                        path = str(gguf_file),
                        source = "models_dir",
                        model_format = "gguf",
                        updated_at = updated_at,
                    ),
                )

    # Several loose checkpoints: one row per file (the folder rescue below needs exactly one).
    from core.inference.diffusion_local_files import resolve_local_single_file
    from hub.utils.comfy_models import loose_diffusion_checkpoints

    sole = resolve_local_single_file(str(models_dir)) if not (found or loose_files) else None
    loose = [] if sole is not None else loose_diffusion_checkpoints(models_dir)

    # A scan folder can also point at a BARE single-file checkpoint dir (one loose .safetensors,
    # no configs): both checks reject it, but resolve_local_single_file loads it.
    if (
        not found
        and not loose
        and (limit is None or limit > 0)
        and _has_non_gguf_weights(models_dir)
    ):
        try:
            updated_at = models_dir.stat().st_mtime
        except OSError:
            updated_at = None
        found.append(
            LocalModelInfo(
                id = str(models_dir),
                display_name = models_dir.name,
                path = str(models_dir),
                source = "models_dir",
                model_format = _dir_model_format(models_dir),
                updated_at = updated_at,
            ),
        )

    for checkpoint in loose:
        if limit is not None and len(found) >= limit:
            break
        try:
            updated_at = checkpoint.stat().st_mtime
        except OSError:
            continue
        found.append(
            LocalModelInfo(
                id = str(checkpoint),
                display_name = checkpoint.stem,
                path = str(checkpoint),
                source = "models_dir",
                model_format = None,
                updated_at = updated_at,
            ),
        )

    return found


def _scan_hf_cache(
    cache_dir: Path,
    *,
    active_cache: bool = True,
    classify_format: bool = True,
    variant_states = None,
) -> List[LocalModelInfo]:
    if not cache_dir.exists() or not cache_dir.is_dir():
        return []

    from hub.utils import inventory_scan as hf_cache_scan

    found: List[LocalModelInfo] = []
    for repo_dir in cache_dir.glob("models--*"):
        if not repo_dir.is_dir():
            continue

        repo_name = repo_dir.name[len("models--") :]
        if not repo_name:
            continue
        model_id = repo_name.replace("--", "/")

        try:
            updated_at = repo_dir.stat().st_mtime
        except OSError:
            updated_at = None

        variant_state = (
            variant_states.for_repo("model", model_id, hub_cache = cache_dir)
            if variant_states is not None
            else None
        )
        partial = hf_cache_scan.repo_listing_partial(
            model_id, repo_dir, variant_state = variant_state
        )

        load_id = model_id
        snapshot = _resolve_hf_cache_realpath(repo_dir)
        if not active_cache:
            load_id = snapshot or str(repo_dir.resolve())
        # Classify from the snapshot's own weights, not the name: GGUF repos often lack a -GGUF suffix.
        model_format = (
            _dir_model_format(Path(snapshot), recursive = True)
            if snapshot and classify_format
            else None
        )
        found.append(
            LocalModelInfo(
                id = load_id,
                model_id = model_id,
                display_name = model_id.split("/")[-1],
                model_format = model_format,
                path = load_id if not active_cache else str(repo_dir),
                source = "hf_cache",
                active_cache = active_cache,
                partial = partial,
                updated_at = updated_at,
            ),
        )
    return found


def _dir_model_format(path: Path, recursive: bool = False) -> Optional[str]:
    """One level down, not an rglob (blocks async /api/models/local); recursive=True reads quant subdirs"""
    try:

        def _servable(p: Path) -> bool:
            return _is_main_gguf_filename(p.name) and not is_appledouble_metadata(p)

        if not any(_servable(p) for p in path.glob("*.gguf")):
            if not recursive:
                return None
            if not any(_servable(p) for p in path.glob("*/*.gguf")):
                return None
        return None if _has_non_gguf_weights(path) else "gguf"
    except OSError:
        return None


def _scan_lmstudio_dir(
    lm_dir: Path, *, source: LocalModelSource = "lmstudio"
) -> List[LocalModelInfo]:
    """Scan a host-app model root; ``source`` names which app it belongs to."""
    if not lm_dir.exists() or not lm_dir.is_dir():
        return []

    # lm_dir may itself be a model directory (not a publisher); return it rather than skip it.
    if _is_model_directory(lm_dir):
        try:
            updated_at = lm_dir.stat().st_mtime
        except OSError:
            updated_at = None
        return [
            LocalModelInfo(
                id = str(lm_dir),
                display_name = lm_dir.name,
                path = str(lm_dir),
                source = source,
                model_format = _dir_model_format(lm_dir),
                updated_at = updated_at,
            ),
        ]

    from core.inference.diffusion_lora import is_image_lora_file

    found: List[LocalModelInfo] = []
    for child in lm_dir.iterdir():
        try:
            if not child.is_dir():
                if (
                    _is_main_gguf_filename(child.name)
                    and child.is_file()
                    and not is_appledouble_metadata(child)
                    and not is_image_lora_file(child)
                ):
                    try:
                        updated_at = child.stat().st_mtime
                    except OSError:
                        updated_at = None
                    found.append(
                        LocalModelInfo(
                            id = str(child),
                            display_name = child.stem,
                            path = str(child),
                            source = source,
                            model_format = "gguf",
                            updated_at = updated_at,
                        ),
                    )
                continue

            # Surface a model-directory child directly instead of descending into it as a publisher.
            if _is_model_directory(child):
                try:
                    updated_at = child.stat().st_mtime
                except OSError:
                    updated_at = None
                found.append(
                    LocalModelInfo(
                        id = str(child),
                        display_name = child.name,
                        path = str(child),
                        source = source,
                        model_format = _dir_model_format(child),
                        updated_at = updated_at,
                    ),
                )
                continue

            for model_dir in child.iterdir():
                try:
                    if model_dir.is_dir():
                        has_model = (
                            bool(_servable_gguf_names(model_dir))
                            or (model_dir / "config.json").exists()
                            or any(
                                not is_appledouble_metadata(p) and not is_image_lora_file(p)
                                for p in model_dir.glob("*.safetensors")
                            )
                        )
                        if not has_model:
                            continue
                        model_id = f"{child.name}/{model_dir.name}"
                        try:
                            updated_at = model_dir.stat().st_mtime
                        except OSError:
                            updated_at = None
                        found.append(
                            LocalModelInfo(
                                id = str(model_dir),
                                model_id = model_id,
                                display_name = model_dir.name,
                                path = str(model_dir),
                                source = source,
                                model_format = _dir_model_format(model_dir),
                                updated_at = updated_at,
                            ),
                        )
                    elif (
                        _is_main_gguf_filename(model_dir.name)
                        and model_dir.is_file()
                        and not is_appledouble_metadata(model_dir)
                        and not is_image_lora_file(model_dir)
                    ):
                        try:
                            updated_at = model_dir.stat().st_mtime
                        except OSError:
                            updated_at = None
                        found.append(
                            LocalModelInfo(
                                id = str(model_dir),
                                model_id = f"{child.name}/{model_dir.stem}",
                                display_name = model_dir.stem,
                                path = str(model_dir),
                                source = source,
                                model_format = "gguf",
                                updated_at = updated_at,
                            ),
                        )
                except OSError:
                    continue
        except OSError:
            continue
    return found


def _scan_ollama_dir(
    ollama_dir: Path,
    *,
    limit: Optional[int] = None,
    materialize_links: bool = True,
) -> List[LocalModelInfo]:
    """Readers treat row ids and paths as filenames, so materialize_links defaults to a .gguf link."""
    from hub.services.models.ollama import scan_ollama_dir
    return [
        LocalModelInfo.model_validate(row.model_dump())
        for row in scan_ollama_dir(ollama_dir, limit = limit, materialize_links = materialize_links)
    ]


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, ...] = ()
    ollama_dirs: tuple[Path, ...] = ()
    omlx_dirs: tuple[Path, ...] = ()


def _compat_local_inventory_sources() -> _CompatLocalInventorySources:
    from utils.paths import (
        ollama_model_dirs,
        hermes_model_dirs,
        hf_default_cache_dir,
        legacy_hf_cache_dir,
        lmstudio_model_dirs,
        omlx_model_dirs,
    )
    from utils.hf_cache_settings import known_hf_hub_caches
    return _CompatLocalInventorySources(
        _resolve_hf_cache_dir(),
        legacy_hf_cache_dir(),
        hf_default_cache_dir(),
        tuple(lmstudio_model_dirs()),
        tuple(known_hf_hub_caches()),
        tuple(hermes_model_dirs()),
        tuple(ollama_model_dirs()),
        tuple(omlx_model_dirs()),
    )


def _scan_nested_compat_rows(
    folder_path: Path, existing: List[LocalModelInfo], *, limit: int
) -> List[LocalModelInfo]:
    """Rows from a recursive scan folder's sub-folders that its own scan did not already list (#6371)."""
    from hub.services.models.local_inventory import is_loadable_model_dir, nested_scan_roots

    seen = {(m.path, m.model_format) for m in existing}
    found: List[LocalModelInfo] = []
    for root in nested_scan_roots(folder_path):
        if len(existing) + len(found) >= limit:
            break
        # No shared variant index: it was built for the registered caches, so a nested one reads its own state.
        rows = _scan_models_dir(root, limit = limit - len(existing) - len(found)) + _scan_hf_cache(
            root, active_cache = False
        )
        for row in rows:
            key = (row.path, row.model_format)
            path = Path(row.path)
            # This scanner also lists config-only folders; across a whole tree those are mostly other apps' configs.
            if row.source != "hf_cache" and not (path.is_file() or is_loadable_model_dir(path)):
                continue
            if key in seen or any(
                p in (".studio_links", "ollama_links") for p in Path(row.path).parts
            ):
                continue
            seen.add(key)
            found.append(row)
            if len(existing) + len(found) >= limit:
                return found
    return found


def _with_comfy_compat_rows(
    folder_path: Path, existing: List[LocalModelInfo], *, limit: int
) -> List[LocalModelInfo]:
    """``existing`` plus a ComfyUI root's denoiser-folder rows, minus the role folders themselves
    (the ``publisher/model`` scan lists them as models; they are containers)."""
    from hub.utils.comfy_models import comfy_dit_scan_roots, comfy_role_dirs

    role_dirs = comfy_role_dirs(folder_path)
    if role_dirs:
        existing = [
            m for m in existing if os.path.normcase(os.path.realpath(m.path)) not in role_dirs
        ]
    seen = {(m.path, m.model_format) for m in existing}
    found: List[LocalModelInfo] = []
    roots = comfy_dit_scan_roots(folder_path)
    scanned = {os.path.normcase(str(root)) for root in roots}
    for root in roots:
        if len(existing) + len(found) >= limit:
            break
        for row in _scan_models_dir(
            root, limit = limit - len(existing) - len(found), loose_files = True
        ):
            key = (row.path, row.model_format)
            if key in seen or os.path.normcase(row.path) in scanned:
                continue
            seen.add(key)
            found.append(row)
    return existing + found


@in_scan_memo
def collect_local_models(
    models_root: Path,
    *,
    custom_folders: Optional[list[dict]] = None,
    sources: Optional[_CompatLocalInventorySources] = None,
    materialize_ollama_links: bool = True,
) -> List[LocalModelInfo]:
    """Shared by the model picker and /v1/models so they cannot drift; models_root is caller-validated."""
    from storage.studio_db import list_scan_folders
    from hub.services.models.local_inventory import run_custom_folder_bounded_sync
    from hub.utils import gguf as gguf_utils
    from hub.utils import inventory_scan as hf_cache_scan
    from utils.models.model_config import detect_gguf_model

    sources = sources or _compat_local_inventory_sources()
    hf_cache_dir = sources.hf_cache_dir
    legacy_hf = sources.legacy_hf
    hf_default = sources.hf_default
    lm_dirs = sources.lm_dirs
    if custom_folders is None:
        try:
            custom_folders = list_scan_folders()
        except Exception as e:
            logger.warning("Could not load custom scan folders: %s", e)
            custom_folders = []

    local_models = _scan_models_dir(models_root)
    active_cache_real = _safe_resolve(hf_cache_dir)
    active_cache_key = os.path.normcase(active_cache_real) if active_cache_real else None
    seen_hf: set[str] = set()
    hf_sources: list[tuple[Path, bool]] = []
    for cache_dir in (
        hf_cache_dir,
        *sources.known_hf_caches,
        legacy_hf,
        hf_default,
        # oMLX also serves models--* repos kept under its own roots.
        *sources.omlx_dirs,
    ):
        cache_real = _safe_resolve(cache_dir)
        if cache_real is None:
            continue
        cache_key = os.path.normcase(str(cache_real))
        if cache_key in seen_hf:
            continue
        seen_hf.add(cache_key)
        hf_sources.append((cache_dir, cache_key == active_cache_key))

    state_repositories = []
    state_cache_dirs = [cache_dir for cache_dir, _active_cache in hf_sources]
    for folder in custom_folders:
        state_cache_dirs.extend(
            run_custom_folder_bounded_sync(
                str(folder["path"]),
                lambda path = Path(folder["path"]): hf_cache_scan.scan_folder_hf_caches(path),
            )
            or ()
        )
    for cache_dir in dict.fromkeys(state_cache_dirs):
        try:
            for repo_dir in cache_dir.glob("models--*"):
                repo_name = repo_dir.name[len("models--") :]
                if repo_name and repo_dir.is_dir():
                    state_repositories.append(("model", repo_name.replace("--", "/"), cache_dir))
        except OSError:
            continue
    try:
        from hub.utils import download_manifest, partial_verdict_cache

        # Taken before the index reads the Hub state, so a write in between misses next time.
        partial_verdict_cache.scan_token()
        variant_states = download_manifest.build_variant_state_index(
            state_repositories,
            active_hub_cache = hf_cache_dir,
        )
    except Exception as e:
        logger.warning("Could not build shared legacy Hub-state index: %s", e)
        variant_states = None

    for cache_dir, active_cache in hf_sources:
        local_models += _scan_hf_cache(
            cache_dir,
            active_cache = active_cache,
            variant_states = variant_states,
        )

    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)

    for ollama_dir in sources.ollama_dirs:
        try:
            local_models += _scan_ollama_dir(ollama_dir, materialize_links = materialize_ollama_links)
        except Exception as e:
            logger.warning("Error scanning Ollama directory %s: %s", ollama_dir, e)

    for omlx_dir in sources.omlx_dirs:
        try:
            local_models += _scan_lmstudio_dir(omlx_dir, source = "omlx")
        except Exception as e:
            logger.warning("Error scanning oMLX directory %s: %s", omlx_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}
    from hub.services.models.local_inventory import _local_model_path_is_symlink

    custom_identities: set[str] = set()

    def _scan_custom_folder(folder_path: Path, recursive: bool) -> list:
        # Filter Ollama .studio_links/ from generic scanners: duplicates and internal paths.
        _generic = [
            m
            for m in (
                _scan_models_dir(folder_path, limit = _MAX_MODELS_PER_FOLDER)
                + [
                    row
                    for cache_dir in hf_cache_scan.scan_folder_hf_caches(folder_path)
                    for row in _scan_hf_cache(
                        cache_dir,
                        active_cache = False,
                        variant_states = variant_states,
                    )
                ]
                + _scan_lmstudio_dir(folder_path)
            )
            if not any(p in (".studio_links", "ollama_links") for p in Path(m.path).parts)
        ]
        if recursive:
            _generic += _scan_nested_compat_rows(
                folder_path, _generic, limit = _MAX_MODELS_PER_FOLDER
            )
        _generic = _with_comfy_compat_rows(folder_path, _generic, limit = _MAX_MODELS_PER_FOLDER)
        custom_models = []
        for model in _generic:
            path = Path(model.path)
            is_gguf_row = model.model_format == "gguf" or _is_gguf_companion_only_dir(path)
            if not is_gguf_row or model.partial:
                custom_models.append(model)
                continue
            if path.is_dir():
                patterns = ("*", "*/*") if model.source == "hf_cache" else ("*",)
                if any(
                    detect_gguf_model(str(file), model_root = str(folder_path)) is not None
                    for pattern in patterns
                    for file in path.glob(pattern)
                    if not _safe_is_dir(file) and file.suffix.lower() == ".gguf"
                ):
                    custom_models.append(model)
            elif (
                detect_gguf_model(
                    model.path,
                    model_root = str(folder_path),
                )
                is not None
            ):
                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,
                limit = _MAX_MODELS_PER_FOLDER - len(custom_models),
                materialize_links = materialize_ollama_links,
            )
        return custom_models

    for folder in custom_folders:
        folder_path = Path(folder["path"])
        row_path = str(folder.get("path", folder_path))
        try:
            custom_models = run_custom_folder_bounded_sync(
                row_path,
                lambda path = folder_path, recursive = bool(folder.get("recursive")): (
                    _scan_custom_folder(path, recursive)
                ),
            )
        except OSError as e:
            logger.warning("Skipping unreadable scan folder %s: %s", folder_path, e)
            # Keep the reason so the folder list can show it instead of nothing.
            record_scan_failure(row_path, e)
            continue
        if custom_models is None:
            continue
        note_scan_folder_scanned(row_path, found = bool(custom_models))
        # Links below the scan root are distinct aliases (as in the Hub inventory), not twins.
        for m in custom_models:
            try:
                below_root = os.path.join(
                    os.path.realpath(folder_path), os.path.relpath(m.path, folder_path)
                )
            except (OSError, ValueError):
                continue
            if not _local_model_path_is_symlink(below_root):
                custom_identities.add(_compat_inventory_path_identity(m.path))
        # Keep an already-attributed source: a registered ~/.ollama/models (or a folder shadowing the HF
        # cache) must not re-stamp its rows as generic custom entries.
        local_models += [
            m
            if m.source in ("hf_cache", "ollama", "hermes")
            else m.model_copy(update = {"source": "custom"})
            for m in custom_models
        ]

    # A registered oMLX root (the pre-scan workaround) lists its models as custom rows too; keep
    # those (the train picker refuses oMLX rows).
    local_models = [
        m
        for m in local_models
        if m.source != "omlx" or _compat_inventory_path_identity(m.path) not in custom_identities
    ]

    # Deduplicate, but always keep custom folder entries (keyed by (id, source)) so they show in the
    # "Custom Folders" UI section even when the model is also in the HF cache.
    deduped: dict[str, LocalModelInfo] = {}
    for model in local_models:
        semantic_id = model.model_id if model.source == "hf_cache" and model.model_id else model.id
        if model.source == "custom":
            physical_identity = gguf_utils.local_path_physical_identity(model.path)
            if (
                model.model_id
                and model.model_id.startswith("ollama/")
                and any(
                    part in (".studio_links", "ollama_links") for part in Path(model.path).parts
                )
            ):
                physical_identity = "\x00".join((model.model_id, physical_identity))
            key = "\x00".join((physical_identity, model.model_format or "", "custom"))
        else:
            key = semantic_id
        existing = deduped.get(key)
        prefer_model = existing is None
        if existing is not None and model.source == existing.source == "hf_cache":
            if model.partial != existing.partial:
                prefer_model = not model.partial
            elif bool(model.active_cache) != bool(existing.active_cache):
                prefer_model = bool(model.active_cache)
            else:
                prefer_model = (model.updated_at or 0) > (existing.updated_at or 0)
        if prefer_model:
            deduped[key] = model

    deduped_values = list(deduped.values())
    custom_values = [model for model in deduped_values if model.source == "custom"]
    models = sorted(
        [model for model in deduped_values if model.source != "custom"]
        + gguf_utils.suppress_grouped_gguf_file_rows(custom_values),
        key = lambda item: item.updated_at or 0,
        reverse = True,
    )
    return [m for m in models if not _is_hidden_model(m.id, m.model_id, m.path)]


_CompatLocalInventoryKey = tuple[Path, _CompatLocalInventorySources, tuple[str, ...], int]
_compat_local_inventory_flights: dict[
    tuple[asyncio.AbstractEventLoop, _CompatLocalInventoryKey], asyncio.Task[List[LocalModelInfo]]
] = {}


# Retrying a superseded scan pays only while invalidations are rare; past the cap, answer anyway.
_COMPAT_LOCAL_INVENTORY_MAX_ATTEMPTS = 8


class _CompatLocalCacheChanged(RuntimeError):
    def __init__(self, models: List[LocalModelInfo]) -> None:
        super().__init__("local inventory sources changed during the scan")
        # Carried so the attempt cap can serve the freshest scan rather than loop forever or answer empty.
        self.models = models


def _compat_inventory_path_identity(path: object) -> str:
    raw = str(path)
    try:
        return os.path.normcase(os.path.realpath(os.path.expanduser(raw)))
    except (OSError, UnicodeError, ValueError):
        return os.path.normcase(raw)


@in_scan_memo
async def _shared_compat_local_inventory_scan(
    models_root: Path, sources: Optional[_CompatLocalInventorySources] = None
) -> List[LocalModelInfo]:
    from storage.studio_db import list_scan_folders
    from hub.services.models.local_inventory import custom_folder_identities
    from hub.utils import inventory_scan as hf_cache_scan

    requested_sources = sources

    def classify(models: List[LocalModelInfo]) -> List[LocalModelInfo]:
        # Task and audio type are set in the shared flight, so overlapping callers skip repeated GGUF reads.
        classified = []
        for model in models:
            task, audio_type = _catalog_classification._local_model_classification_for_task(
                model, _local_model_task(model)
            )
            workflows = _catalog_classification.local_audio_workflows(model, audio_type)
            classified.append(
                model.model_copy(
                    update = {
                        "task": task,
                        "audio_type": audio_type,
                        **({"audio_workflows": workflows} if workflows else {}),
                    }
                )
            )
        return classified

    async def collect(
        expected_epoch: int, custom_folders: List[dict], scan_sources: _CompatLocalInventorySources
    ) -> List[LocalModelInfo]:
        models = await asyncio.to_thread(
            collect_local_models,
            models_root,
            custom_folders = custom_folders,
            sources = scan_sources,
        )
        if hf_cache_scan.hf_cache_scans_epoch() != expected_epoch:
            raise _CompatLocalCacheChanged(models)
        classified = await asyncio.to_thread(classify, models)
        # That hop is an await point of its own, so a mutation can land after the check above.
        if hf_cache_scan.hf_cache_scans_epoch() != expected_epoch:
            raise _CompatLocalCacheChanged(models)
        return classified

    # Discard obsolete results and retry their waiters against the current cache epoch.
    superseded: Optional[List[LocalModelInfo]] = None
    for _attempt in range(_COMPAT_LOCAL_INVENTORY_MAX_ATTEMPTS):
        # Read the epoch first so any later source/folder change lands in a newer epoch.
        # Caller-supplied sources stay pinned: /local validated models_dir against those roots.
        epoch = hf_cache_scan.hf_cache_scans_epoch()
        scan_sources = requested_sources or _compat_local_inventory_sources()
        try:
            custom_folders = await asyncio.to_thread(list_scan_folders)
        except Exception as e:
            logger.warning("Could not load custom scan folders: %s", e)
            custom_folders = []
        # Off the loop and under the scan budget: realpath on a hung mount blocks in the kernel.
        identities = await asyncio.to_thread(
            custom_folder_identities, custom_folders, _compat_inventory_path_identity
        )
        key: _CompatLocalInventoryKey = (
            Path(_compat_inventory_path_identity(models_root)),
            scan_sources,
            tuple(
                identity + ("\x00r" if folder.get("recursive") else "")
                for identity, folder in zip(identities, custom_folders)
            ),
            epoch,
        )
        try:
            return await hf_cache_scan.shared_scan(
                _compat_local_inventory_flights,
                key,
                lambda expected_epoch = epoch, folders = custom_folders, roots = scan_sources: collect(
                    expected_epoch, folders, roots
                ),
            )
        except _CompatLocalCacheChanged as changed:
            superseded = changed.models
            continue
    # Invalidations outpace the walk, so no scan can confirm as current; serve the freshest one.
    logger.warning("Compat local inventory kept racing cache invalidations; serving the last scan")
    return await asyncio.to_thread(classify, superseded)


async def _invalidate_local_scans() -> None:
    """Every successful delete must call this or /v1/models keeps advertising it; off loop: lock stalls"""
    from core.inference.local_model_resolver import invalidate_index
    await asyncio.to_thread(invalidate_index)


@router.get("/local", response_model = LocalModelListResponse)
async def list_local_models(
    models_dir: str = Query(
        default = "./models", description = "Directory to scan for local model folders"
    ),
    current_subject: str = Depends(get_current_subject),
    via_api_key: bool = Depends(authenticated_via_api_key),
):
    """List local model candidates from the models dir, HF caches, LM Studio, Hermes, Ollama.

    Redacted as ``/api/hub/local`` is: this router mirrors it over the same scan roots, so
    leaving it alone recovers the layout that route hides.
    """
    # Off the loop: the probes stat every source root.
    sources = await asyncio.to_thread(_compat_local_inventory_sources)
    hf_cache_dir = sources.hf_cache_dir
    legacy_hf = sources.legacy_hf
    hf_default = sources.hf_default
    lm_dirs = sources.lm_dirs

    # Only trusted Path objects touch the FS; the user string is for matching only.
    allowed_roots: list[Path] = [Path("./models").resolve(), hf_cache_dir]
    if _safe_is_dir(legacy_hf):
        allowed_roots.append(legacy_hf)
    if _safe_is_dir(hf_default):
        allowed_roots.append(hf_default)
    try:
        from utils.paths import studio_root, outputs_root
        allowed_roots.extend([studio_root(), outputs_root()])
    except Exception:
        pass

    requested = os.path.realpath(os.path.expanduser(models_dir))
    models_root = None
    for root in allowed_roots:
        root_str = os.path.realpath(str(root))
        if requested == root_str or requested.startswith(root_str + os.sep):
            models_root = root  # trusted root, not the user-supplied path
            break
    if models_root is None:
        raise HTTPException(
            status_code = 403,
            detail = "Directory not allowed",
        )

    try:
        models = await _shared_compat_local_inventory_scan(models_root, sources)
        if account_access.managed_account():
            models = await asyncio.to_thread(account_access.filter_model_rows, models)
        return redact_inventory_host_paths(
            LocalModelListResponse(
                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,
            ),
            via_api_key = via_api_key,
        )
    except Exception as e:
        raise log_and_http_error(
            e,
            500,
            "Failed to list local models",
            event = "models.list_local_models_failed",
            log = logger,
        )


@router.get("/scan-folders")
async def get_scan_folders(
    current_subject: str = Depends(get_current_subject),
    via_api_key: bool = Depends(authenticated_via_api_key),
):
    """List all registered custom model scan folders. Redacted like ``/api/hub/scan-folders``."""
    from storage.studio_db import list_scan_folders

    folders = await asyncio.to_thread(list_scan_folders)
    # Opening the dialog is how a fixed folder clears, so recheck the bad ones.
    await asyncio.to_thread(refresh_failed_scan_folders, folders)
    return redact_inventory_host_paths(
        {"folders": annotate_scan_folders(folders)}, via_api_key = via_api_key
    )


@router.post("/scan-folders", response_model = ScanFolderInfo, status_code = 201)
async def add_scan_folder_endpoint(
    body: AddScanFolderRequest,
    current_subject: str = Depends(get_current_subject),
    via_api_key: bool = Depends(authenticated_via_api_key),
):
    """Register a new directory to scan for local models. Redacted like the GET above.

    The listings hide the normalized absolute path; submitting ``.`` here and reading the answer
    recovered the server's working directory.
    """
    if account_access.managed_account():
        body = body.model_copy(update = {"path": account_access.private_directory(body.path, "")})
    from storage.studio_db import add_scan_folder_with_status

    try:
        folder, inserted = await asyncio.to_thread(
            add_scan_folder_with_status, body.path, body.recursive
        )
    except ValueError as e:
        logger.warning("Scan folder rejected: %s (path=%s)", e, body.path)
        rejection_message = str(e)
        raise HTTPException(status_code = 400, detail = rejection_message)
    logger.info("Scan folder added: %s", folder.get("path"))
    if inserted:
        from core.inference.local_model_resolver import invalidate_index, warm_index_soon
        await asyncio.to_thread(invalidate_index)
        warm_index_soon()
    return redact_inventory_host_paths(folder, via_api_key = via_api_key)


@router.delete("/scan-folders/{folder_id}")
async def remove_scan_folder_endpoint(
    folder_id: int, current_subject: str = Depends(get_current_subject)
):
    """Remove a registered custom scan folder."""
    from storage.studio_db import remove_scan_folder

    removed = await asyncio.to_thread(remove_scan_folder, folder_id)
    if removed:
        logger.info("Scan folder removed: id=%s", folder_id)
        from core.inference.local_model_resolver import invalidate_index, warm_index_soon

        await asyncio.to_thread(invalidate_index)
        warm_index_soon()
    return {"ok": True}


def _dir_has_downloaded_model(directory: Path, max_entries: int = 4000) -> bool:
    """Any weight file counts, but an empty Ollama or LM Studio scaffold does not."""
    # Resolve the model layer blob: a failed pull can leave a manifest with no blob.
    visited = 0
    manifests = directory / "manifests"
    blobs = directory / "blobs"
    try:
        if _safe_is_dir(manifests) and _safe_is_dir(blobs):
            for m in manifests.rglob("*"):
                visited += 1
                if visited > max_entries:
                    break
                if not m.is_file():
                    continue
                try:
                    manifest = json.loads(m.read_text(encoding = "utf-8-sig"))
                except (json.JSONDecodeError, OSError, ValueError):
                    continue
                # Skip valid-JSON non-objects under manifests/ as _scan_ollama_dir does, or the chip probe raises.
                if not isinstance(manifest, dict):
                    continue
                layers = manifest.get("layers") or []
                if not isinstance(layers, list):
                    continue
                for layer in layers:
                    if not isinstance(layer, dict):
                        continue
                    if layer.get("mediaType") != "application/vnd.ollama.image.model":
                        continue
                    digest = layer.get("digest", "")
                    if (
                        isinstance(digest, str)
                        and digest
                        and (blobs / digest.replace(":", "-")).is_file()
                    ):
                        return True
    except OSError:
        pass
    # BFS skipping hidden dirs: rglob could exhaust the budget in a hidden subtree.
    queue = [directory]
    visited = 0
    while queue:
        current = queue.pop(0)
        try:
            entries = list(current.iterdir())
        except OSError:
            continue
        for entry in entries:
            visited += 1
            if visited > max_entries:
                return False
            try:
                if entry.is_dir():
                    if not entry.name.startswith("."):
                        queue.append(entry)
                else:
                    low = entry.name.lower()
                    if is_appledouble_metadata(entry):
                        continue
                    # Imatrix-only folders aren't surfaced, so counting one would advertise a chip that opens empty.
                    if low.endswith(".gguf") and not _is_imatrix_path(entry.name):
                        return True
                    if low.endswith(".safetensors"):
                        return True
                    # PyTorch checkpoints; gate by name so tokenizer.bin and friends don't count as weights.
                    if _is_weight_bin(entry.name):
                        return True
            except OSError:
                continue
    return False


@router.get("/recommended-folders")
async def get_recommended_folders(current_subject: str = Depends(get_current_subject)):
    """Return well-known model directories that hold a downloaded model.

    Lightweight alternative to ``browse-folders`` for the frontend's
    one-click "Recommended" chips. Only paths that actually contain
    weights are returned, so an empty LM Studio/Ollama scaffold no longer
    shows up as a suggestion.
    """
    account_access.require_installation_owner()
    from utils.paths.storage_roots import lmstudio_model_dirs

    folders: list[str] = []
    seen: set[str] = set()

    def _add(p: Optional[Path]) -> None:
        if p is None:
            return
        try:
            resolved = str(p.resolve())
        except OSError:
            return
        if resolved in seen:
            return
        if (
            _safe_is_dir(resolved)
            and os.access(resolved, os.R_OK | os.X_OK)
            and _dir_has_downloaded_model(Path(resolved))
        ):
            seen.add(resolved)
            folders.append(resolved)

    try:
        for p in lmstudio_model_dirs():
            _add(p)
    except Exception as e:
        logger.warning("Failed to scan for LM Studio model directories: %s", e)

    ollama_env = os.environ.get("OLLAMA_MODELS")
    if ollama_env:
        _add(Path(ollama_env).expanduser())
    for candidate in (
        Path.home() / ".ollama" / "models",
        Path("/usr/share/ollama/.ollama/models"),
        Path("/var/lib/ollama/.ollama/models"),
    ):
        _add(candidate)

    return {"folders": folders}


# Max children to stat when checking if a directory "looks like" it holds models.
_BROWSE_MODEL_HINT_PROBE = 64
# Hard cap on subdirectory entries so browsing ``/usr/lib`` can't stat-storm the process.
_BROWSE_ENTRY_CAP = 2000


def _count_model_files(directory: Path, cap: int = 200) -> int:
    """Count GGUF/safetensors files immediately inside *directory* so the UI can mark a weights-only
    leaf dir as a valid "Use this folder" target. Bounded by visited entries."""
    n = 0
    visited = 0
    try:
        for f in directory.iterdir():
            visited += 1
            if visited > cap:
                break
            try:
                if f.is_file():
                    low = f.name.lower()
                    if low.endswith((".gguf", ".safetensors")):
                        n += 1
            except OSError:
                continue
    except PermissionError as e:
        logger.debug("browse-folders: permission denied counting %s: %s", directory, e)
        return 0
    except OSError as e:
        logger.debug("browse-folders: OS error counting %s: %s", directory, e)
        return 0
    return n


def _has_direct_model_signal(directory: Path) -> bool:
    """True if an immediate child signals a model: a GGUF/safetensors/config.json file or a
    ``models--*`` subdir (HF cache). Bounded by ``_BROWSE_MODEL_HINT_PROBE``."""
    try:
        it = directory.iterdir()
    except OSError:
        return False
    try:
        for i, child in enumerate(it):
            if i >= _BROWSE_MODEL_HINT_PROBE:
                break
            try:
                name = child.name
                if child.is_file():
                    low = name.lower()
                    if low.endswith((".gguf", ".safetensors")) and not is_appledouble_metadata(
                        child
                    ):
                        return True
                    if low in ("config.json", "adapter_config.json"):
                        return True
                elif child.is_dir() and name.startswith("models--"):
                    return True
            except OSError:
                continue
    except OSError:
        return False
    return False


def _looks_like_model_dir(directory: Path) -> bool:
    """Bounded heuristic to flag dirs worth exploring in the browser; false negatives are fine, the real scanner
    is authoritative. Three signals, cheapest first: name ``models--*`` (HF cache layout), an immediate child
    weight/config file, then a grandchild with a direct signal (LM Studio / Ollama ``publisher/model``)."""
    if directory.name.startswith("models--"):
        return True
    if _has_direct_model_signal(directory):
        return True
    try:
        it = directory.iterdir()
    except OSError:
        return False
    try:
        for i, child in enumerate(it):
            if i >= _BROWSE_MODEL_HINT_PROBE:
                break
            try:
                if not child.is_dir():
                    continue
            except OSError:
                continue
            if child.name.startswith("models--"):
                return True
            if _has_direct_model_signal(child):
                return True
    except OSError:
        return False
    return False


def _build_browse_allowlist(
    media_roots: Optional[list[Path]] = None, drive_roots: Optional[list[Path]] = None
) -> list[Path]:
    """Returns browsable root dirs, which also seed sidebar chips; takes pre-probed media and drive roots"""
    from utils.paths import (
        hf_default_cache_dir,
        legacy_hf_cache_dir,
        well_known_model_dirs,
    )
    from utils.paths import external_media
    from storage.studio_db import list_scan_folders

    candidates: list[Path] = []

    def _add(p: Optional[Path]) -> None:
        if p is None:
            return
        try:
            resolved = p.resolve()
        except OSError:
            return
        if _safe_is_dir(resolved):
            candidates.append(resolved)

    _add(Path.home())
    if media_roots is None:
        media_roots = [
            *external_media.linux_external_mount_roots(),
            *external_media.macos_volume_roots(),
        ]
    if drive_roots is None:
        drive_roots = external_media.windows_drive_roots()
    for p in media_roots:
        _add(p)
    for p in drive_roots:
        _add(p)
    _add(_resolve_hf_cache_dir())
    try:
        _add(hf_default_cache_dir())
    except Exception:  # noqa: BLE001 -- best-effort
        pass
    try:
        _add(legacy_hf_cache_dir())
    except Exception:  # noqa: BLE001 -- best-effort
        pass
    try:
        from utils.paths import (
            exports_root,
            outputs_root,
            studio_root,
        )

        _add(studio_root())
        _add(outputs_root())
        _add(exports_root())
    except Exception as exc:  # noqa: BLE001 -- best-effort
        logger.debug("browse-folders: Unsloth roots unavailable: %s", exc)
    try:
        for folder in list_scan_folders():
            p = folder.get("path")
            if p:
                _add(Path(p))
    except Exception as exc:  # noqa: BLE001 -- best-effort
        logger.debug("browse-folders: could not load scan folders: %s", exc)
    try:
        for p in well_known_model_dirs():
            _add(p)
    except Exception as exc:  # noqa: BLE001 -- best-effort
        logger.debug("browse-folders: well-known dirs unavailable: %s", exc)

    seen: set[str] = set()
    deduped: list[Path] = []
    for p in candidates:
        key = str(p)
        if key in seen:
            continue
        seen.add(key)
        deduped.append(p)
    return deduped


def _is_path_inside_allowlist(target: Path, allowed_roots: list[Path]) -> bool:
    """Realpath, so symlinks cannot escape; whole components only; POSIX / covers no descendants"""
    try:
        target_real = os.path.normcase(os.path.realpath(str(target)))
    except OSError:
        return False
    for root in allowed_roots:
        try:
            root_real = os.path.normcase(os.path.realpath(str(root)))
        except OSError:
            continue
        if target_real == root_real:
            return True
        drive, tail = os.path.splitdrive(root_real)
        if os.path.dirname(root_real) == root_real and not drive:
            # Bare POSIX root ("/"): equality above is the only match; don't authorize descendants.
            continue
        if drive.startswith(("\\\\", "//")) and not tail:
            # os.path.commonpath raises on a bare UNC share root, so use a boundary-safe prefix test
            if target_real.startswith(root_real.rstrip("\\/") + os.sep):
                return True
            continue
        try:
            if os.path.commonpath([target_real, root_real]) == root_real:
                return True
        except ValueError:
            # Different drives / mixed absolute-relative: not contained.
            continue
    return False


def _normalize_browse_request_path(path: Optional[str]) -> str:
    if path is None or not path.strip():
        return os.path.normpath(str(Path.home()))

    expanded = os.path.expanduser(path.strip())
    if not os.path.isabs(expanded):
        expanded = os.path.join(str(Path.cwd()), expanded)
    return os.path.normpath(expanded)


def _browse_relative_parts(requested_path: str, root: Path) -> Optional[list[str]]:
    root_text = os.path.normpath(str(root))
    try:
        rel_text = os.path.relpath(requested_path, root_text)
    except ValueError:
        return None

    if rel_text == ".":
        return []
    if rel_text == ".." or rel_text.startswith(f"..{os.sep}"):
        return None

    parts = [part for part in rel_text.split(os.sep) if part not in ("", ".")]
    altsep = os.altsep
    for part in parts:
        if part == ".." or os.sep in part or (altsep and altsep in part):
            return None
    return parts


def _match_browse_child(current: Path, name: str) -> Optional[Path]:
    try:
        for child in current.iterdir():
            if child.name == name:
                return child
    except PermissionError:
        raise HTTPException(
            status_code = 403,
            detail = f"Permission denied reading {current.name}",
        ) from None
    except OSError as exc:
        logger.warning("browse-folders: could not read %s: %s", current, exc, exc_info = True)
        raise HTTPException(
            status_code = 500,
            detail = f"Could not read {os.path.basename(str(current))}",
        ) from exc
    return None


def _resolve_browse_target(path: Optional[str], allowed_roots: list[Path]) -> Path:
    from storage.studio_db import (
        contains_sensitive_path_component,
        is_denied_system_path,
    )

    requested_path = _normalize_browse_request_path(path)
    resolved_roots: list[Path] = []
    seen_roots: set[str] = set()
    for root in sorted(allowed_roots, key = lambda p: len(str(p)), reverse = True):
        try:
            resolved = root.resolve()
        except OSError:
            continue
        key = str(resolved)
        if key in seen_roots:
            continue
        seen_roots.add(key)
        resolved_roots.append(resolved)

    if not any(_browse_relative_parts(requested_path, root) is not None for root in resolved_roots):
        # Spelled through a symlinked root (moved install, linked $HOME): matches only once resolved.
        if not is_network_or_device_path(requested_path):
            try:
                real = os.path.realpath(requested_path)
            except (OSError, ValueError):
                real = requested_path
            if not is_network_or_device_path(real):
                requested_path = real

    for root in resolved_roots:
        parts = _browse_relative_parts(requested_path, root)
        if parts is None:
            continue

        current = root
        for part in parts:
            child = _match_browse_child(current, part)
            if child is None:
                raise HTTPException(
                    status_code = 404,
                    detail = f"Path does not exist: {os.path.basename(requested_path)}",
                )
            try:
                resolved_child = child.resolve()
            except OSError as exc:
                logger.warning(
                    "browse-folders: invalid path component %r under %s: %s",
                    part,
                    current,
                    exc,
                    exc_info = True,
                )
                raise HTTPException(
                    status_code = 400,
                    detail = "Invalid path",
                ) from exc
            if not _is_path_inside_allowlist(resolved_child, resolved_roots):
                raise HTTPException(
                    status_code = 403,
                    detail = (
                        "Path is not in the browseable allowlist. Register it via "
                        "POST /api/models/scan-folders first, or pick a directory "
                        "under your home folder."
                    ),
                )
            if contains_sensitive_path_component(str(resolved_child)):
                raise HTTPException(
                    status_code = 403,
                    detail = "Credential or configuration directories are not browseable.",
                )
            if is_denied_system_path(str(resolved_child)):
                raise HTTPException(
                    status_code = 403,
                    detail = "System directories are not browseable.",
                )
            current = resolved_child

        if contains_sensitive_path_component(str(current)):
            raise HTTPException(
                status_code = 403,
                detail = "Credential or configuration directories are not browseable.",
            )
        # Zero-component case: the requested path IS an allowlist root (legacy "/" or a drive root).
        if is_denied_system_path(str(current)):
            raise HTTPException(
                status_code = 403,
                detail = "System directories are not browseable.",
            )
        if not current.is_dir():
            raise HTTPException(
                status_code = 400,
                detail = f"Not a directory: {os.path.basename(str(current))}",
            )
        return current

    raise HTTPException(
        status_code = 403,
        detail = (
            "Path is not in the browseable allowlist. Register it via "
            "POST /api/models/scan-folders first, or pick a directory "
            "under your home folder."
        ),
    )


# Sync def so FastAPI threadpools it: a dead mapped drive would stall the loop.
@router.get("/browse-folders", response_model = BrowseFoldersResponse)
def browse_folders(
    path: Optional[str] = Query(
        None,
        description = (
            "Directory to list. If omitted, defaults to the current user's "
            "home directory. Tilde (`~`) and relative paths are expanded. "
            "Must resolve inside the allowlist of browseable roots (HOME, "
            "HF cache, Unsloth dirs, registered scan folders, well-known "
            "model dirs)."
        ),
    ),
    show_hidden: bool = Query(
        False,
        description = "Include entries whose name starts with a dot",
    ),
    current_subject: str = Depends(get_current_subject),
):
    """List immediate subdirectories of *path* for the Custom Folders picker.

    Lets the frontend render a modal folder browser without a native OS
    dialog. Read-only: enumerates visible subdirectories so the user can
    click to a folder and hand the string to POST /api/models/scan-folders.

    Sandbox: bounded to :func:`_build_browse_allowlist`; paths outside it
    return 403, and symlinks are resolved via ``os.path.realpath`` first
    so traversal can't escape. Sorting: model-bearing dirs, then plain,
    then hidden (if ``show_hidden=true``).
    """
    from utils.paths.storage_roots import workspace_root

    managed = account_access.managed_account()
    if managed:
        path = account_access.private_directory(path or str(workspace_root()), "")
    from utils.paths import hf_default_cache_dir, well_known_model_dirs
    from utils.paths import external_media
    from storage.studio_db import (
        contains_sensitive_path_component,
        is_denied_system_path,
        list_scan_folders,
    )

    # A managed account browses its workspace only; no media/drive roots or chips outside it.
    media_roots = (
        []
        if managed
        else [
            *external_media.linux_external_mount_roots(),
            *external_media.macos_volume_roots(),
        ]
    )
    drive_roots = [] if managed else external_media.windows_drive_roots()
    allowed_roots = (
        [workspace_root().resolve()]
        if managed
        else _build_browse_allowlist(media_roots, drive_roots)
    )

    try:
        target = _resolve_browse_target(path, allowed_roots)
    except HTTPException:
        requested_path = _normalize_browse_request_path(path)
        if path is not None and path.strip():
            logger.warning(
                "browse-folders: rejected path %r (normalized=%s)",
                path,
                requested_path,
            )
        raise

    entries: list[BrowseEntry] = []
    truncated = False
    visited = 0
    try:
        it = target.iterdir()
    except PermissionError:
        raise HTTPException(
            status_code = 403,
            detail = f"Permission denied reading {os.path.basename(str(target))}",
        )
    except OSError as exc:
        logger.warning("browse-folders: could not read %s: %s", target, exc, exc_info = True)
        raise HTTPException(
            status_code = 500,
            detail = f"Could not read {os.path.basename(str(target))}",
        )

    try:
        for child in it:
            # Bound by visits, not appends, so dirs full of files still hit the cap.
            visited += 1
            if visited > _BROWSE_ENTRY_CAP:
                truncated = True
                break
            try:
                if not child.is_dir():
                    continue
            except OSError:
                continue
            name = child.name
            is_hidden = name.startswith(".")
            if is_hidden and not show_hidden:
                continue
            if contains_sensitive_path_component(name):
                continue
            # Hide denied system dirs (Windows, /etc); resolve first so symlinks into them are hidden
            try:
                resolved_child = os.path.realpath(str(child))
            except (OSError, ValueError):
                resolved_child = str(child)
            if is_denied_system_path(resolved_child):
                continue
            entries.append(
                BrowseEntry(
                    name = name,
                    has_models = _looks_like_model_dir(child),
                    hidden = is_hidden,
                )
            )
    except PermissionError as exc:
        logger.debug(
            "browse-folders: permission denied during enumeration of %s: %s",
            target,
            exc,
        )
    except OSError as exc:
        logger.warning("browse-folders: partial enumeration of %s: %s", target, exc)

    # Model-bearing first, then plain, then hidden; case-insensitive within each bucket.
    def _sort_key(e: BrowseEntry) -> tuple[int, str]:
        bucket = 0 if e.has_models else (2 if e.hidden else 1)
        return (bucket, e.name.lower())

    entries.sort(key = _sort_key)

    # Parent is None at the filesystem root or outside the allowed roots, else the up-row would 403.
    parent: Optional[str]
    if target.parent == target or not _is_path_inside_allowlist(target.parent, allowed_roots):
        parent = None
    else:
        parent = str(target.parent)

    suggestions: list[str] = []
    seen_sug: set[str] = set()

    def _add_sug(p: Optional[Path]) -> None:
        if p is None:
            return
        try:
            resolved = str(p.resolve())
        except OSError:
            return
        if resolved in seen_sug:
            return
        # Drop denied system dirs so no chip 403s; drive roots stay, with only their system subdirs denied.
        if is_denied_system_path(resolved):
            return
        if _safe_is_dir(resolved):
            seen_sug.add(resolved)
            suggestions.append(resolved)

    if managed:
        for root in allowed_roots:
            _add_sug(root)
    else:
        _add_sug(Path.home())
        for p in media_roots:
            _add_sug(p)
        for p in drive_roots:
            _add_sug(p)
        try:
            _add_sug(hf_default_cache_dir())
        except Exception:
            pass
        try:
            for folder in list_scan_folders():
                _add_sug(Path(folder.get("path", "")))
        except Exception as exc:
            logger.debug("browse-folders: could not load scan folders: %s", exc)
        try:
            for p in well_known_model_dirs():
                _add_sug(p)
        except Exception as exc:
            logger.debug("browse-folders: could not load well-known dirs: %s", exc)

    return BrowseFoldersResponse(
        current = str(target),
        parent = parent,
        entries = entries,
        suggestions = suggestions,
        truncated = truncated,
        model_files_here = _count_model_files(target),
    )


@router.get("/list")
async def list_models(current_subject: str = Depends(get_current_subject)):
    """List available models: default plus currently loaded."""
    try:
        from core.inference.defaults import get_default_models

        # Chat reads this on first paint: listing suggestions must not construct the runtime or probe hardware.
        inference_backend = peek_inference_backend()
        default_models = await asyncio.to_thread(
            lambda: inference_backend.default_models
            if inference_backend is not None
            else get_default_models(detect_hardware = False)
        )
        if account_access.managed_account():
            default_models = [
                m
                for m in default_models
                if await asyncio.to_thread(account_access.model_visible, m)
            ]

        from core.inference import model_slots
        from routes.inference import _llama_status_model_ids, get_llama_cpp_backend

        def _orchestrator_models(orchestrator) -> list[ModelDetails]:
            entries = []
            for model_name, model_data in orchestrator.models.items():
                _is_vision = model_data.get("is_vision", False)
                _audio_type = model_data.get("audio_type")
                entries.append(
                    ModelDetails(
                        id = model_name,
                        name = display_model_name(model_name),
                        is_vision = _is_vision,
                        is_lora = model_data.get("is_lora", False),
                        is_mlx = model_data.get("is_mlx", False),
                        is_audio = model_data.get("is_audio", False),
                        audio_type = _audio_type,
                        has_audio_input = model_data.get("has_audio_input", False),
                        model_type = derive_model_type(_is_vision, _audio_type),
                    )
                )
            return entries

        def _gguf_model(llama_backend) -> list[ModelDetails]:
            if not (llama_backend.is_loaded and llama_backend.model_identifier):
                return []
            display_id, _reported_identifier = _llama_status_model_ids(llama_backend)
            return [
                ModelDetails(
                    id = llama_backend.model_identifier,
                    name = display_model_name(display_id or llama_backend.model_identifier),
                    is_gguf = True,
                    is_vision = llama_backend.is_vision,
                    is_audio = getattr(llama_backend, "_is_audio", False),
                    audio_type = getattr(llama_backend, "_audio_type", None),
                    has_audio_input = bool(getattr(llama_backend, "_has_audio_input", False)),
                )
            ]

        loaded_models = []
        hide_resident = account_access.resident_hidden(
            "chat", getattr(inference_backend, "active_model_name", None)
        )
        if not hide_resident and inference_backend is not None:
            loaded_models += _orchestrator_models(inference_backend)

        llama_backend = get_llama_cpp_backend()
        hide_resident = hide_resident or account_access.resident_hidden(
            "chat", getattr(llama_backend, "model_identifier", None)
        )
        if not hide_resident:
            loaded_models += _gguf_model(llama_backend)

        for slot in model_slots.visible():
            loaded_models += _orchestrator_models(slot.orchestrator)
            loaded_models += model_slots.in_slot(slot, lambda: _gguf_model(slot.llama))

        all_models = []
        seen_ids = set()
        loaded_by_id = {model_info.id: model_info for model_info in loaded_models}

        for model_id in default_models:
            if model_id not in seen_ids:
                model_info = loaded_by_id.get(model_id) or ModelDetails(
                    id = model_id,
                    name = display_model_name(model_id),
                    is_gguf = model_id.upper().endswith("-GGUF"),
                    is_mlx = looks_like_mlx_repo(model_id),
                )
                all_models.append(model_info)
                seen_ids.add(model_id)

        for model_info in loaded_models:
            if model_info.id not in seen_ids:
                all_models.append(model_info)
                seen_ids.add(model_info.id)

        return ModelListResponse(models = all_models, default_models = default_models)

    except Exception as e:
        raise log_and_http_error(
            e,
            500,
            "Failed to list models",
            event = "models.list_models_failed",
            log = logger,
        )


def _get_max_position_embeddings(config) -> Optional[int]:
    """The window this model was trained for, by the rule a load resolves it with. Reading one field
    name showed a dash for a model spelling it another way (Kimi Linear carries model_max_length
    alone) and a number as soon as it loaded."""
    from types import SimpleNamespace

    from core.inference.mlx_inference import mlx_native_context_length

    return mlx_native_context_length(SimpleNamespace(config = config))


_MODEL_WEIGHT_EXTENSIONS = (".safetensors", ".bin", ".pt", ".pth", ".gguf")


def _get_model_size_bytes(model_name: str, hf_token: HfTokenArg = None) -> Optional[int]:
    try:
        from huggingface_hub import HfApi

        api = HfApi(token = hf_token)
        info = api.repo_info(model_name, repo_type = "model", token = hf_token)
        if not info.siblings:
            return None

        total = 0
        for sibling in info.siblings:
            if sibling.rfilename and sibling.rfilename.endswith(_MODEL_WEIGHT_EXTENSIONS):
                if sibling.size is not None:
                    total += sibling.size

        return total if total > 0 else None
    except Exception as e:
        logger.warning(f"Could not get model size for {model_name}: {e}")
        return None


def _get_snapshot_model_size_bytes(snapshot_path: str) -> Optional[int]:
    try:
        snapshot = Path(snapshot_path).resolve(strict = True)
        snapshots_dir = snapshot.parent.resolve(strict = True)
        repo_dir = snapshots_dir.parent.resolve(strict = True)
        if not snapshot.is_dir() or snapshots_dir.name != "snapshots" or not repo_dir.is_dir():
            return None
        blobs_dir = repo_dir / "blobs"
        resolved_blobs_dir = blobs_dir.resolve(strict = True) if blobs_dir.is_dir() else None
        # hub 1.x shares one blob store per cache root, outside the repo dir.
        shared_blobs_dir = repo_dir.parent / "blobs"
        resolved_shared_blobs_dir = (
            shared_blobs_dir.resolve(strict = True) if shared_blobs_dir.is_dir() else None
        )
    except (OSError, RuntimeError, ValueError):
        return None

    total = 0
    scan_failed = False

    def _record_walk_error(_error: OSError) -> None:
        nonlocal scan_failed
        scan_failed = True

    try:
        for root, _, filenames in os.walk(
            snapshot,
            followlinks = False,
            onerror = _record_walk_error,
        ):
            root_path = Path(root)
            for filename in filenames:
                if not filename.endswith(_MODEL_WEIGHT_EXTENSIONS):
                    continue
                try:
                    candidate = (root_path / filename).resolve(strict = True)
                    if not candidate.is_file():
                        continue
                    if not candidate.is_relative_to(snapshot) and not any(
                        blob_root is not None and candidate.is_relative_to(blob_root)
                        for blob_root in (resolved_blobs_dir, resolved_shared_blobs_dir)
                    ):
                        continue
                    total += candidate.stat().st_size
                except (OSError, RuntimeError, ValueError):
                    scan_failed = True
    except OSError:
        return None
    return total if total > 0 and not scan_failed else None


def _model_config_inspection_target(
    model_name: str,
    prefer_local_cache: bool,
    local_path: Optional[str],
    hf_token: HfTokenArg = None,
) -> str:
    if not prefer_local_cache or is_local_path(model_name):
        return model_name
    # The cached snapshot ignores the token, so a caller denied ambient creds goes to the Hub.
    if not cache_reads_authorized(hf_token, repo_id = canonical_model_repo_id(model_name)):
        return model_name
    from hub.utils.hf_cache_state import (
        latest_snapshot_from_cache_path,
        with_load_subdirs,
    )

    snapshot = latest_snapshot_from_cache_path(
        local_path,
        "model",
        canonical_model_repo_id(model_name),
        with_load_subdirs(model_name, ("config.json", "adapter_config.json")),
    )
    if snapshot is None:
        # A cached Laya checkpoint has no config.json; the probes read it by repo id.
        if is_decision_model(model_name, hf_token, local_files_only = True):
            return model_name
        raise HTTPException(
            status_code = 404,
            detail = "Selected cached model is no longer available.",
        )
    return snapshot


async def _require_model_access_or_caller_token(
    model_name: str,
    hf_token,
    *,
    local_path: Optional[str] = None,
    prefer_local_cache: bool = False,
) -> None:
    """Managed access check that also accepts the caller's own Hub token, since a remote preflight
    precedes the first download and its grant. Local and cache-only selections keep the check."""
    if not account_access.managed_account():
        return
    try:
        await asyncio.to_thread(account_access.require_model_access, model_name)
    except HTTPException as exc:
        if (
            exc.status_code != 404
            or local_path
            or prefer_local_cache
            or is_local_path(model_name)
            or not isinstance(hf_token, str)
            or not hf_token.strip()
        ):
            raise
        await asyncio.to_thread(account_access.authorize_download, model_name, "model", hf_token)


def _tensor_split_can_launch(tensor_parallel, flash_attn) -> bool:
    """Only a resolved flash_attn False refuses a tensor split; None is not evidence it would fail."""
    if not tensor_parallel:
        return False
    return flash_attn is not False


@router.get("/config/{model_name:path}")
async def get_model_config(
    model_name: str,
    hf_token: Optional[str] = Query(None),
    prefer_local_cache: bool = False,
    local_path: Optional[str] = None,
    as_decision: bool = False,
    header_hf_token: Optional[str] = Depends(get_hf_token),
    allow_ambient_token: bool = Depends(allow_ambient_hf_token),
    current_subject: str = Depends(get_current_subject),
    via_api_key: bool = Depends(authenticated_via_api_key),
):
    """Get configuration for a specific model (wraps load_model_defaults).

    ``as_decision`` asks for a text or vision LLM as a decision model: a fresh Clef head on it."""
    # An API-key caller is shown a filesystem-backed row under an opaque `ref:` handle and hands
    # it back here, where it would otherwise read as a Hugging Face id.
    from core.inference.npu_backend import is_npu_model_path
    from models.inference import resolve_inventory_handle

    model_name = resolve_inventory_handle(model_name)
    if is_npu_model_path(model_name):
        return ModelDetails(id = model_name, model_name = model_name, model_type = "text")
    if local_path:
        local_path = resolve_inventory_handle(local_path)
    if local_path:
        if account_access.managed_account():
            await asyncio.to_thread(account_access.require_model_access, local_path)
    hf_token = hf_token_arg(
        _normalize_hf_token(header_hf_token) or _normalize_hf_token(hf_token),
        allow_ambient_token = allow_ambient_token and not account_access.managed_account(),
    )
    await _require_model_access_or_caller_token(
        model_name,
        hf_token,
        local_path = local_path,
        prefer_local_cache = prefer_local_cache,
    )
    from core.inference.llama_cpp import _hf_offline_if_unreachable_for
    from utils.models.model_config import shared_hub_model_info
    from utils.utils import pinned_hf_reachability

    def _resolve(model_name: str) -> ModelDetails:
        # Guard wraps all probes so offline they resolve from the HF cache.
        with (
            pinned_hf_reachability(),
            _hf_offline_if_unreachable_for(model_name),
            shared_hub_model_info(),
        ):
            # Inside the guard: it forces offline itself when the Hub is unreachable.
            if not is_local_path(model_name) and anonymous_and_offline(
                hf_token, repo_id = canonical_model_repo_id(model_name)
            ):
                raise HTTPException(status_code = 404, detail = _UNAUTHORIZED_OFFLINE)
            if not is_local_path(model_name):
                resolved = resolve_cached_repo_id_case(model_name)
                if resolved != model_name:
                    logger.info(
                        "Using cached repo_id casing '%s' for requested '%s'",
                        resolved,
                        model_name,
                    )
                model_name = resolved

            logger.info(f"Getting model config for: {model_name}")
            from utils.models.model_config import detect_audio_type_checked

            inspection_target = _model_config_inspection_target(
                model_name,
                prefer_local_cache,
                local_path,
                hf_token,
            )
            config_dict = load_model_defaults(model_name)

            # local_files_only would read config.json from the cache unauthorized; local folders keep it.
            probe_local_only = prefer_local_cache and (
                is_local_path(model_name) or cache_reads_authorized(hf_token, repo_id = model_name)
            )
            is_vision = is_vision_model(
                inspection_target,
                hf_token = hf_token,
                local_files_only = probe_local_only,
            )
            is_embedding = is_embedding_model(inspection_target, hf_token = hf_token)
            layout = decision_layout(
                model_name, hf_token = hf_token, local_files_only = probe_local_only
            )
            is_decision = layout is not None
            decision_checkpoints = None
            if layout == "clef":
                from core.systemone.catalog import CLEF_DEFAULTS_REPO

                # Local Clef folders and Studio fine-tunes start from Clef-flash's recipe.
                if config_dict == load_model_defaults("default"):
                    config_dict = load_model_defaults(CLEF_DEFAULTS_REPO)
            elif is_decision:
                from core.systemone.catalog import CHECKPOINTS, LAYA_REPO
                config_dict = load_model_defaults(LAYA_REPO)
                decision_checkpoints = [
                    {"name": c.name, "subfolder": c.subfolder, "description": c.description}
                    for c in CHECKPOINTS.values()
                    if c.source == model_name
                ] or None
            audio_type, audio_type_definitive = detect_audio_type_checked(
                _audio_probe_target(inspection_target),
                hf_token = hf_token,
                local_files_only = probe_local_only,
            )

            is_lora = False
            base_model = None
            max_position_embeddings = None
            try:
                model_config = ModelConfig.from_identifier(
                    inspection_target,
                    hf_token = hf_token,
                )
                is_lora = model_config.is_lora
                base_model = model_config.base_model if is_lora else None
                max_position_embeddings = _get_max_position_embeddings(model_config)
            except Exception:
                pass

            # Fallback: raw config.json (declarative fields only) -- must never run a repo's auto_map.
            if max_position_embeddings is None:
                try:
                    from utils.transformers_version import _load_config_json
                    from types import SimpleNamespace

                    _cfg = _load_config_json(inspection_target, hf_token = hf_token)
                    if _cfg is not None:

                        def _to_ns(d):
                            if isinstance(d, dict):
                                return SimpleNamespace(**{k: _to_ns(v) for k, v in d.items()})
                            return d

                        max_position_embeddings = _get_max_position_embeddings(_to_ns(_cfg))
                except Exception:
                    pass

            if (
                as_decision
                and not is_decision
                and not (is_embedding or is_lora or audio_type is not None)
            ):
                from utils.models.model_config import load_llm_decision_defaults
                is_decision, layout = True, "llm"
                config_dict = load_llm_decision_defaults()

            from utils.models.training_defaults import model_training_recommendations

            config_dict = model_training_recommendations(
                config_dict,
                is_vision = is_vision,
                is_audio = audio_type is not None,
                is_embedding = is_embedding,
                is_decision = is_decision,
            )
            logger.info(
                f"Model config result for {model_name}: is_vision={is_vision}, is_embedding={is_embedding}, audio_type={audio_type}, audio_type_known={audio_type_definitive}, is_lora={is_lora}, max_position_embeddings={max_position_embeddings}"
            )
            return ModelDetails(
                id = model_name,
                model_name = model_name,
                config = config_dict,
                is_vision = is_vision,
                is_embedding = is_embedding,
                is_decision = is_decision,
                decision_layout = layout,
                decision_checkpoints = decision_checkpoints,
                is_lora = is_lora,
                is_audio = audio_type is not None,
                audio_type = audio_type,
                audio_type_known = audio_type_definitive,
                has_audio_input = is_audio_input_type(audio_type),
                model_type = derive_model_type(is_vision, audio_type, is_embedding, is_decision),
                base_model = base_model,
                max_position_embeddings = max_position_embeddings,
                # Keyed on the target, not the flag: an anonymous caller's bare repo id sizes as None.
                model_size_bytes = (
                    _get_snapshot_model_size_bytes(inspection_target)
                    if prefer_local_cache and inspection_target != model_name
                    else _get_model_size_bytes(model_name, hf_token)
                ),
            )

    try:
        # Off-loop: the guard blocks on DNS + HEAD + TCP. The caller's identifier is echoed, not
        # referenced: referencing it would make this route an oracle for their other references.
        from hub.utils.host_paths import redact_host_paths, restore_inventory_handles
        return redact_host_paths(
            restore_inventory_handles(await asyncio.to_thread(_resolve, model_name)),
            via_api_key = via_api_key,
            echo = (model_name,),
        )

    except HTTPException:
        raise
    except Exception as e:
        raise log_and_http_error(
            e,
            500,
            "Failed to get model config",
            event = "models.get_model_config_failed",
            log = logger,
        )


def _consent_provider(
    model_name: str,
    scanned_targets: List[str],
    external_refs: Optional[List[str]] = None,
) -> Optional[str]:
    """HF org for the consent dialog's `from "<provider>"` tag, or None. Only a single, non-local,
    canonical ``owner/repo`` id yields one; a LoRA's extra base, a local path, or an external
    ``auto_map`` ref yields None so the dialog never misattributes scanned code."""
    if len(scanned_targets) != 1 or external_refs or is_local_path(model_name):
        return None
    parts = model_name.split("/")
    return parts[0] if len(parts) == 2 and all(parts) else None


@router.post("/remote-code-scan")
async def scan_model_remote_code(
    model_name: str = Body(..., embed = True),
    hf_token: Optional[str] = Body(None, embed = True),
    prefer_local_cache: bool = Body(False, embed = True),
    model_local_path: Optional[str] = Body(None, embed = True),
    model_snapshot_path: Optional[str] = Body(None, embed = True),
    model_snapshot_repo_id: Optional[str] = Body(None, embed = True),
    allow_ambient_token: bool = Depends(allow_ambient_hf_token),
    current_subject: str = Depends(get_current_subject),
):
    """Scan a model's ``auto_map`` custom code so the UI can show findings before
    the user enables ``trust_remote_code``. Code-free: reads ``config.json`` and
    statically scans the repo ``.py`` (never loads the model). Returns
    ``has_remote_code`` plus the severity-tagged findings + a pinning fingerprint.

    POST (not GET) so the ``hf_token`` for gated repos travels in the body and
    never lands in a URL, browser history, or access log.
    """
    # Before the access checks, so they run on the resolved path.
    from models.inference import resolve_inventory_handle

    model_name = resolve_inventory_handle(model_name)
    model_local_path = resolve_inventory_handle(model_local_path) if model_local_path else None
    model_snapshot_path = (
        resolve_inventory_handle(model_snapshot_path) if model_snapshot_path else None
    )
    model_snapshot_repo_id = (
        resolve_inventory_handle(model_snapshot_repo_id) if model_snapshot_repo_id else None
    )
    if account_access.managed_account():
        for ref in (model_name, model_local_path, model_snapshot_path, model_snapshot_repo_id):
            if isinstance(ref, str) and ref:
                await asyncio.to_thread(account_access.require_model_access, ref)
        allow_ambient_token = False
    # An absent token would read as ambient-authorized and leak private cached source.
    hf_token = hf_token_arg(hf_token, allow_ambient_token = allow_ambient_token)
    # Offline the scanner reads cached config/Python and returns source snippets.
    if not is_local_path(model_name) and anonymous_and_offline(
        hf_token, repo_id = canonical_model_repo_id(model_name)
    ):
        raise HTTPException(status_code = 404, detail = _UNAUTHORIZED_OFFLINE)
    try:
        from utils.security import (
            load_scan_target,
            preflight_remote_code_consent_for_targets,
            security_load_subdirs,
        )

        local_model = is_local_path(model_name)
        if not local_model:
            model_name = resolve_cached_repo_id_case(model_name)

        # hf_hub_download resolves cached configs without the credential; fail closed here,
        # not in _repo_in_any_hf_cache, whose other caller needs its False.
        def _repo_maybe_cached(repo: str) -> bool:
            """Probes the scanner inputs in the active hub cache, not config.json alone; fails closed"""
            try:
                if not _repo_in_any_hf_cache(repo):
                    return False
            except Exception:
                return True
            try:
                from huggingface_hub import try_to_load_from_cache
                from utils.hf_cache_settings import active_hf_hub_cache
                from utils.security.remote_code_scan import remote_code_config_paths

                cache_dir = active_hf_hub_cache()
                return any(
                    isinstance(
                        try_to_load_from_cache(repo_id = repo, filename = name, cache_dir = cache_dir),
                        str,
                    )
                    for name in remote_code_config_paths()
                )
            except Exception:
                return True

        if not local_model and cached_read_refused(
            hf_token, repo_id = model_name, is_cached = lambda: _repo_maybe_cached(model_name)
        ):
            raise HTTPException(
                status_code = 404,
                detail = _UNAUTHORIZED_CACHED_MODEL,
            )
        scan_target = model_name
        exact_snapshot_path = (
            model_snapshot_path.strip()
            if isinstance(model_snapshot_path, str) and model_snapshot_path.strip()
            else None
        )
        exact_snapshot_repo_id = model_name
        if isinstance(model_snapshot_repo_id, str):
            snapshot_repo_id = model_snapshot_repo_id.strip()
            # Namespace-less Hub ids like "gpt2" are valid, so use the shared validator, not the regex.
            from hub.utils.paths import is_valid_repo_id as _shared_is_valid_repo_id

            if snapshot_repo_id and not _shared_is_valid_repo_id(snapshot_repo_id):
                raise HTTPException(
                    status_code = 400,
                    detail = "Invalid model snapshot repository ID.",
                )
            if snapshot_repo_id:
                exact_snapshot_repo_id = snapshot_repo_id
        if local_model:
            normalized_model_name = normalize_path(model_name)
            try:
                scan_target = str(Path(normalized_model_name).expanduser().resolve(strict = False))
            except (OSError, RuntimeError, ValueError):
                scan_target = normalized_model_name
        if exact_snapshot_path and not local_model:
            exact_snapshot_repo_id = resolve_cached_repo_id_case(exact_snapshot_repo_id)
            scan_target = _model_config_inspection_target(
                exact_snapshot_repo_id,
                True,
                normalize_path(exact_snapshot_path),
                hf_token,
            )
        elif (
            prefer_local_cache is True
            and not local_model
            and cache_reads_authorized(hf_token, repo_id = model_name)
        ):
            # Resolving to a cached snapshot would hand over a private repo's Python unauthorized.
            from core.training.training import _resolve_model_snapshot
            local_path = normalize_path(model_local_path) if model_local_path else None
            scan_target = _resolve_model_snapshot(model_name, local_path) or model_name
        # Snapshot the primary's cache state before resolving the base, which downloads
        # adapter_config.json and would hide it from cleanup on decline.
        primary_cache_target, _ = load_scan_target(scan_target, ())
        try:
            _primary_preexisting = is_local_path(primary_cache_target) or _repo_in_any_hf_cache(
                primary_cache_target
            )
        except Exception:
            _primary_preexisting = True
        requested_scan_target = scan_target
        from core.inference.native_audio import native_audio_security_targets

        try:
            requested_security_targets = native_audio_security_targets(
                requested_scan_target, hf_token = hf_token
            )
        except ValueError as exc:
            raise HTTPException(status_code = 400, detail = str(exc)) from exc
        try:
            from utils.models.model_config import get_base_model_from_lora_identifier

            # Resolve a LOCAL or REMOTE adapter's base so its code/weights are scanned too.
            _base = get_base_model_from_lora_identifier(requested_scan_target, hf_token)
            if _base:
                requested_security_targets.append(_base)
        except Exception:
            pass
        security_targets: list[str] = []
        consent_load_subdirs: dict[str, tuple] = {}
        for _requested_target in dict.fromkeys(requested_security_targets):
            _subdirs = security_load_subdirs(_requested_target, hf_token)
            if _requested_target == requested_scan_target and requested_scan_target != model_name:
                _subdirs = tuple(
                    dict.fromkeys((*_subdirs, *security_load_subdirs(model_name, hf_token)))
                )
            _target, _subdirs = load_scan_target(_requested_target, _subdirs)
            # A different repo than the one authorized; refuse rather than silently skip the scan.
            if not is_local_path(_target) and cached_read_refused(
                hf_token, repo_id = _target, is_cached = lambda t = _target: _repo_maybe_cached(t)
            ):
                raise HTTPException(
                    status_code = 404,
                    detail = _UNAUTHORIZED_CACHED_MODEL,
                )
            if _target not in consent_load_subdirs:
                security_targets.append(_target)
                consent_load_subdirs[_target] = ()
            _subdirs = tuple(dict.fromkeys((*consent_load_subdirs[_target], *_subdirs)))
            consent_load_subdirs[_target] = _subdirs
        # Record repos our scan first pulls in, computed before preflight, so decline purges only those.
        from utils.security.remote_code_scan import external_auto_map_repos, shared_config_reads

        scan_created_repos: list = []
        _seen_created: set = set()

        def _mark_scan_created(repo: str, *, preexisting: Optional[bool] = None) -> None:
            if not repo or repo in _seen_created:
                return
            _seen_created.add(repo)
            try:
                already = (
                    preexisting
                    if preexisting is not None
                    else (is_local_path(repo) or _repo_in_any_hf_cache(repo))
                )
                if not already:
                    scan_created_repos.append(repo)
            except Exception:
                pass

        external_refs: list = []
        # One advisory scan: its passes share each config read; the load-time gates re-read fresh.
        with shared_config_reads():
            for _target in security_targets:
                # Use the pre-base-resolution snapshot for the primary (see above).
                _mark_scan_created(
                    _target,
                    preexisting = _primary_preexisting if _target == primary_cache_target else None,
                )
                for _ext in external_auto_map_repos(
                    _target,
                    hf_token,
                    load_subdirs = consent_load_subdirs[_target],
                ):
                    # Found after authorization: refuse like the base, else its cached Python leaks as source snippets
                    if not is_local_path(_ext) and cached_read_refused(
                        hf_token, repo_id = _ext, is_cached = lambda e = _ext: _repo_maybe_cached(e)
                    ):
                        raise HTTPException(
                            status_code = 404,
                            detail = _UNAUTHORIZED_CACHED_MODEL,
                        )
                    external_refs.append(_ext)
                    _mark_scan_created(_ext)
            decision = preflight_remote_code_consent_for_targets(
                security_targets,
                hf_token = hf_token,
                subject = current_subject,
                load_subdirs_by_target = consent_load_subdirs,
            )
        payload = decision.response_payload()
        blocks = (
            [(payload.get("block_cause"), payload.get("model_name"))]
            if payload.get("block_cause")
            else []
        )
        payload["model_name"] = exact_snapshot_repo_id if exact_snapshot_path else model_name
        payload["requires_trust_remote_code"] = decision.has_remote_code
        # Prior approval lets the dialog be skipped; the scan still ran, so this is a real match.
        payload["already_approved"] = (
            decision.has_remote_code
            and not decision.blocked
            and decision.reason == "approved by fingerprint"
        )
        # created_by_scan = primary flag (older clients); scan_created_repos drives cleanup.
        payload["created_by_scan"] = primary_cache_target in scan_created_repos
        payload["scan_created_repos"] = scan_created_repos
        # Provider tag decided here, where locality/scan scope/external refs are known.
        provider_target = exact_snapshot_repo_id if exact_snapshot_path else model_name
        if requested_scan_target == model_name and primary_cache_target != model_name:
            provider_target = primary_cache_target
        payload["provider"] = _consent_provider(provider_target, security_targets, external_refs)

        # Malware gate (metadata-only): HF-flagged unsafe files, orthogonal to remote code.
        from utils.security import evaluate_file_security

        unsafe_files: list = []
        security_blocked = False
        for _target in security_targets:
            _sec = evaluate_file_security(
                _target,
                hf_token = hf_token,
                load_subdirs = consent_load_subdirs[_target],
            )
            security_blocked = security_blocked or _sec.blocked
            unsafe_files.extend(_sec.unsafe_files)
            if _sec.blocked:
                blocks.append((_sec.block_cause, _sec.model_name))
        payload["unsafe_files"] = unsafe_files
        payload["security_blocked"] = security_blocked
        if security_blocked:
            # Non-approvable hard block: hides "Enable and continue" while forcing the dialog open.
            payload["approvable"] = False
            payload["requires_trust_remote_code"] = True
            payload["error_kind"] = "malware_blocked"
        from utils.hub_settings import active_source_label
        from utils.security.file_security import NOT_ON_SOURCE, strongest_block

        block_cause, block_target = strongest_block(blocks)
        payload["block_cause"] = block_cause
        # A repo the source lacks declares nothing, but the load still stops at the dialog.
        if block_cause:
            payload["requires_trust_remote_code"] = True
        payload["block_source"] = active_source_label()
        payload["block_target"] = block_target if block_cause == NOT_ON_SOURCE else None
        # The findings quote paths inside the model directory.
        from hub.utils.host_paths import restore_inventory_handles

        return restore_inventory_handles(payload)
    except HTTPException:
        raise
    except Exception as e:
        raise log_and_http_error(
            e,
            500,
            "Failed to scan model remote code",
            event = "models.remote_code_scan_failed",
            log = logger,
        )


@router.post("/discard-remote-code")
async def discard_remote_code_download(
    model_name: str = Body(..., embed = True), current_subject: str = Depends(get_current_subject)
):
    """Purge a repo the consent scan downloaded after the user DECLINED its custom
    code, so untrusted code is not left on disk.

    Safety: only ever deletes a metadata-only cache entry the scan created. It
    refuses a local path (never touches user files), a currently-loaded model, and
    any repo that has weight files cached (``*.safetensors`` / ``*.bin`` /
    ``*.gguf``) -- i.e. a model the user actually downloaded. The frontend only
    calls this when the scan reported ``created_by_scan``.
    """
    account_access.require_installation_owner()
    if is_local_path(model_name):
        return {"deleted": False, "reason": "local"}
    if not _is_valid_repo_id(model_name):
        return {"deleted": False, "reason": "invalid"}

    try:
        from hub.services.models.deletion import _loaded_id_matches_repo
        from core.inference import model_slots
        from routes.inference import get_llama_cpp_backend

        for llama_backend in (
            get_llama_cpp_backend(),
            *(slot.llama for slot in model_slots.resident()),
        ):
            if llama_backend.is_loaded and llama_backend.model_identifier:
                if _loaded_id_matches_repo(llama_backend.model_identifier, model_name):
                    return {"deleted": False, "reason": "loaded"}
    except Exception:
        pass
    try:
        # Peek, not construct: no orchestrator means no active model, and building one hits get_device().
        from core.inference.orchestrator import peek_inference_backend
        from core.inference import model_slots
        for inference_backend in (
            peek_inference_backend(),
            *(slot.orchestrator for slot in model_slots.resident()),
        ):
            if inference_backend is not None and inference_backend.active_model_name:
                if _loaded_id_matches_repo(inference_backend.active_model_name, model_name):
                    return {"deleted": False, "reason": "loaded"}
    except Exception:
        pass

    _WEIGHTS = (
        ".safetensors",
        ".bin",
        ".pt",
        ".pth",
        ".h5",
        ".msgpack",
        ".gguf",
        ".onnx",
        ".ckpt",
    )
    try:
        target_repo = None
        hf_cache = None
        for cache in _all_hf_cache_scans():
            for repo_info in cache.repos:
                if repo_info.repo_type != "model":
                    continue
                if repo_info.repo_id.lower() == model_name.lower():
                    target_repo, hf_cache = repo_info, cache
                    break
            if target_repo is not None:
                break

        if target_repo is None:
            return {"deleted": False, "reason": "not_cached"}

        # Hard guard: a repo with weights is a real model the user has -- leave it.
        if any(f.file_name.lower().endswith(_WEIGHTS) for f in _cached_files(target_repo)):
            return {"deleted": False, "reason": "has_weights"}

        revision_hashes = [rev.commit_hash for rev in target_repo.revisions]
        if not revision_hashes:
            return {"deleted": False, "reason": "not_cached"}
        hf_cache.delete_revisions(*revision_hashes).execute()
        logger.info("Discarded declined remote-code download: %s", model_name)
        return {"deleted": True}
    except Exception as e:
        logger.warning("Could not discard remote-code download for %s: %s", model_name, e)
        return {"deleted": False, "reason": "error"}


def _audio_probe_target(inspection_target: str) -> str:
    """Curated aliases name a load subdirectory, not a repo, so resolve the alias before probing."""
    if is_local_path(inspection_target):
        return inspection_target
    try:
        from utils.security import load_scan_target
        repo_id, _load_subdirs = load_scan_target(canonical_model_repo_id(inspection_target), ())
        return repo_id or inspection_target
    except Exception:  # noqa: BLE001 - a probe target must never fail the handler
        return inspection_target


def _audio_type_of_checkpoint(
    model_path: str,
    base_model: Optional[str],
    hf_token: Optional[str] = None,
) -> Optional[str]:
    """Scan rows lack modality: detect from the checkpoint first, then the base repo an adapter names"""
    from utils.models.model_config import detect_audio_type

    for candidate in (model_path, base_model):
        if not candidate:
            continue
        try:
            # local_files_only avoids re-fetching uncached misses every poll; pass hf_token since
            # capability caches are keyed by token fingerprint.
            audio_type = detect_audio_type(candidate, hf_token = hf_token, local_files_only = True)
        except Exception as exc:  # never let a scan row fail the whole listing
            logger.debug("audio detection failed for %r: %s", candidate, exc)
            continue
        if audio_type:
            return audio_type
    return None


@router.get("/loras")
async def scan_loras(
    outputs_dir: str = Query(
        default = str(outputs_root()), description = "Directory to scan for LoRA adapters"
    ),
    exports_dir: str = Query(
        default = str(exports_root()), description = "Directory to scan for exported models"
    ),
    hf_token: HfTokenArg = Depends(get_request_hf_token),
    current_subject: str = Depends(get_current_subject),
):
    """Scan for trained LoRA adapters and exported models.

    Returns training outputs (outputs_dir) and exported models
    (exports_dir) in one list, distinguished by the source field.
    """
    exports_dir = account_access.private_directory(exports_dir, "exports")
    outputs_dir = account_access.private_directory(outputs_dir, "outputs")
    try:
        resolved_outputs_dir = str(resolve_output_dir(outputs_dir))
        resolved_exports_dir = str(resolve_export_dir(exports_dir))
        # Off the loop: the directory walk and per-checkpoint tokenizer reads can stall streamed tokens too.
        lora_list = await asyncio.to_thread(
            _scan_loras_sync, resolved_outputs_dir, resolved_exports_dir, hf_token
        )

        return LoRAScanResponse(loras = lora_list, outputs_dir = resolved_outputs_dir)

    except Exception as e:
        raise log_and_http_error(
            e,
            500,
            "Failed to scan LoRA adapters",
            event = "models.scan_loras_failed",
            log = logger,
        )


def _disk_bytes(model_path: str, export_type: Optional[str]) -> Optional[int]:
    """Bytes a fine-tune takes on disk. A GGUF export counts its whole folder."""
    path = Path(model_path)
    if export_type == "gguf" and path.is_file():
        path = path.parent
    try:
        if path.is_file():
            return path.stat().st_size
        total = 0
        for root, _dirs, files in os.walk(path):
            for name in files:
                try:
                    total += os.lstat(os.path.join(root, name)).st_size
                except OSError:
                    continue
        return total
    except OSError:
        return None


def _scan_loras_sync(
    resolved_outputs_dir: str, resolved_exports_dir: str, hf_token: Optional[str]
) -> List[LoRAInfo]:
    from utils.models.checkpoints import parse_adapter_features

    lora_list: List[LoRAInfo] = []

    trained_models = scan_trained_models(outputs_dir = resolved_outputs_dir)
    for display_name, model_path, model_type in trained_models:
        base_model = get_base_model_from_checkpoint(model_path)
        lora_list.append(
            LoRAInfo(
                display_name = display_name,
                adapter_path = model_path,
                base_model = base_model,
                source = "training",
                export_type = model_type,
                size_bytes = _disk_bytes(model_path, model_type),
                audio_type = _audio_type_of_checkpoint(model_path, base_model, hf_token),
                adapter_features = parse_adapter_features(model_path),
            )
        )

    exported = scan_exported_models(exports_dir = resolved_exports_dir)
    for display_name, model_path, export_type, base_model in exported:
        lora_list.append(
            LoRAInfo(
                display_name = display_name,
                adapter_path = model_path,
                base_model = base_model,
                source = "exported",
                export_type = export_type,
                size_bytes = _disk_bytes(model_path, export_type),
                audio_type = _audio_type_of_checkpoint(model_path, base_model, hf_token),
                adapter_features = parse_adapter_features(model_path),
            )
        )

    return lora_list


@router.get("/diffusion-loras")
async def scan_diffusion_loras(
    family: Optional[str] = Query(
        default = None, description = "Filter to LoRAs compatible with this diffusion family"
    ),
    current_subject: str = Depends(get_current_subject),
):
    """List diffusion image LoRA adapters for the Images workflow.

    Merges the curated catalog with local files in ``<studio_home>/loras/diffusion``,
    optionally filtered to the loaded model's family. Cheap: one directory scan, no network
    (a hub adapter is only downloaded when actually selected for a generation). Distinct from
    ``/loras`` above, which lists trained/exported TEXT adapters.
    """
    from core.inference import diffusion_lora

    entries = await asyncio.to_thread(diffusion_lora.list_loras, family = family)
    if account_access.managed_account():
        entries = await asyncio.to_thread(account_access.filter_model_rows, entries)
    return {
        "loras": [
            {
                "id": e.id,
                "display_name": e.display_name,
                "source": e.source,
                "format": e.fmt,
                "families": list(e.families),
                "size_bytes": e.size_bytes,
                "weight_default": e.weight_default,
                "fine_tuned": e.fine_tuned,
            }
            for e in entries
        ],
        "loras_dir": str(diffusion_lora.loras_dir()),
    }


@router.get("/diffusion-embeddings")
async def scan_diffusion_embeddings(
    family: Optional[str] = Query(
        default = None, description = "Filter to embeddings this diffusion family can use"
    ),
    current_subject: str = Depends(get_current_subject),
):
    """List textual-inversion embeddings in ``<studio_home>/embeddings/diffusion`` for the Images page.

    The filename stem is the trigger word: naming it in a prompt or negative prompt uses the embedding.
    ``family`` keeps only files of that family's format (an unknown family, or one without embeddings,
    lists none). One directory scan reading safetensors headers only; no network.
    """
    from core.inference import diffusion_embeddings

    kind = None
    if family:
        fam = next((f for f in _diffusion_families() if f.name == family.strip().lower()), None)
        kind = getattr(fam, "textual_inversion", None) if fam is not None else None
    entries = (
        await asyncio.to_thread(diffusion_embeddings.list_embeddings, kind)
        if kind is not None or not family
        else []
    )
    return {
        "embeddings": [
            {
                "id": e.id,
                "trigger": e.id,
                "kind": e.kind,
                "vectors": e.vectors,
                "size_bytes": e.size_bytes,
            }
            for e in entries
        ],
        "embeddings_dir": str(diffusion_embeddings.embeddings_dir()),
    }


def _diffusion_families():
    from core.inference.diffusion_families import _FAMILIES
    return _FAMILIES


@router.get("/diffusion-controlnets")
async def scan_diffusion_controlnets(
    family: Optional[str] = Query(
        default = None, description = "Filter to ControlNets compatible with this diffusion family"
    ),
    current_subject: str = Depends(get_current_subject),
):
    """List diffusion ControlNet models for the Images workflow.

    Merges the curated, family-tagged catalog with local model folders in
    ``<studio_home>/controlnets/diffusion``, optionally filtered to the loaded model's family.
    Cheap: one directory scan, no network (a hub model is only downloaded when selected).
    """
    from core.inference import diffusion_controlnet

    entries = diffusion_controlnet.list_controlnets(family = family)
    if account_access.managed_account():
        entries = await asyncio.to_thread(account_access.filter_model_rows, entries)
    return {
        "controlnets": [
            {
                "id": e.id,
                "display_name": e.display_name,
                "source": e.source,
                "families": list(e.families),
                "control_types": list(e.control_types),
                "is_union": e.is_union,
            }
            for e in entries
        ],
        "control_types": list(diffusion_controlnet.CONTROL_TYPES),
        "controlnets_dir": str(diffusion_controlnet.controlnets_dir()),
    }


def _is_path_under(path: Path, root: Path) -> bool:
    try:
        path.resolve().relative_to(root.resolve())
        return True
    except ValueError:
        return False


def _is_path_under_lexically(path: Path, root: Path) -> bool:
    """Check containment without resolving the final path's symlink."""
    try:
        absolute_path = Path(os.path.abspath(str(path)))
        absolute_root = Path(os.path.abspath(str(root)))
        absolute_path.relative_to(absolute_root)
        return True
    except ValueError:
        return False


def _loaded_model_matches_deleted_path(active_model: str, deleted_path: Path) -> bool:
    try:
        active = Path(active_model).expanduser().resolve()
        target = deleted_path.resolve()
        return active == target or (target.is_dir() and active.is_relative_to(target))
    except (OSError, RuntimeError, ValueError) as e:
        logger.debug(
            "Could not resolve loaded/deleted model paths; falling back to string comparison: %s",
            e,
        )
        active_lower = active_model.lower()
        target_lower = str(deleted_path).lower()
        return active_lower == target_lower or active_lower.startswith(f"{target_lower}{os.sep}")


def _loading_model_matches_deleted_path(loading_model: object, deleted_path: Path) -> bool:
    if not loading_model:
        return False
    return _loaded_model_matches_deleted_path(str(loading_model), deleted_path)


def _active_diffusion_backend():
    """The live Images engine, or None when this install has no diffusion stack. Fails OPEN on import: a
    chat-only install (no diffusers) must still be able to delete its fine-tuned models. Reading the
    returned backend's state is what fails closed."""
    try:
        from core.inference.diffusion_engine_router import get_active_diffusion_engine
        return get_active_diffusion_engine()
    except Exception as e:
        logger.debug(f"Images engine unavailable during delete guard: {e}")
        return None


def _active_video_backend():
    try:
        from core.inference.video import get_video_backend
        return get_video_backend()
    except Exception as e:
        logger.debug(f"Video backend unavailable during delete guard: {e}")
        return None


def _forget_gone_library_entries(source: str, folder: Path) -> None:
    """Drop Library entries of deleted models so new models at that path inherit nothing; errors only log"""
    try:
        from storage import library_db
        prefix = f"model:{source}:"
        for item_id in library_db.list_entries():
            path = item_id[len(prefix) :] if item_id.startswith(prefix) else ""
            if path and not os.path.lexists(path) and _is_path_under(Path(path), folder):
                library_db.delete_entry(item_id)
    except Exception as e:
        logger.warning("Could not clear the Library entries under %s: %s", folder, e)


def _prune_empty_parents(start: Path, stop_at: Path) -> None:
    """Remove empty ancestors of ``start`` up to (not including) ``stop_at``, so the enclosing run dir
    does not linger as an empty entry in scan results."""
    try:
        stop_resolved = stop_at.resolve()
    except OSError:
        return
    parent = start.parent
    while True:
        try:
            parent_resolved = parent.resolve()
        except OSError:
            return
        if parent_resolved == stop_resolved:
            return
        try:
            parent_resolved.relative_to(stop_resolved)
        except ValueError:
            return
        try:
            parent.rmdir()
        except OSError:
            return
        parent = parent.parent


def _variant_names_same_checkpoint(a: Optional[str], b: Optional[str]) -> bool:
    """Deliberately loose: a false match only refuses a delete, while a false miss could lose weights."""
    from hub.utils.gguf import bare_quant_alias, is_qualified_gguf_variant_key

    left = (a or "").strip().lower()
    right = (b or "").strip().lower()
    if not left or not right:
        return False
    if left == right:
        return True
    for key, bare in ((left, right), (right, left)):
        if (
            is_qualified_gguf_variant_key(key)
            and not is_qualified_gguf_variant_key(bare)
            and bare_quant_alias(key).lower() == bare
        ):
            return True
    return False


def _delete_gguf_variant_files(root: Path, variant: str) -> tuple[int, int]:
    deleted_count = 0
    deleted_bytes = 0
    from hub.utils.gguf import remove_appledouble_sidecar

    from hub.utils.gguf import gguf_variant_keys_by_checkpoint

    weights: list[tuple[Path, str]] = []
    for path in root.rglob("*"):
        if not path.is_file() or not _is_main_gguf_filename(path.name):
            continue
        # proven AppleDouble metadata is removed with its weight, not counted as a model.
        if is_appledouble_metadata(path):
            continue
        try:
            relative = path.relative_to(root).as_posix()
        except ValueError:
            relative = path.name
        weights.append((path, relative))
    # checkpoint-qualified keys isolate sibling builds that share a quant.
    keys = gguf_variant_keys_by_checkpoint(relative for _path, relative in weights)
    for path, relative in weights:
        if keys[relative].lower() != variant.lower():
            continue
        try:
            deleted_bytes += path.stat().st_size
        except OSError:
            pass
        path.unlink()
        deleted_bytes += remove_appledouble_sidecar(path)
        deleted_count += 1
    return deleted_count, deleted_bytes


@router.delete("/delete-finetuned")
async def delete_finetuned_model(
    model_path: str = Body(...),
    source: str = Body(...),
    export_type: Optional[str] = Body(None),
    gguf_variant: Optional[str] = Body(None),
    current_subject: str = Depends(get_current_subject),
):
    """delete an Unsloth output, or one quant from an exported GGUF, within approved roots."""
    if source not in {"training", "exported"}:
        raise HTTPException(
            status_code = 400,
            detail = "Only trained or exported Unsloth models can be deleted",
        )

    if not model_path or not model_path.strip():
        raise HTTPException(status_code = 400, detail = "model_path is required")

    if export_type == "gguf" and not gguf_variant:
        raise HTTPException(
            status_code = 400,
            detail = "gguf_variant is required when export_type is 'gguf'",
        )

    raw_path = Path(model_path).expanduser()
    if source == "training":
        target_path = raw_path
        allowed_root = outputs_root()
    else:
        allowed_root = exports_root()
        target_path = (
            raw_path.parent
            if export_type == "gguf" and raw_path.suffix.lower() == ".gguf"
            else raw_path
        )

    allowed_root = allowed_root.resolve()
    delete_path = Path(os.path.abspath(str(target_path)))
    delete_path_is_symlink = delete_path.is_symlink()

    if delete_path_is_symlink:
        if not _is_path_under_lexically(delete_path, allowed_root):
            raise HTTPException(
                status_code = 400,
                detail = "Model path is outside Unsloth storage",
            )
        if export_type == "gguf" and gguf_variant:
            target_path = delete_path.resolve()
            if not _is_path_under(target_path, allowed_root):
                raise HTTPException(
                    status_code = 400,
                    detail = "Model path is outside Unsloth storage",
                )
        else:
            target_path = delete_path
    else:
        target_path = target_path.resolve()

    should_check_resolved_path = not delete_path_is_symlink or (
        export_type == "gguf" and gguf_variant
    )
    if should_check_resolved_path and not _is_path_under(target_path, allowed_root):
        raise HTTPException(
            status_code = 400,
            detail = "Model path is outside Unsloth storage",
        )
    if target_path == allowed_root:
        raise HTTPException(
            status_code = 400,
            detail = "Refusing to delete storage root",
        )
    if not target_path.exists() and not target_path.is_symlink():
        raise HTTPException(status_code = 404, detail = "Model not found on disk")

    if source == "training":
        try:
            from core.training import get_training_backend

            training_backend = get_training_backend()
            if training_backend.is_training_active():
                raise HTTPException(
                    status_code = 409,
                    detail = "Cannot delete trained models while training is running",
                )
            # Diffusion trainer is a separate run on the same root: check it or rmtree may hit its live output
            from core.training.diffusion_training_service import get_diffusion_training_service

            if get_diffusion_training_service().is_active():
                raise HTTPException(
                    status_code = 409,
                    detail = (
                        "Cannot delete trained models while diffusion (Images) training is running"
                    ),
                )
        except HTTPException:
            raise
        except Exception as e:
            logger.warning("Could not check training status before delete: %s", e)
            raise HTTPException(
                status_code = 500,
                detail = "Could not verify training status before deleting",
            ) from e

    try:
        from core.inference import model_slots
        from routes.inference import get_llama_cpp_backend

        kept = model_slots.resident()
        filling = model_slots.filling_model()
        if filling and _loaded_model_matches_deleted_path(filling, target_path):
            raise HTTPException(
                status_code = 409,
                detail = "Cannot delete a model while it is loading",
            )
        for llama_backend in (get_llama_cpp_backend(), *(slot.llama for slot in kept)):
            if (
                (llama_backend.is_active or llama_backend.is_loaded)
                and llama_backend.model_identifier
                and _loaded_model_matches_deleted_path(
                    llama_backend.model_identifier,
                    target_path,
                )
                and (
                    not gguf_variant
                    or not llama_backend.hf_variant
                    # Alias-aware: a literal compare would pass the bare-quant spelling the delete accepts.
                    or _variant_names_same_checkpoint(llama_backend.hf_variant, gguf_variant)
                )
            ):
                if llama_backend.is_loaded:
                    raise HTTPException(
                        status_code = 400,
                        detail = "Unload the model before deleting",
                    )
                raise HTTPException(
                    status_code = 409,
                    detail = "Cannot delete a model while it is loading",
                )
        # Peek: building an orchestrator to learn there is none reaches get_device() (a torch import).
        from core.inference.orchestrator import peek_inference_backend

        for inference_backend in (peek_inference_backend(), *(slot.orchestrator for slot in kept)):
            if inference_backend is None:
                continue
            loading_models = getattr(inference_backend, "loading_models", set())
            if any(
                _loading_model_matches_deleted_path(loading_model, target_path)
                for loading_model in loading_models
            ):
                raise HTTPException(
                    status_code = 409,
                    detail = "Cannot delete a model while it is loading",
                )
            if inference_backend.active_model_name and _loaded_model_matches_deleted_path(
                inference_backend.active_model_name,
                target_path,
            ):
                raise HTTPException(
                    status_code = 400,
                    detail = "Unload the model before deleting",
                )
    except HTTPException:
        raise
    except Exception as e:
        logger.warning("Could not check the loaded models before delete: %s", e)
        raise HTTPException(
            status_code = 503,
            detail = "Could not verify model load status before deleting",
        ) from e

    # Images / Video hold their own pipelines; rmtree would pull weights from a live engine.
    for label, get_backend in (
        ("Images", _active_diffusion_backend),
        ("Video", _active_video_backend),
    ):
        backend = get_backend()
        if backend is None:
            continue
        try:
            status = backend.status()
            held = (
                [status.get(key) for key in ("repo_id", "base_repo")]
                if status.get("loaded")
                else []
            )
            held += list(getattr(backend, "loaded_repo_ids", tuple)())
            if any(h and _loaded_model_matches_deleted_path(str(h), target_path) for h in held):
                raise HTTPException(
                    status_code = 400,
                    detail = "Unload the model before deleting",
                )
            if any(
                _loading_model_matches_deleted_path(lid, target_path)
                for lid in getattr(backend, "loading_repo_ids", tuple)()
            ):
                raise HTTPException(
                    status_code = 409,
                    detail = "Cannot delete a model while it is loading",
                )
        except HTTPException:
            raise
        except Exception as e:
            logger.warning("Could not check the %s model before delete: %s", label, e)
            raise HTTPException(
                status_code = 503,
                detail = "Could not verify model load status before deleting",
            ) from e

    try:
        if export_type == "gguf" and gguf_variant:
            if not target_path.is_dir():
                raise HTTPException(
                    status_code = 400,
                    detail = "GGUF variant deletion requires an export directory",
                )
            deleted_count, deleted_bytes = _delete_gguf_variant_files(
                target_path,
                gguf_variant,
            )
            if deleted_count == 0:
                raise HTTPException(
                    status_code = 404,
                    detail = f"Variant {gguf_variant} not found on disk",
                )
            try:
                if not any(target_path.iterdir()):
                    target_path.rmdir()
                    _prune_empty_parents(target_path, allowed_root)
            except OSError:
                pass
            _forget_gone_library_entries(source, target_path)
            await _invalidate_local_scans()
            logger.info(
                "Deleted %s GGUF file(s) for exported model at %s variant %s (%0.1f MB freed)",
                deleted_count,
                target_path,
                gguf_variant,
                deleted_bytes / (1024 * 1024),
            )
            return {
                "status": "deleted",
                "path": str(target_path),
                "gguf_variant": gguf_variant,
            }

        if target_path.is_symlink() or target_path.is_file():
            target_path.unlink()
        else:
            shutil.rmtree(target_path)

        if target_path.exists() or target_path.is_symlink():
            raise HTTPException(
                status_code = 500,
                detail = "Deletion incomplete; some files could not be removed",
            )

        _prune_empty_parents(target_path, allowed_root)
        _forget_gone_library_entries(source, target_path)

        await _invalidate_local_scans()
        logger.info("Deleted fine-tuned model at %s", target_path)
        return {"status": "deleted", "path": str(target_path)}
    except HTTPException:
        raise
    except Exception as e:
        logger.error(
            "Error deleting fine-tuned model %s: %s",
            target_path,
            e,
            exc_info = True,
        )
        raise HTTPException(
            status_code = 500,
            detail = "Failed to delete fine-tuned model",
        )


@router.get("/loras/{lora_path:path}/base-model", response_model = LoRABaseModelResponse)
async def get_lora_base_model(lora_path: str, current_subject: str = Depends(get_current_subject)):
    """
    Get the base model for a LoRA adapter.

    This endpoint wraps the backend get_base_model_from_lora function.
    """
    if account_access.managed_account():
        await asyncio.to_thread(account_access.require_model_access, lora_path)
    try:
        base_model = get_base_model_from_lora(lora_path)

        if base_model is None:
            raise HTTPException(
                status_code = 404,
                detail = f"Could not determine base model for LoRA: {lora_path}",
            )

        return LoRABaseModelResponse(
            lora_path = lora_path,
            base_model = base_model,
        )

    except HTTPException:
        raise
    except Exception as e:
        raise log_and_http_error(
            e,
            500,
            "Failed to get base model",
            event = "models.get_lora_base_model_failed",
            log = logger,
        )


@router.get("/check-vision/{model_name:path}", response_model = VisionCheckResponse)
async def check_vision_model(
    model_name: str,
    hf_token: Optional[str] = Query(None),
    header_hf_token: Optional[str] = Depends(get_hf_token),
    allow_ambient_token: bool = Depends(allow_ambient_hf_token),
    current_subject: str = Depends(get_current_subject),
):
    """
    Check if a model is a vision model.

    This endpoint wraps the backend is_vision_model function.
    """
    hf_token = hf_token_arg(
        _normalize_hf_token(header_hf_token) or _normalize_hf_token(hf_token),
        allow_ambient_token = allow_ambient_token and not account_access.managed_account(),
    )
    # After the token, so a private repo classifies before its first download.
    await _require_model_access_or_caller_token(model_name, hf_token)
    try:
        logger.info(f"Checking if vision model: {model_name}")
        # Authenticate so gated VLMs classify correctly (else 404 reads as non-vision); local paths skip it.
        from core.inference.llama_cpp import _hf_offline_if_unreachable_for

        # Off-loop: the probes block and is_vision_model()'s lazy sets can import transformers.
        def _check():
            with _hf_offline_if_unreachable_for(model_name):
                return is_vision_model(model_name, hf_token = hf_token)

        is_vision = await asyncio.to_thread(_check)

        logger.info(f"Vision check result for {model_name}: is_vision={is_vision}")
        return VisionCheckResponse(
            model_name = model_name,
            is_vision = is_vision,
        )

    except Exception as e:
        raise log_and_http_error(
            e,
            500,
            "Failed to check vision model",
            event = "models.check_vision_model_failed",
            log = logger,
        )


@router.get("/check-embedding/{model_name:path}", response_model = EmbeddingCheckResponse)
async def check_embedding_model(
    model_name: str,
    hf_token: Optional[str] = Query(None),
    header_hf_token: Optional[str] = Depends(get_hf_token),
    allow_ambient_token: bool = Depends(allow_ambient_hf_token),
    current_subject: str = Depends(get_current_subject),
):
    """
    Check if a model is an embedding model.

    This endpoint wraps the backend is_embedding_model function.
    """
    hf_token = hf_token_arg(
        _normalize_hf_token(header_hf_token) or _normalize_hf_token(hf_token),
        allow_ambient_token = allow_ambient_token and not account_access.managed_account(),
    )
    # After the token, so a private repo classifies before its first download.
    await _require_model_access_or_caller_token(model_name, hf_token)
    try:
        logger.info(f"Checking if embedding model: {model_name}")
        # Same guard as /check-vision: is_embedding_model hits the hub with a 15s timeout.
        from core.inference.llama_cpp import _hf_offline_if_unreachable_for

        def _check():
            with _hf_offline_if_unreachable_for(model_name):
                return is_embedding_model(model_name, hf_token = hf_token)

        is_embedding = await asyncio.to_thread(_check)

        logger.info(f"Embedding check result for {model_name}: is_embedding={is_embedding}")
        return EmbeddingCheckResponse(
            model_name = model_name,
            is_embedding = is_embedding,
        )

    except Exception as e:
        raise log_and_http_error(
            e,
            500,
            "Failed to check embedding model",
            event = "models.check_embedding_model_failed",
            log = logger,
        )


# Budget for the walk below: a slow volume or large tree can outlast the listing.
_NATIVE_CONTEXT_READ_TIMEOUT_SECONDS = 5.0
# Backstop for a single hung syscall; longer than the walk budget.
_NATIVE_CONTEXT_HARD_TIMEOUT_SECONDS = 8.0
# Concurrent reads. A read stranded on a hung mount holds its slot, so retries wait.
_NATIVE_CONTEXT_MAX_CONCURRENT_READS = 4
_NATIVE_CONTEXT_SLOTS: "weakref.WeakKeyDictionary" = weakref.WeakKeyDictionary()


def _native_context_slots() -> asyncio.Semaphore:
    """Per running loop, since an asyncio primitive cannot be shared across loops."""
    loop = asyncio.get_running_loop()
    slots = _NATIVE_CONTEXT_SLOTS.get(loop)
    if slots is None:
        slots = asyncio.Semaphore(_NATIVE_CONTEXT_MAX_CONCURRENT_READS)
        _NATIVE_CONTEXT_SLOTS[loop] = slots
    return slots


def _settle_native_context(
    slots: asyncio.Semaphore, future: "asyncio.Future", value: Optional[int]
) -> None:
    slots.release()
    if not future.done():
        future.set_result(value)


async def _read_native_context_length_bounded(model: str, is_local: bool) -> Optional[int]:
    """Hard-bounded since None costs only a pre-filled context field; a daemon thread never blocks exit."""
    slots = _native_context_slots()
    began = time.monotonic()
    try:
        await asyncio.wait_for(slots.acquire(), timeout = _NATIVE_CONTEXT_HARD_TIMEOUT_SECONDS)
    except asyncio.TimeoutError:
        logger.debug("native context read for '%s' waited out its slot; reporting none", model)
        return None

    remaining = _NATIVE_CONTEXT_HARD_TIMEOUT_SECONDS - (time.monotonic() - began)
    loop = asyncio.get_running_loop()
    future: "asyncio.Future" = loop.create_future()

    def worker() -> None:
        try:
            value = _read_native_context_length(model, is_local = is_local)
        except Exception:
            value = None
        try:
            loop.call_soon_threadsafe(_settle_native_context, slots, future, value)
        except RuntimeError:
            pass  # loop already closed; nothing is waiting on this

    if remaining <= 0:
        slots.release()
        return None
    try:
        account_thread(target = worker, name = "native-ctx", daemon = True).start()
    except RuntimeError:
        slots.release()  # thread never ran, so it will never release
        return None

    try:
        return await asyncio.wait_for(future, timeout = remaining)
    except asyncio.TimeoutError:
        logger.debug("native context read for '%s' did not return; reporting none", model)
        return None


def _read_native_context_length(repo_id: str, is_local: bool) -> Optional[int]:
    """Time bound checked between files; past it returns None, not holding the listing. Never raises."""
    try:
        from utils.models.gguf_metadata import read_gguf_context_length
        from utils.paths.path_utils import file_contents_available_locally

        # Before cache discovery (also filesystem I/O): started after, a slow enumeration would hand the walk a fresh budget.
        deadline = time.monotonic() + _NATIVE_CONTEXT_READ_TIMEOUT_SECONDS
        if is_local:
            roots = [Path(repo_id)]
        else:
            from hub.utils.hf_cache_state import iter_repo_cache_dirs
            if not _is_valid_repo_id(repo_id):
                return None
            roots = list(iter_repo_cache_dirs("model", repo_id))

        for root in roots:
            if time.monotonic() >= deadline:
                logger.debug("native context read for '%s' out of budget", repo_id)
                return None
            paths = [root] if is_local and root.is_file() else _iter_gguf_paths(root, deadline)
            for f in paths:
                if time.monotonic() >= deadline:
                    logger.debug("native context read for '%s' out of budget", repo_id)
                    return None
                if _is_mmproj_filename(f.name) or not file_contents_available_locally(f):
                    # Opening a cloud placeholder recalls its data.
                    continue
                n = read_gguf_context_length(str(f))
                if n:
                    return n
    except Exception:
        pass
    return None


def _resolve_quant_gguf(repo_id: str, quant: str, is_local: bool) -> tuple[Optional[str], int]:
    """One snapshot only, so a quant is not summed across revisions; metadata lives in the first shard."""
    try:
        if is_local:
            # A direct .gguf path has no quant label; size the whole split family.
            direct = Path(repo_id)
            if direct.is_file() and direct.suffix.lower() == ".gguf":
                from core.inference.llama_cpp import LlamaCppBackend
                return str(direct), LlamaCppBackend._get_gguf_size_bytes(str(direct))
            roots = [Path(repo_id)]
        else:
            from hub.utils.hf_cache_state import iter_repo_cache_dirs

            if not _is_valid_repo_id(repo_id):
                return None, 0
            from hub.utils.gguf_sources import cached_gguf_sources

            source = cached_gguf_sources(repo_id).get((quant or "").strip().lower())
            if source is not None:
                return _resolve_quant_gguf(str(source.snapshot), quant, True)
            roots = []
            for entry in iter_repo_cache_dirs("model", repo_id):
                snaps = entry / "snapshots"
                if snaps.is_dir():
                    roots.extend(s for s in snaps.iterdir() if s.is_dir())

        want = (quant or "").strip()
        best_total = 0
        best_first: Optional[str] = None
        for root in roots:
            ranked: dict[int, list[tuple[str, Path, int]]] = {0: [], 1: []}
            for f in _iter_gguf_paths(root):
                try:
                    rel = f.relative_to(root).as_posix()
                except ValueError:
                    rel = f.name
                rank = _main_variant_rank(rel, want)
                if rank is None:
                    continue
                try:
                    size = f.stat().st_size
                except OSError:
                    continue
                ranked[rank].append((rel, f, size))
            # Exact keys when any exist (label otherwise), one shard family as in
            # group_gguf_variant_files; mixing counts other checkpoints' bytes.
            chosen = _one_shard_family_of(ranked[0] or ranked[1])
            matches = [(rel, f) for rel, f, _size in chosen]
            total = sum(size for _rel, _f, size in chosen)
            # Prefer the most complete snapshot so a partial older revision can't underestimate bytes.
            if matches and total > best_total:
                matches.sort(key = lambda m: m[0])
                best_total = total
                best_first = str(matches[0][1])
        if best_first is not None:
            return best_first, best_total
    except Exception:
        pass
    return None, 0


def _resolve_mtp_drafter(
    main_gguf_path: str, search_root: Optional[str] = None
) -> tuple[Optional[str], int]:
    """Load-path resolvers, so it prices the drafter llama-server opens; (None, 0) if absent; never raises"""

    try:
        from utils.models.gguf_metadata import read_gguf_nextn_predict_layers

        if (read_gguf_nextn_predict_layers(main_gguf_path) or 0) > 0:
            return None, 0
        from core.inference.llama_cpp import (
            LlamaCppBackend,
            _companion_snapshot_sibling,
            _pick_mtp,
            _pick_mtp_root_only,
            _snapshot_dir_of,
        )

        if _snapshot_dir_of(main_gguf_path) is not None:
            # Same gate as ``_download_mtp``: MTP/ fallback only for qwen4exp without its own head.
            pick = (
                _pick_mtp
                if LlamaCppBackend._gguf_path_wants_nested_mtp(main_gguf_path)
                else _pick_mtp_root_only
            )
            drafter = _companion_snapshot_sibling(main_gguf_path, pick)
        else:
            # No `accept` filter: the load path's guards a native-lease boundary estimates don't cross.
            from utils.models.model_config import detect_mtp_file
            drafter = detect_mtp_file(main_gguf_path, search_root = search_root)
        if not drafter:
            return None, 0
        # Whole split family: the load planner reserves every shard.
        return drafter, LlamaCppBackend._get_gguf_size_bytes(drafter)
    except Exception:
        return None, 0


@router.get("/kv-cache-estimate")
async def get_kv_cache_estimate(
    repo_id: str = Query(..., description = "HF repo ID or local path"),
    quant: str = Query(..., description = "Quantization label (e.g. Q4_K_M)"),
    n_ctx: Optional[int] = Query(
        None,
        ge = 1,
        description = "Context length to size the KV cache for; omit for the model's native length",
    ),
    cache_type_kv: Optional[str] = Query(
        None,
        description = "KV cache dtype (e.g. q8_0, q4_0, q5_0, iq4_nl, f32)",
    ),
    n_parallel: Optional[int] = Query(
        None,
        ge = 1,
        description = (
            "--parallel slots; scales the per-slot KV stream padding. Omit to use "
            "the server's own slot count, which is what a default load gets."
        ),
    ),
    speculative_type: Optional[str] = Query(
        None,
        description = "Speculative decoding mode (mtp, ngram, mtp+ngram, dspark, dflash, auto)",
    ),
    spec_draft_n_max: Optional[int] = Query(
        None,
        ge = 0,
        description = (
            "--spec-draft-n-max. A Hybrid Mamba target keeps one recurrent rollback "
            "state per drafted token, so this is the dominant speculative cost there."
        ),
    ),
    spec_draft_cache_type: Optional[str] = Query(
        None,
        description = "Draft KV cache dtype (--spec-draft-type-k/-v), independent of the main cache",
    ),
    ctx_checkpoints: Optional[int] = Query(
        None,
        ge = 0,
        description = "--ctx-checkpoints; each one adds an SWA snapshot per slot",
    ),
    n_batch: Optional[int] = Query(
        None,
        ge = 1,
        description = "--batch-size; the compute buffers scale with it",
    ),
    n_ubatch: Optional[int] = Query(
        None,
        ge = 1,
        description = "--ubatch-size; the dominant term in the flat compute buffer",
    ),
    tensor_parallel: bool = Query(
        False,
        description = "Tensor mode replicates compute buffers on every device in the pool",
    ),
    disable_vision: bool = Query(
        False,
        description = "Load a vision GGUF without its mmproj, freeing the projector's VRAM",
    ),
    flash_attn: Optional[bool] = Query(
        None,
        description = (
            "Flash attention state to price. Omit to resolve it the way the launch does "
            "(the build's capability, LLAMA_ARG_FLASH_ATTN, a last-wins -fa in the extra "
            "arguments, and a quantized V cache which forces it on). It is not a detail: "
            "with flash attention off llama.cpp floors the V axis at f16 and pads "
            "variable-width V tensors, which is a 1.44x KV cache at q8_0 and 2.28x at q4_0"
        ),
    ),
    kv_unified: Optional[bool] = Query(
        None,
        description = (
            "--kv-unified state to price; omit to resolve it as the launch does. Changes "
            "the sliding-window allowance on an SWA model, which is per slot when unified"
        ),
    ),
    swa_full: Optional[bool] = Query(
        None,
        description = (
            "--swa-full state to price; omit to resolve it as the launch does. Collapses "
            "an SWA model's two cache sizes into one full-context cache"
        ),
    ),
    no_mmproj_offload: Optional[bool] = Query(
        None,
        description = (
            "--no-mmproj-offload state to price; omit to resolve it as the launch does. "
            "A projector on the host is not VRAM, so pricing the wrong side moves the "
            "total by the whole mmproj"
        ),
    ),
    request: Request = None,  # type: ignore[assignment]
    current_subject: str = Depends(get_current_subject),
):
    """KV cache, weight and speculative-decoding bytes for a downloaded GGUF.

    Backs the load dialog's "exceeds memory" warning and the picker's memory
    bar, using the same architecture-aware estimator as load. Best-effort: on
    missing metadata it returns nulls and the UI simply shows nothing.

    ``spec_bytes`` is what an MTP draft mode costs on top of ``kv_bytes``. It is
    null for ngram, which drafts from the generated text and costs no VRAM, and
    for models with no drafter -- the caller draws no segment either way.
    """
    if account_access.managed_account():
        await asyncio.to_thread(account_access.require_model_access, repo_id)

    # Blocking disk work, so run in a worker. Args bound as defaults since the body reassigns them.
    def _estimate(n_ctx: Optional[int] = n_ctx, n_parallel: Optional[int] = n_parallel) -> dict:
        null = {
            "kv_bytes": None,
            "weights_bytes": None,
            "lookup_table_bytes": None,
            "native_context": None,
            "spec_bytes": None,
            "n_ctx": None,
            "projector_bytes": None,
            "spec_unpriced": False,
            "kv_checkpoint_bytes": None,
            "spec_fixed_bytes": None,
            "gpu_bytes": None,
            "compute_bytes": None,
            "total_bytes": None,
            "gpu_floor_bytes": None,
            "context_is_pinned": None,
            "inherited_device_pin": None,
        }
        try:
            from utils.models.model_config import is_local_path

            is_local = is_local_path(repo_id)
            path, weights_bytes = _resolve_quant_gguf(repo_id, quant, is_local)
            if not path:
                return null

            from core.inference.llama_cpp import LlamaCppBackend

            be = LlamaCppBackend.__new__(LlamaCppBackend)
            for attr in (
                "_context_length",
                "_n_layers",
                "_n_kv_heads",
                "_n_heads",
                "_embedding_length",
                "_kv_key_length",
                "_kv_value_length",
                "_kv_lora_rank",
                "_sliding_window",
                "_sliding_window_pattern",
                "_ssm_inner_size",
                "_full_attention_interval",
                "_key_length_mla",
                "_n_kv_heads_by_layer",
                "_kv_key_length_swa",
                "_kv_value_length_swa",
                "_shared_kv_layers",
                "_nextn_predict_layers",
            ):
                setattr(be, attr, None)
            be._model_identifier = "kv-estimate"
            be._read_gguf_metadata(path)

            # Mirror _resolve_parallel_slots: omitted means the server's slot count, not one.
            if n_parallel is None:
                state = getattr(getattr(request, "app", None), "state", None)
                n_parallel = getattr(state, "llama_parallel_slots", 1) or 1
            # Price what the launch serves: without --kv-unified load_model falls back to one slot.
            try:
                from routes.inference import _effective_parallel_slots
                n_parallel = _effective_parallel_slots(n_parallel, diffusion_kind = False)
            except Exception as e:
                logger.debug(f"slot clamp unavailable for '{repo_id}' {quant}: {e}")

            # Whether the caller pinned a context, captured before the default overwrites n_ctx.
            _inherited_device_pin = False
            try:
                _dev = (os.environ.get("LLAMA_ARG_DEVICE") or "").strip()
                # "none" is a CPU-only launch, which the planner already prices at zero GPU bytes.
                _inherited_device_pin = bool(_dev) and _dev.lower() != "none"
            except Exception as e:
                logger.debug(f"inherited device pin unreadable: {e}")

            _ctx_was_omitted = not n_ctx
            # Only an unpinned context is auto-fitted; an inherited one over budget is a real overage.
            _context_is_pinned = not _ctx_was_omitted
            # Same precedence as launch: an inherited positive context beats the header; only zero is dropped.
            if _ctx_was_omitted:
                try:
                    from routes.inference import _inherited_ctx_size

                    _inherited = _inherited_ctx_size()
                    _context_is_pinned = bool(_inherited)
                    n_ctx = _inherited or be._context_length
                except Exception as e:
                    logger.debug(f"inherited context unavailable: {e}")
                    n_ctx = be._context_length
            if not n_ctx or n_ctx < 1:
                return null

            # Resolve K/V types like the planner (incl. inherited LLAMA_ARG_CACHE_TYPE_K/V).
            _effective_cache_type = cache_type_kv
            try:
                from core.inference.llama_cpp import (
                    _kv_bytes_per_elem,
                    _planned_main_cache_types,
                )
                _effective_cache_type = max(
                    _planned_main_cache_types(cache_type_kv, None), key = _kv_bytes_per_elem
                )
            except Exception as e:
                logger.debug(f"cache type resolution failed for '{repo_id}': {e}")

            # Re-resolve via the launch's own helpers so estimate and load agree.
            # isinstance(bool): in-process the omitted arg is a truthy Query default.
            _asked_flash_attn = flash_attn if isinstance(flash_attn, bool) else None
            _asked_kv_unified = kv_unified if isinstance(kv_unified, bool) else None
            _asked_swa_full = swa_full if isinstance(swa_full, bool) else None
            _asked_no_mmproj = no_mmproj_offload if isinstance(no_mmproj_offload, bool) else None
            _plan_extra_args: list[str] = []
            if _asked_flash_attn is not None:
                _plan_extra_args += ["--flash-attn", "on" if _asked_flash_attn else "off"]
            if _asked_kv_unified is not None:
                _plan_extra_args += ["--kv-unified" if _asked_kv_unified else "--no-kv-unified"]
            if _asked_swa_full:
                # llama.cpp has no --no-swa-full.
                _plan_extra_args += ["--swa-full"]
            if _asked_no_mmproj is not None:
                _plan_extra_args += [
                    "--no-mmproj-offload" if _asked_no_mmproj else "--mmproj-offload"
                ]
            _planner_extras = _plan_extra_args or None

            _plan_kwargs: dict = {}
            try:
                from core.inference.llama_cpp import (
                    _kv_unified_from_args,
                    _planned_flash_attn_state,
                    _planned_main_cache_types as _plan_cache_types,
                    _swa_full_from_args_or_env,
                )

                _plan_caps = {}
                try:
                    _plan_caps = LlamaCppBackend.probe_server_capabilities() or {}
                except Exception as e:
                    logger.debug(f"capability probe failed for '{repo_id}': {e}")
                _plan_kwargs = {
                    "flash_attn": _planned_flash_attn_state(
                        _planner_extras,
                        planned_cache_types = _plan_cache_types(cache_type_kv, _planner_extras),
                        # An unreadable probe keeps the managed default.
                        supports_flash_attn = bool(_plan_caps.get("supports_flash_attn", True)),
                        tensor_parallel = bool(tensor_parallel),
                        architecture = getattr(be, "_architecture", None),
                    ),
                    # The loader's own default: unified only for >1 slot, only if supported.
                    "kv_unified": _kv_unified_from_args(
                        _planner_extras,
                        default = (n_parallel or 1) > 1
                        and bool(_plan_caps.get("supports_kv_unified", False)),
                    ),
                    "swa_full": _swa_full_from_args_or_env(_planner_extras),
                }
            except Exception as e:
                logger.debug(f"attention plan resolution failed for '{repo_id}': {e}")

            # Probe failures keep the unflagged default rather than assuming zero.
            _cc_caps: dict = {}
            _total_ram_mib: Optional[int] = None
            try:
                _cc_caps = be.probe_server_capabilities() or {}
                _total_ram_mib = getattr(be, "_host_memory_capacity_mib", lambda: None)()
            except Exception as e:
                logger.debug(f"checkpoint budget inputs unavailable for '{repo_id}': {e}")

            # A blank field means llama.cpp's default, narrowed only by a cap Studio can emit.
            from core.inference.llama_cpp import effective_ctx_checkpoints_for_caps

            _effective_checkpoints = effective_ctx_checkpoints_for_caps(
                _cc_caps,
                None,
                ctx_checkpoints,
                per_checkpoint_bytes = getattr(be, "_ctx_checkpoint_bytes", lambda *_a, **_k: 0)(
                    _effective_cache_type,
                    swa_full = _plan_kwargs.get("swa_full", False),
                    flash_attn = _plan_kwargs.get("flash_attn", True),
                ),
                n_parallel = n_parallel,
                total_host_bytes = (_total_ram_mib * 1024 * 1024) if _total_ram_mib else None,
            )
            kv = be._estimate_kv_cache_bytes(
                n_ctx,
                _effective_cache_type,
                n_parallel = n_parallel,
                ctx_checkpoints = _effective_checkpoints,
                n_ubatch = n_ubatch,
                **_plan_kwargs,
            )

            # Report the host-resident checkpoint share separately from GPU cache bytes.
            kv_checkpoint = 0
            if _effective_checkpoints:
                _kv_without = be._estimate_kv_cache_bytes(
                    n_ctx,
                    _effective_cache_type,
                    n_parallel = n_parallel,
                    ctx_checkpoints = 0,
                    n_ubatch = n_ubatch,
                    **_plan_kwargs,
                )
                kv_checkpoint = max(0, int(kv) - int(_kv_without))

            # DSpark/DFlash drafters aren't priced here (~11 GB possible); flag as unpriced instead.
            _spec_mode = (speculative_type or "").lower()
            spec_unpriced = _spec_mode in ("dspark", "dflash")
            # Auto promotes to DSpark/DFlash when shipped and supported, so flag it too.
            if not spec_unpriced and _spec_mode == "auto":
                try:
                    # Import here: these names are local to _resolve_mtp_drafter.
                    from core.inference.llama_cpp import (
                        _companion_snapshot_sibling,
                        _is_dflash_drafter_path,
                        _pick_dspark,
                        _snapshot_dir_of,
                    )

                    def _pick_dflash(candidates: list[str]) -> Optional[str]:
                        hits = sorted(f for f in candidates if _is_dflash_drafter_path(f))
                        return hits[0] if hits else None

                    _caps = be.probe_server_capabilities() or {}
                    if _snapshot_dir_of(path) is not None:
                        _has_dspark = bool(_companion_snapshot_sibling(path, _pick_dspark))
                        _has_dflash = bool(_companion_snapshot_sibling(path, _pick_dflash))
                    else:
                        # Plain local folders resolve sidecars via the same detectors as the load path, not snapshots only.
                        from utils.models.drafters.dflash import detect_dflash_file
                        from utils.models.model_config import detect_dspark_file

                        _root = repo_id if is_local else None
                        _has_dspark = bool(detect_dspark_file(path, search_root = _root))
                        _has_dflash = bool(detect_dflash_file(path, search_root = _root))
                    if (_caps.get("supports_dspark") and _has_dspark) or (
                        _caps.get("supports_dflash") and _has_dflash
                    ):
                        spec_unpriced = True
                except Exception as e:
                    logger.debug(f"auto sidecar probe failed for '{repo_id}' {quant}: {e}")

            # mmproj is charged at a worst-case multiple of its size (_MMPROJ_VRAM_SAFETY).
            projector = None
            if not disable_vision:
                try:
                    from core.inference.llama_cpp import LlamaCppBackend as _Be
                    from utils.models.model_config import detect_mmproj_file

                    # HF cache layout puts the projector at the snapshot root, not beside quant subdirs.
                    from core.inference.llama_cpp import (
                        _companion_snapshot_sibling,
                        _mmproj_picker,
                        _snapshot_dir_of,
                    )

                    if _snapshot_dir_of(path) is not None:
                        mmproj = _companion_snapshot_sibling(path, _mmproj_picker(repo_id, path))
                    else:
                        mmproj = detect_mmproj_file(path, search_root = repo_id if is_local else None)
                    if mmproj:
                        projector = int(_Be._get_gguf_size_bytes(mmproj) * _Be._MMPROJ_VRAM_SAFETY)
                except Exception as e:
                    logger.debug(f"mmproj estimate failed for '{repo_id}' {quant}: {e}")
            # Use the resolved placement: env can put the projector on the host.
            try:
                from core.inference.llama_cpp import _resolved_mmproj_offload
                _mmproj_offloaded = _resolved_mmproj_offload(_planner_extras)
            except Exception as e:  # noqa: BLE001 -- cannot resolve -> the asked value stands
                logger.debug(f"could not resolve the mmproj placement: {e}")
                _mmproj_offloaded = None if _asked_no_mmproj is None else not _asked_no_mmproj
            if _mmproj_offloaded is False:
                # The projector is in HOST memory, with vision still on.
                projector = None

            # Only MTP reserves memory. Guarded separately so KV still prices if MTP sizing fails.
            spec = None
            spec_fixed = None
            if (speculative_type or "").lower() in ("mtp", "mtp+ngram", "auto"):
                try:
                    from core.inference.llama_cpp import (
                        _auto_mode_drops_mtp,
                        _extract_model_size_b,
                        _is_mtp_model_name,
                        _mla_mtp_auto_enabled,
                    )

                    drafter_path, drafter_bytes = _resolve_mtp_drafter(
                        path, search_root = repo_id if is_local else None
                    )
                    # Auto declines MTP on a sub-3B embedded head (per-token cost regresses); separate drafter exempt
                    _mode = (speculative_type or "").lower()

                    # Like the loader, this declines MTP unless llama-server advertises a --spec-type mtp token.
                    _binary_lacks_mtp = not (be.probe_server_capabilities() or {}).get("mtp_token")
                    # Auto declines an MLA embedded head (GLM/DeepSeek/Kimi): slower than none; separate drafter exempt
                    _auto_drops_mla = (
                        _mode == "auto"
                        and be._kv_lora_rank is not None
                        and bool(be._nextn_predict_layers)
                        and not drafter_path
                        and not _mla_mtp_auto_enabled()
                    )
                    # Mirror is_mtp_model: otherwise MLA models get billed a second full KV copy.
                    _not_an_mtp_model = not (
                        bool(be._nextn_predict_layers)
                        or _is_mtp_model_name(repo_id, path)
                        or bool(drafter_path)
                    )
                    if (
                        _binary_lacks_mtp
                        or _auto_drops_mla
                        or _not_an_mtp_model
                        or _auto_mode_drops_mtp(
                            _mode,
                            _extract_model_size_b(repo_id),
                            has_separate_drafter = bool(drafter_path),
                        )
                    ):
                        pass
                    else:
                        # Reported separately so auto-fit softening can't hide a context-independent overage.
                        spec_fixed = int(drafter_bytes or 0) or None
                        _effective_draft_n_max = spec_draft_n_max
                        if _effective_draft_n_max is None:
                            try:
                                from routes.inference import (
                                    _cached_estimate_config,
                                    _estimate_draft_n_max,
                                )
                                _effective_draft_n_max = _estimate_draft_n_max(
                                    _cached_estimate_config(repo_id, quant, None, False),
                                    drafter_path or "",
                                    requested = None,
                                    extras = [],
                                )
                            except Exception as e:
                                logger.debug(f"draft depth default failed: {e}")
                                _effective_draft_n_max = 0
                        spec = be._estimate_mtp_overhead_bytes(
                            n_ctx,
                            # Draft K/V default to f16 at load; passing it keeps a quantized main cache from underpricing
                            draft_cache_type_k = spec_draft_cache_type,
                            draft_cache_type_v = spec_draft_cache_type,
                            drafter_path = drafter_path,
                            draft_weights_bytes = drafter_bytes,
                            n_parallel = n_parallel,
                            # Blank is not zero: _build_speculative_flags defaults draft depth to
                            # 2 (GPU) / 3 (CPU), which multiplies Hybrid Mamba rollback state.
                            spec_draft_n_max = _effective_draft_n_max,
                            # Same estimator, so it must get the same resolved plan.
                            **_plan_kwargs,
                        )
                        # Adds the draft decode graph floor, which the helper leaves to the loader's soft overhead.
                        if spec is not None:
                            spec += be._MTP_DRAFT_COMPUTE_BYTES
                except Exception as e:
                    logger.debug(f"mtp overhead estimate failed for '{repo_id}' {quant}: {e}")

            # The load planner's figure is authoritative (env, companions, compute buffers);
            # existing fields kept for compatibility.
            planner_gpu = None
            planner_compute = None
            planner_total = None
            planner_floor = None
            planner_unsized = False
            # Bind before the try so the except path never hits a NameError.
            _b = None
            try:
                from routes.inference import (
                    _ESTIMATE_NOT_ON_DISK,
                    _cached_estimate_config,
                    _gguf_memory_breakdown,
                    _localized_estimate_config,
                )

                # Tensor mode replicates compute buffers per device; use the effective mode (env included).
                _effective_tp = tensor_parallel
                try:
                    from core.inference.llama_server_args import _effective_tensor_parallel
                    _effective_tp = _effective_tensor_parallel(None, bool(tensor_parallel))
                except Exception as e:
                    logger.debug(f"tensor mode resolution failed for '{repo_id}': {e}")
                if _effective_tp and not _tensor_split_can_launch(
                    _effective_tp, _plan_kwargs.get("flash_attn")
                ):
                    logger.debug(
                        f"'{repo_id}': flash attention is off, so the launch cannot take a tensor "
                        "split; pricing the layer split it would fall back to"
                    )
                    _effective_tp = False
                    # Explicit, since an inherited LLAMA_ARG_SPLIT_MODE=tensor would re-enable it.
                    _planner_extras = list(_planner_extras or []) + ["--split-mode", "layer"]
                _planner_devices = 1
                if _effective_tp:
                    from routes.inference import (
                        _cached_inference_devices,
                        _guard_device_count,
                    )
                    _planner_devices = max(
                        1,
                        _guard_device_count(
                            None, _cached_inference_devices(), tensor_parallel = True
                        ),
                    )
                # Plan built with the same extra arguments, else gpu_bytes and kv_bytes in one response disagree.
                _cfg = _cached_estimate_config(repo_id, quant, None, False)
                if _cfg is not None and _cfg is not _ESTIMATE_NOT_ON_DISK:
                    _cfg = _localized_estimate_config(_cfg, path)
                    _b = _gguf_memory_breakdown(
                        _cfg,
                        path,
                        n_ctx = 0 if _ctx_was_omitted else n_ctx,
                        speculative_type = speculative_type,
                        n_parallel = n_parallel,
                        cache_type_kv = cache_type_kv,
                        ctx_checkpoints = ctx_checkpoints,
                        disable_vision = disable_vision,
                        spec_draft_n_max = spec_draft_n_max,
                        spec_draft_cache_type = spec_draft_cache_type,
                        n_batch = n_batch,
                        n_ubatch = n_ubatch,
                        # Pass the resolved split: _gguf_memory_breakdown re-resolves a raw toggle back into tensor mode.
                        tensor_parallel = _effective_tp,
                        n_devices = _planner_devices,
                        llama_extra_args = _planner_extras,
                    )
                    if _b is not None:
                        # Keep a real zero (e.g. LLAMA_ARG_DEVICE=none means CPU-only).
                        planner_gpu = int(_b.gpu_bytes)
                        planner_compute = int(_b.compute_bytes) or None
                        planner_total = int(_b.total_bytes) or None
                        planner_unsized = bool(_b.drafter_kv_unsized)
                        # Floor = plan at the shortest context; what remains can't be fixed by shortening context.
                        _floor = _gguf_memory_breakdown(
                            _cfg,
                            path,
                            n_ctx = _MIN_PRICED_CONTEXT,
                            speculative_type = speculative_type,
                            n_parallel = n_parallel,
                            cache_type_kv = cache_type_kv,
                            ctx_checkpoints = ctx_checkpoints,
                            disable_vision = disable_vision,
                            spec_draft_n_max = spec_draft_n_max,
                            spec_draft_cache_type = spec_draft_cache_type,
                            n_batch = n_batch,
                            n_ubatch = n_ubatch,
                            # A floor priced for an impossible placement is not a floor.
                            tensor_parallel = _effective_tp,
                            n_devices = _planner_devices,
                            llama_extra_args = _planner_extras,
                        )
                        if _floor is not None:
                            planner_floor = min(int(_floor.gpu_bytes), planner_gpu)
            except Exception as e:
                logger.debug(f"planner breakdown failed for '{repo_id}' {quant}: {e}")

            # Built via MemoryEstimate so this route and /inference/estimate-memory can't drift.
            _estimate = build_memory_estimate(
                _b if _b is not None else EMPTY_BREAKDOWN,
                quant_file_bytes = weights_bytes or 0,
                native_context = be._context_length,
                # What remains at the shortest context: callers can tell a context overage from one no context fixes.
                gpu_floor_bytes = planner_floor,
                # False only when the loader may shrink the context; an inherited over-budget window is no fit.
                context_is_pinned = _context_is_pinned,
                # An inherited LLAMA_ARG_DEVICE confines the child to fewer cards than the caller's budget.
                inherited_device_pin = _inherited_device_pin,
                # The planner could not size the drafter cache, so its own total is only a floor.
                spec_unpriced = spec_unpriced or planner_unsized,
                # Passed to the constructor: Pydantic doesn't validate post-construction assignment.
                gpu_bytes = planner_gpu,
                compute_bytes = planner_compute,
                total_bytes = planner_total,
                n_ctx = int(n_ctx),
            )
            return project_kv_cache_estimate(
                _estimate,
                kv_bytes = int(kv) if kv else None,
                spec_bytes = int(spec) if spec else None,
                # The part of spec_bytes a shorter context cannot reduce.
                spec_fixed_bytes = spec_fixed if spec else None,
                projector_bytes = projector or None,
                # Host-heap share; included in kv_bytes, which means the whole cache.
                kv_checkpoint_bytes = kv_checkpoint or None,
            )
        except Exception as e:
            logger.debug(f"kv-cache-estimate failed for '{repo_id}' {quant}: {e}")
            return null

    return await asyncio.to_thread(_estimate)


@router.get("/gguf-variants", response_model = GgufVariantsResponse)
async def get_gguf_variants(
    repo_id: str = Query(
        ..., description = "HuggingFace repo ID (e.g. 'unsloth/gemma-3-4b-it-GGUF')"
    ),
    prefer_local_cache: bool = False,
    offline: bool = False,
    local_path: Optional[str] = None,
    hf_token: Optional[str] = Query(None, description = "HuggingFace token for private repos"),
    include_cache_locations: bool = False,
    hf_token_header: HfTokenArg = Depends(get_request_hf_token),
    current_subject: str = Depends(get_current_subject),
    via_api_key: bool = Depends(authenticated_via_api_key),
):
    """List GGUF quantization variants for a HF repo or local directory."""
    # Resolve before the access check: the handle matches no allowlist entry.
    repo_id = resolve_host_path_reference(repo_id) or repo_id
    local_path = resolve_host_path_reference(local_path) or local_path
    from hub.services.models import gguf_variants as hub_gguf_variants

    if account_access.managed_account():
        await hub_gguf_variants.listing_thread(
            offline,
            account_access.require_model_access,
            repo_id,
            **({"offline": True} if offline else {}),
        )
    try:
        hf_token = _resolve_hub_token(hf_token_header, hf_token)

        answer = await hub_gguf_variants.get_gguf_variants_answer(
            repo_id,
            prefer_local_cache = prefer_local_cache,
            offline = offline,
            local_path = local_path,
            include_cache_locations = include_cache_locations,
            hf_token = hf_token,
        )
        response = answer.response
        # The copy the listing answered from, else the pin; both beat a repo-wide walk.
        context_model = (
            answer.context_source
            or hub_gguf_variants.pinned_snapshot_for_request(repo_id, local_path)
            or repo_id
        )
        # Reading a bare repo id walks every local cache; skip it when unauthorized.
        if not answer.cache_authorized and not is_local_path(context_model):
            context_model = None
        variant_sources = getattr(answer, "variant_context_sources", None) or {}

        # Each quant is priced off its own source; an unauthorized (None) context_model adds no read.
        read_models = [
            model for model in dict.fromkeys([context_model, *variant_sources.values()]) if model
        ]
        # Share the existing hard deadline and concurrency guard across all source reads.
        context_values = await asyncio.gather(
            *(
                _read_native_context_length_bounded(model, is_local_path(model))
                for model in read_models
            )
        )
        context_lengths = dict(zip(read_models, context_values))

        # The identifier is resolved on the way in, so it is referenced again on the way out, as in /hub.
        return redact_host_paths(
            GgufVariantsResponse(
                repo_id = response.repo_id,
                variants = [
                    GgufVariantDetail(
                        filename = v.filename,
                        quant = v.quant,
                        cache_path = getattr(v, "cache_path", None),
                        context_length = context_lengths.get(
                            variant_sources.get(v.quant.lower(), context_model)
                        ),
                        # Path-qualified keys are not pickable labels; without display_label the row reads as its whole path.
                        display_label = getattr(v, "display_label", None),
                        size_bytes = v.size_bytes,
                        download_size_bytes = int(
                            getattr(v, "download_size_bytes", v.size_bytes) or v.size_bytes
                        ),
                        estimated_resident_gb = getattr(v, "estimated_resident_gb", None),
                        lookup_table_bytes = int(getattr(v, "lookup_table_bytes", 0) or 0),
                        pending_drafter_filename = getattr(v, "pending_drafter_filename", None),
                        pending_drafter_size_bytes = int(
                            getattr(v, "pending_drafter_size_bytes", 0) or 0
                        ),
                        downloaded = bool(v.downloaded),
                        update_available = bool(getattr(v, "update_available", False)),
                        partial = bool(getattr(v, "partial", False)),
                        cleanable = bool(getattr(v, "cleanable", False)),
                    )
                    for v in response.variants
                ],
                has_vision = response.has_vision,
                default_variant = response.default_variant,
                context_length = context_lengths.get(context_model),
                resolved_locally = bool(getattr(response, "resolved_locally", False)),
                dependencies_resolved = bool(getattr(response, "dependencies_resolved", False)),
                loadable_variants = getattr(response, "loadable_variants", None),
                loadable = getattr(response, "loadable", None),
                variant_format = getattr(response, "variant_format", None),
            ),
            via_api_key = via_api_key,
        )
    except HTTPException:
        raise
    except Exception as e:
        logger.error(f"Error listing GGUF variants for '{repo_id}': {e}", exc_info = True)
        raise HTTPException(
            status_code = 500,
            detail = "Failed to list GGUF variants",
        )


@router.get("/gguf-download-progress")
async def get_gguf_download_progress(
    repo_id: str = Query(..., description = "HuggingFace repo ID"),
    variant: str = Query("", description = "Quantization variant (e.g. UD-TQ1_0)"),
    expected_bytes: int = Query(0, description = "Expected total download size in bytes"),
    hf_token: HfTokenArg = Depends(get_request_hf_token),
    current_subject: str = Depends(get_current_subject),
    via_api_key: bool = Depends(authenticated_via_api_key),
):
    """Compatibility route backed by the shared multi-cache progress service."""
    from hub.services.models import downloads
    return redact_host_paths(
        await downloads.get_gguf_download_progress_response(
            repo_id,
            variant = variant,
            expected_bytes = expected_bytes,
            hf_token = hf_token,
        ),
        via_api_key = via_api_key,
    )


def _resolve_hf_cache_realpath(repo_dir: Path) -> Optional[str]:
    """Most useful on-disk path for a HF cache repo. Delegates to the Hub scanner's function of the same
    name so this route and ``/api/hub/local-models`` name one directory: the newest snapshot dir, ties
    broken by ``snapshot_selection_key``."""
    from hub.utils import inventory_scan as hf_cache_scan
    return hf_cache_scan.resolve_hf_cache_realpath(repo_dir)


@router.get("/download-progress")
async def get_download_progress(
    repo_id: str = Query(..., description = "HuggingFace repo ID"),
    mlx_load: bool = Query(False),
    hf_token: HfTokenArg = Depends(get_request_hf_token),
    current_subject: str = Depends(get_current_subject),
    via_api_key: bool = Depends(authenticated_via_api_key),
):
    """Compatibility route backed by the shared multi-cache progress service. The payload names
    the cache directory it measured, so it takes the caller class like its ``/api/hub`` twin."""
    from hub.services.models import downloads
    return redact_host_paths(
        await downloads.get_download_progress_response(
            repo_id, hf_token = hf_token, mlx_load = mlx_load
        ),
        via_api_key = via_api_key,
    )


def _repo_in_any_hf_cache(model_name: str) -> bool:
    """Checks active, legacy and default HF caches, so a repo already held is never marked scan-created."""
    from utils.paths import resolve_cached_repo_id_case

    dirname = f"models--{resolve_cached_repo_id_case(model_name).replace('/', '--')}"
    dirname_lower = dirname.lower()
    from hub.utils.hf_cache_state import hf_cache_roots

    candidates = hf_cache_roots()
    # Discard deletes case-insensitively across all caches, so check every cache.
    for cache in candidates:
        try:
            if (cache / dirname).exists():
                return True
            if cache.is_dir():
                for entry in cache.iterdir():
                    if entry.name.lower() == dirname_lower and entry.is_dir():
                        return True
        except Exception:
            continue
    return False


def _all_hf_cache_scans():
    """scan_cache_dir for the active, legacy, and default HF caches. Each probe is isolated: an
    unreadable auxiliary cache is skipped, not fatal, so the Downloaded list never blanks out and
    downloads never leak into Recommended."""
    from hub.utils.inventory_scan import all_hf_cache_scans
    return all_hf_cache_scans()


def _is_gguf_filename(name: str) -> bool:
    return name.lower().endswith(".gguf")


def _is_mmproj_filename(name: str) -> bool:
    """Match GGUF vision-adapter (mmproj) files. Consistent with
    ``utils.models.model_config._is_mmproj``."""
    return "mmproj" in name.lower()


def _is_main_gguf_filename(name: str) -> bool:
    """A primary GGUF weight, not an mmproj vision adapter, an MTP drafter or a calibration
    imatrix. Same rule as ``hub.services.models.common``; pass a snapshot-relative path to
    catch ``MTP/`` copies too."""
    return (
        _is_gguf_filename(name)
        and not _is_mmproj_filename(name)
        and not _is_mtp_drafter(name)
        and not _is_imatrix_path(name)
    )


def _recovered_repo_is_unusable_by_repo_id(repo_info) -> bool:
    """See hub.utils.inventory_scan; False for anything upstream already returns."""
    from hub.utils.inventory_scan import recovered_repo_is_unusable_by_repo_id as impl
    return impl(repo_info)


def _repo_id_will_not_resolve(repo_cache_dir: Path) -> bool:
    """See hub.utils.inventory_scan; True only in the dangling refs/main window."""
    from hub.utils.inventory_scan import repo_id_will_not_resolve as impl
    return impl(repo_cache_dir)


def _default_ref_offers_no_whole_quant(repo_cache_dir: Path) -> bool:
    """See hub.utils.inventory_scan; True when refs/main resolves onto a torn quant. _gguf_copy_is_usable
    asks the stronger question now, so this has no caller here; it stays because it was importable
    before."""
    from hub.utils.inventory_scan import default_ref_offers_no_whole_quant as impl
    return impl(repo_cache_dir)


def _gguf_copy_is_usable(repo_info, load_id: Optional[str], active_root: Optional[Path]) -> bool:
    """Whether this copy of the repo holds a quant a load can reach. A pinned copy names a complete
    snapshot; an unpinned copy must be in the active cache and have an id that resolves onto a whole
    quant, which is exactly what withheld the pin."""
    if load_id:
        return True
    if active_root is None:
        return False
    try:
        repo_path = Path(repo_info.repo_path)
        if repo_path.parent.resolve(strict = False) != active_root:
            return False
        ref_snapshot = _default_ref_snapshot(repo_path)
        return ref_snapshot is not None and snapshot_has_complete_variants(str(ref_snapshot))
    except (OSError, RuntimeError, ValueError):
        return False


def _snapshot_has_gguf_projector(snapshot: str) -> bool:
    """See hub.utils.inventory_scan; reads the same walk the variant lister reports from."""
    from hub.utils.inventory_scan import snapshot_has_gguf_projector as impl
    return impl(Path(snapshot))


def _cached_files(repo_info) -> list:
    return [f for rev in getattr(repo_info, "revisions", ()) or () for f in cached_repo_files(rev)]


def cached_repo_files(revision) -> list:
    from hub.services.models.cache_inventory import cached_repo_files as impl
    return impl(revision)


def _cached_repo_file_name(file_obj) -> str:
    """Snapshot-relative name for a cached file: huggingface_hub records the bare ``file_name``,
    which cannot tell an ``MTP/`` drafter from a quant."""
    from hub.services.models.cache_inventory import _cached_repo_file_name as impl
    return impl(file_obj)


def _main_variant_gguf_label(rel_path: str) -> Optional[str]:
    name = rel_path.rsplit("/", 1)[-1]
    if not _is_main_gguf_filename(name):
        return None
    if _is_mtp_drafter(rel_path):
        return None
    label = _extract_quant_label(rel_path)
    if _is_big_endian_gguf_path(rel_path, label):
        return None
    return label


def _one_shard_family_of(entries: list) -> list:
    """``(rel, path, size)`` *entries* narrowed to the one shard set the loader opens, as ``hub.utils.gguf.group_gguf_variant_files``."""
    if len(entries) < 2:
        return list(entries)
    from hub.utils.gguf import gguf_shard_set

    families: dict[tuple[str, int], list] = {}
    for entry in entries:
        families.setdefault(gguf_shard_set(entry[0]), []).append(entry)
    if len(families) < 2:
        return list(entries)
    return min(families.values(), key = lambda group: min(e[0] for e in group))


def _main_variant_rank(rel_path: str, want: str) -> Optional[int]:
    """rank an exact variant as 0, its legacy quant alias as 1, or no match as None without normalizing paths."""
    from hub.utils.gguf import gguf_variant_family, is_qualified_gguf_variant_key
    from utils.models.model_config import _gguf_variant_key

    label = _main_variant_gguf_label(rel_path)
    if label is None:
        return None
    key = _gguf_variant_key(rel_path)
    # a second same-quant build in a custom folder is keyed by its family (#13926)
    want_family = gguf_variant_family(want) if want.lower().endswith(".gguf") else want
    if _variant_keys_match(key, want) or (
        gguf_variant_family(rel_path).casefold() == want_family.strip().casefold()
    ):
        return 0
    if is_qualified_gguf_variant_key(key) and "/" not in key.replace("\\", "/"):
        return None
    return 1 if _normalized_quant_label(label) == _normalized_quant_label(want) else None


def _variant_keys_match(key: str, want: str) -> bool:
    """match exact variant keys without folding punctuation in qualified paths."""
    from hub.utils.gguf import is_qualified_gguf_variant_key

    if is_qualified_gguf_variant_key(key) or is_qualified_gguf_variant_key(want):
        return key.strip().lower() == want.strip().lower()
    return _normalized_quant_label(key) == _normalized_quant_label(want)


def _normalized_quant_label(label: str) -> str:
    return label.lower().replace("-", "").replace("_", "")


def _repo_has_mmproj(repo_info) -> bool:
    """True if the repo ships a GGUF vision adapter (mmproj), so it can
    take image inputs. Cheap: scans already-listed file names only."""
    return any(
        _is_mmproj_filename(f.file_name)
        for revision in repo_info.revisions
        for f in cached_repo_files(revision)
    )


def _cached_gguf_row_has_vision(repo_info, load_id: Optional[str]) -> bool:
    """Whether the copy this row loads ships a projector. The loader opens the projector out of the snapshot it
    loads from, so one in a revision the load never reaches is not vision support. Judged per snapshot, not
    per file: a split quant can sit in a subdirectory while the projector sits at the root."""
    if load_id:
        return _snapshot_has_gguf_projector(load_id)
    # No projector in any revision means none to reach, and saves a cache walk.
    if not _repo_has_mmproj(repo_info):
        return False
    try:
        from hub.utils.gguf import iter_snapshots_preferring_whole, list_local_gguf_variants

        # The row describes this copy; a duplicate in another root is one the load never reaches.
        root = Path(repo_info.repo_path).parent
        for snapshot in iter_snapshots_preferring_whole(repo_info.repo_id, None, root = root):
            variants, has_vision = list_local_gguf_variants(str(snapshot))
            if variants:
                return bool(has_vision)
    except Exception:
        pass
    # Nothing on disk to load, so the row describes the repo rather than a copy of it.
    return True


def _iter_gguf_paths(root: Path, deadline: Optional[float] = None):
    from hub.services.models.common import _iter_gguf_paths as iter_paths
    yield from iter_paths(root, deadline)


def _repo_gguf_size_bytes(repo_info) -> int:
    """Dedupes by blob path: Hugging Face hardlinks blobs shared across revisions. mmproj excluded."""
    unique_blobs: dict[str, int] = {}
    for revision in repo_info.revisions:
        rev_id = getattr(revision, "commit_hash", None) or str(id(revision))
        for f in cached_repo_files(revision):
            # Snapshot-relative: only the directory tells an MTP/ drafter from a primary quant.
            name = _cached_repo_file_name(f)
            if _is_main_gguf_filename(name):
                from hub.services.models.cache_inventory import _blob_key
                unique_blobs[_blob_key(f, f"{rev_id}:{name}")] = f.size_on_disk or 0
    return sum(unique_blobs.values())


def _repo_has_gguf_files(repo_info) -> bool:
    """True when any revision in a cached repo has a primary GGUF weight file; an mmproj-only repo is
    not one."""
    return _repo_gguf_size_bytes(repo_info) > 0


def _blob_mtime(f) -> float:
    """Blob modification time in epoch seconds (0.0 if unknown). Prefers HF metadata
    ``blob_last_modified``, falls back to stat(); only mtimes, never path parsing."""
    ts = getattr(f, "blob_last_modified", None)
    if isinstance(ts, (int, float)) and ts > 0:
        return float(ts)
    blob_path = getattr(f, "blob_path", None)
    if blob_path:
        try:
            return float(Path(blob_path).stat().st_mtime)
        except OSError:
            pass
    return 0.0


def _repo_gguf_last_modified(repo_info) -> float:
    """Newest mtime among a repo's primary (non-mmproj) GGUF blobs, driving the Downloaded list's "last
    downloaded" ordering."""
    latest = 0.0
    for revision in repo_info.revisions:
        for f in cached_repo_files(revision):
            if _is_main_gguf_filename(_cached_repo_file_name(f)):
                latest = max(latest, _blob_mtime(f))
    return latest


def snapshot_variants_all_complete(snapshot: str) -> bool:
    """Re-export; the predicate lives beside the completed-variant walk it uses."""
    from hub.utils import inventory_scan
    return inventory_scan.snapshot_variants_all_complete(snapshot)


def snapshot_has_complete_variants(snapshot: str) -> bool:
    """Re-export of the predicate every load-id pin shares; see above."""
    from hub.utils import inventory_scan
    return inventory_scan.snapshot_has_complete_variants(snapshot)


def _repo_gguf_load_id(repo_info, active_root: Optional[Path]) -> Optional[str]:
    """Snapshot dir holding the newest primary GGUF, for a repo outside the active hub cache that does
    not resolve by id. ``None`` when the id works or no snapshot is recorded, since the repo dir itself
    is not loadable."""
    from hub.utils.hf_cache_state import snapshot_selection_key

    repo_path = getattr(repo_info, "repo_path", None)
    if repo_path is None or active_root is None:
        return None
    try:
        if repo_path.parent.resolve(strict = False) == active_root:
            ref_snapshot = _default_ref_snapshot(repo_path)
            if ref_snapshot is not None and snapshot_has_complete_variants(str(ref_snapshot)):
                return None
    except (OSError, RuntimeError, ValueError):
        pass
    # Shared selection key, so this route and the /gguf-variants lister name one snapshot.
    candidates = [
        Path(snapshot)
        for revision in repo_info.revisions
        if (snapshot := getattr(revision, "snapshot_path", None)) is not None
        and any(
            _is_main_gguf_filename(_cached_repo_file_name(f)) for f in cached_repo_files(revision)
        )
    ]
    candidates.sort(key = snapshot_selection_key, reverse = True)
    # Newest first, skipping any holding no whole quant, else a torn download beats a loadable one.
    for snapshot in candidates:
        if snapshot_has_complete_variants(str(snapshot)):
            return str(snapshot)
    # No complete snapshot: return None, since a partial path fails on load; the repo id fetches shards
    return None


def _preferred_gguf_copy(
    rows: dict, ranks: dict, key: str, candidate: tuple[bool, bool], size: int
) -> bool:
    """Whether this copy should replace the one already kept for *key*, in the order the Hub inventory
    deduplicates by: a copy that cannot load loses to one that can, then the active cache wins, then
    the larger download."""
    existing = rows.get(key)
    if existing is None:
        return True
    kept = ranks.get(key, (True, True))
    if candidate[0] != kept[0]:
        return candidate[0]
    if candidate[1] != kept[1]:
        return candidate[1]
    return size > int(existing.get("size_bytes") or 0)


@router.get("/cached-gguf")
async def list_cached_gguf(
    current_subject: str = Depends(get_current_subject),
    via_api_key: bool = Depends(authenticated_via_api_key),
):
    """List GGUF repos downloaded to HF cache, legacy Unsloth cache, and HF default cache."""
    try:
        # Off the loop: the filter can probe the Hub per ungranted repo.
        return redact_host_paths(
            {"cached": await asyncio.to_thread(cached_gguf_rows)}, via_api_key = via_api_key
        )
    except Exception as e:
        logger.error("Error listing cached GGUF repos: %s", scrub_paths(e), exc_info = True)
        return {"cached": []}


@in_scan_memo
def cached_gguf_rows(cache_scans = None) -> list[dict]:
    if cache_scans is None:
        cache_scans = _all_hf_cache_scans()
    try:
        active_root = _resolve_hf_cache_dir().resolve(strict = False)
    except Exception:
        active_root = None

    seen_lower: dict[str, dict] = {}
    # keep active-cache rank beside rows; the compatibility schema only exposes partialness.
    seen_rank: dict[str, tuple[bool, bool]] = {}
    for hf_cache in cache_scans:
        for repo_info in hf_cache.repos:
            try:
                if repo_info.repo_type != "model":
                    continue
                repo_id = repo_info.repo_id
                # Pass the snapshot path too so the config check also hides custom Whisper checkpoints.
                if _is_hidden_model(repo_id, str(repo_info.repo_path)):
                    continue
                total_size = _repo_gguf_size_bytes(repo_info)
                if total_size == 0:
                    continue
                key = repo_id.lower()
                existing = seen_lower.get(key)
                last_modified = _repo_gguf_last_modified(repo_info)
                load_id = _repo_gguf_load_id(repo_info, active_root)
                selected = (
                    Path(load_id) if load_id else _default_ref_snapshot(Path(repo_info.repo_path))
                )
                rank = (
                    _gguf_copy_is_usable(repo_info, load_id, active_root),
                    active_root is not None
                    and Path(repo_info.repo_path).parent.resolve(strict = False) == active_root,
                )
                if _preferred_gguf_copy(seen_lower, seen_rank, key, rank, total_size):
                    row = {
                        "repo_id": repo_id,
                        "size_bytes": total_size,
                        "cache_path": str(repo_info.repo_path),
                        "has_vision": _cached_gguf_row_has_vision(repo_info, load_id),
                        "task": _repo_gguf_task(repo_info, selected),
                    }
                    if load_id:
                        row["load_id"] = load_id
                    if not rank[0]:
                        row["partial"] = True
                    # Keep the newest timestamp across duplicate caches; absent rows sort as oldest.
                    lm = max(last_modified, (existing or {}).get("last_modified", 0.0))
                    if lm > 0:
                        row["last_modified"] = lm
                    seen_lower[key] = row
                    seen_rank[key] = rank
                elif last_modified > existing.get("last_modified", 0.0):
                    existing["last_modified"] = last_modified
            except Exception as e:
                repo_label = getattr(repo_info, "repo_id", "<unknown>")
                logger.warning(f"Skipping cached GGUF repo {repo_label}: {e}")
                continue
    # Newest download first; stable repo_id tie-break for equal/missing mtimes.
    return account_access.filter_model_rows(
        sorted(
            seen_lower.values(),
            key = lambda c: (-(c.get("last_modified") or 0.0), c["repo_id"].lower()),
        )
    )


def _repo_pipeline_missing_denoiser(repo_info, selected: Optional[Path] = None) -> bool:
    """Companion-only-prefetch check for the snapshot this row loads."""
    from hub.utils import inventory_scan as hf_cache_scan

    if selected is not None:
        return hf_cache_scan.snapshot_pipeline_missing_denoiser(selected)
    return hf_cache_scan.repo_pipeline_missing_denoiser(repo_info)


def _cached_repo_partial(
    repo_id: str,
    repo_cache_dir: Optional[Path] = None,
    snapshot_dir: Optional[Path] = None,
) -> bool:
    """Needs repo_cache_dir and snapshot_dir; else a newer partial revision flags it; errors: not partial"""
    try:
        from hub.utils.inventory_scan import is_snapshot_partial
        return bool(is_snapshot_partial("model", repo_id, repo_cache_dir, snapshot_dir))
    except Exception:  # noqa: BLE001 -- never fail the listing over a partial probe
        return False


@router.get("/cached-models", response_model = CachedModelsResponse)
async def list_cached_models(
    current_subject: str = Depends(get_current_subject),
    hf_token: HfTokenArg = Depends(get_request_hf_token),
    via_api_key: bool = Depends(authenticated_via_api_key),
):
    """List non-GGUF model repos downloaded to HF cache, legacy Unsloth cache, and HF default cache."""
    try:
        # Off the loop: the filter can probe the Hub per ungranted repo.
        return redact_host_paths(
            {"cached": await asyncio.to_thread(cached_model_rows)}, via_api_key = via_api_key
        )
    except Exception as e:
        logger.error("Error listing cached models: %s", scrub_paths(e), exc_info = True)
        return {"cached": []}


# Row gate only; broader than the prefix rule since legacy diffusers ship diffusion_pytorch_model.bin.
_NON_GGUF_WEIGHT_EXTENSIONS = (".safetensors", ".bin")


def _snapshot_can_serve_a_load(snapshot: Path) -> bool:
    """Check contents, not mtime: a partial fetch leaves an unloadable dir newer than a complete one."""
    if _local_pipeline_index(snapshot):
        from core.inference.media_locality import _pipeline_components_present
        from hub.utils.inventory_scan import snapshot_pipeline_missing_denoiser
        return _pipeline_components_present(snapshot) and not snapshot_pipeline_missing_denoiser(
            snapshot
        )
    return _is_model_directory(snapshot) and not _snapshot_payload_is_torn(snapshot)


def _snapshot_payload_is_torn(snapshot: Optional[Path]) -> bool:
    """See hub.utils.inventory_scan; True when the snapshot proves its payload incomplete."""
    from hub.utils.inventory_scan import _snapshot_cannot_serve_its_payload
    return _snapshot_cannot_serve_its_payload(snapshot)


def _default_ref_snapshot(repo_cache_dir: Path) -> Optional[Path]:
    """See hub.utils.inventory_scan; the snapshot dir ``refs/main`` names, or ``None``."""
    from hub.utils.inventory_scan import default_ref_snapshot
    return default_ref_snapshot(repo_cache_dir)


def _repo_model_snapshots(repo_info) -> list:
    """Snapshot dirs of a cached non-GGUF repo, newest selection order first."""
    from hub.utils.hf_cache_state import snapshot_selection_key

    candidates = [
        Path(snapshot)
        for revision in getattr(repo_info, "revisions", ()) or ()
        if (snapshot := getattr(revision, "snapshot_path", None)) is not None
    ]
    candidates.sort(key = snapshot_selection_key, reverse = True)
    return candidates


def _repo_is_reachable_by_id(repo_path: Path, active_root: Path, loadable: Optional[Path]) -> bool:
    """Bare id follows refs/main, which can name a half-fetched snapshot that resolves then fails."""
    try:
        if repo_path.parent.resolve(strict = False) != active_root:
            return False
        if _repo_id_will_not_resolve(repo_path):
            return False
    except (OSError, RuntimeError, ValueError):
        return False
    if loadable is None:
        return True
    # huggingface_hub writes refs/<rev> only when rev != commit, so no refs/main is unresolvable.
    ref_snapshot = _default_ref_snapshot(repo_path)
    return ref_snapshot is not None and _snapshot_can_serve_a_load(ref_snapshot)


def _repo_model_selection(
    repo_info, active_root: Optional[Path]
) -> tuple[Optional[Path], Optional[str]]:
    """One revision answers for every field, so a stale older revision cannot speak for the row."""
    repo_path = getattr(repo_info, "repo_path", None)
    if repo_path is None or active_root is None:
        return None, None
    usable = []
    for snapshot in _repo_model_snapshots(repo_info):
        try:
            if snapshot.is_dir():
                usable.append(snapshot)
        except OSError:
            continue
    # Newest snapshot a load can be served from, since the newest dir may be a half-fetched partial.
    loadable = next((s for s in usable if _snapshot_can_serve_a_load(s)), None)
    if _repo_is_reachable_by_id(Path(repo_path), active_root, loadable):
        # The bare id follows refs/main, so that ref names the revision a load reads.
        return _default_ref_snapshot(Path(repo_path)) or loadable, None
    # No snapshot can prove it serves a load, so keep the previous newest-dir pin rather than drop it.
    selected = loadable or (usable[0] if usable else None)
    return selected, (str(selected) if selected else None)


def _repo_model_load_id(repo_info, active_root: Optional[Path]) -> Optional[str]:
    """Snapshot dir for a repo cached outside the active cache; a bare id would re-download."""
    return _repo_model_selection(repo_info, active_root)[1]


def _repo_model_format(repo_info, selected: Optional[Path] = None) -> Optional[str]:
    """``"adapter"`` for a cached LoRA/PEFT repo, else ``None``. ``cached_model_rows`` set no format, so
    every consumer filtering out adapters compared against a key that never existed. An adapter ships
    ``adapter_config.json``; a merge does not. Judged on the selected revision."""
    for snapshot in [selected] if selected is not None else _repo_model_snapshots(repo_info):
        try:
            if (snapshot / "adapter_config.json").is_file():
                return "adapter"
        except OSError:
            continue
    return None


def _repo_model_can_chat(repo_info, selected: Optional[Path] = None) -> Optional[bool]:
    """False for encoder-only repos (embedding, CLIP, ViT), else None so unknowns are never hidden."""
    from hub.services.models.common import _local_transformers_can_chat, _read_local_json_object

    ordered = _repo_model_snapshots(repo_info)
    if selected is not None:
        verdict = _local_transformers_can_chat(selected)
        if verdict is not None or _read_local_json_object(selected / "config.json"):
            return verdict
        ordered = [s for s in ordered if s != selected]
    for snapshot in ordered:
        verdict = _local_transformers_can_chat(snapshot)
        if verdict is not None:
            return verdict
    return None


def _repo_hosts_artifacts(repo_id: str) -> bool:
    """``mirror_hosts_artifacts``, False when the family tables are unavailable."""
    try:
        from core.inference.diffusion_families import mirror_hosts_artifacts
        return mirror_hosts_artifacts(repo_id)
    except Exception:  # noqa: BLE001 -- no table means no artifact mirrors
        return False


@in_scan_memo
def cached_model_rows(cache_scans = None) -> list[dict]:
    _WEIGHT_EXTENSIONS = _NON_GGUF_WEIGHT_EXTENSIONS
    if cache_scans is None:
        cache_scans = _all_hf_cache_scans()
    try:
        active_root = _resolve_hf_cache_dir().resolve(strict = False)
    except Exception:
        active_root = None

    seen_lower: dict[str, dict] = {}
    cache_scans = list(cache_scans)
    # Across EVERY root, as the cached-model scan decides it: an artifact mirror whose GGUF sits in one root and
    # whose diffusers folders sit in the other is a GGUF repo, so its folders-only copy is no row of this listing.
    try:
        from hub.services.models.cache_inventory import _artifact_gguf_repo_ids
        artifact_gguf_keys = _artifact_gguf_repo_ids(cache_scans)
    except Exception:  # noqa: BLE001 -- no table means no artifact mirrors
        artifact_gguf_keys = set()
    for hf_cache in cache_scans:
        for repo_info in hf_cache.repos:
            try:
                if repo_info.repo_type != "model":
                    continue
                repo_id = repo_info.repo_id
                # Pass the snapshot path too so the config check also hides custom Whisper checkpoints.
                if _is_hidden_model(repo_id, str(repo_info.repo_path)):
                    continue
                if _repo_has_gguf_files(repo_info):
                    continue
                # Its GGUF in another root: listed (its delete is scoped to this root and frees what it shows) but as
                # a companion of that GGUF, never a single-file or pipeline pick.
                cross_root_folders = repo_id.lower() in artifact_gguf_keys
                selected, model_load_id = _repo_model_selection(repo_info, active_root)
                if _recovered_repo_is_unusable_by_repo_id(repo_info):
                    # Schema now carries load_id, so a recovery holding a serving snapshot is listed pinned to it.
                    if not (
                        model_load_id is not None
                        and selected is not None
                        and _snapshot_can_serve_a_load(selected)
                    ):
                        continue
                from hub.services.models.cache_inventory import repo_unique_size_bytes

                total_size = repo_unique_size_bytes(repo_info)
                if total_size == 0:
                    continue
                weight_files = [
                    f for f in _cached_files(repo_info) if f.file_name.endswith(_WEIGHT_EXTENSIONS)
                ]
                if not weight_files:
                    continue
                last_modified = max(
                    (_blob_mtime(f) for f in weight_files),
                    default = 0.0,
                )
                key = repo_id.lower()
                existing = seen_lower.get(key)
                # A companion-only prefetch (manifest + VAE/TE but no transformer shards) is not a loadable pipeline; treat it as partial.
                # The FP8 artifact mirror lists as its root checkpoint, as released builds did: its diffusers folders
                # belong to the BASE pick, and a pipeline pick of the repo itself is refused.
                artifact_checkpoint = _repo_hosts_artifacts(repo_id) and not cross_root_folders
                is_partial = _cached_repo_partial(repo_id, Path(repo_info.repo_path), selected) or (
                    not artifact_checkpoint and _repo_pipeline_missing_denoiser(repo_info, selected)
                )
                # Prefer the most COMPLETE snapshot, then largest: a partial copy in one cache root must not shadow a complete copy in another.
                if existing is None or (not is_partial, total_size) > (
                    not bool(existing.get("partial")),
                    existing["size_bytes"],
                ):
                    row_task = _cached_repo_task(repo_info, selected)
                    is_diffusers = _repo_is_diffusers(repo_info, selected)
                    has_pipeline_index = not artifact_checkpoint and _repo_has_pipeline_index(
                        repo_info, selected
                    )
                    row = {
                        "repo_id": repo_id,
                        "size_bytes": total_size,
                        "task": row_task,
                    }
                    pipeline_artifact_kind = (
                        None if artifact_checkpoint else _diffusers_pipeline_artifact_kind(selected)
                    )
                    if pipeline_artifact_kind is not None:
                        row["artifact_kind"] = pipeline_artifact_kind
                    # Pin a copy its bare id cannot reach, so the pick loads the found snapshot.
                    if row_task is None and pipeline_artifact_kind is not None:
                        row["load_id"] = str(selected)
                    elif model_load_id:
                        row["load_id"] = model_load_id
                    model_format = _repo_model_format(repo_info, selected)
                    if model_format:
                        row["model_format"] = model_format
                    # Without this the picker offers an embedding or CLIP repo as a chat model.
                    if _repo_model_can_chat(repo_info, selected) is False:
                        row["can_chat"] = False
                    # None task is shared with every chat repo, so an unloadable diffusion repo must say can_chat False.
                    if is_diffusers:
                        row["diffusers"] = True
                    if is_partial:
                        row["partial"] = True
                    # Listed, so tens of GB of companion weights stay visible and deletable,
                    # but flagged, so no picker offers a denoiser-less repo as a load.
                    if _is_sd_cpp_companion_repo(repo_id) or cross_root_folders:
                        row["companion"] = True
                    # Flag diffusion repos with no pipeline index: loadable only via from_single_file, so pickers must not offer a pipeline load.
                    if row["task"] is not None and not has_pipeline_index:
                        row["single_file"] = True
                    # Keep the newest timestamp across duplicate caches; absent rows sort as oldest.
                    lm = max(last_modified, (existing or {}).get("last_modified", 0.0))
                    if lm > 0:
                        row["last_modified"] = lm
                    seen_lower[key] = row
                elif last_modified > existing.get("last_modified", 0.0):
                    existing["last_modified"] = last_modified
            except Exception as e:
                repo_label = getattr(repo_info, "repo_id", "<unknown>")
                logger.warning(f"Skipping cached model repo {repo_label}: {e}")
                continue

    # Local-only list path: update checks are GGUF-only and happen lazily when variants are viewed.
    return account_access.filter_model_rows(
        sorted(
            seen_lower.values(),
            key = lambda c: (-(c.get("last_modified") or 0.0), c["repo_id"].lower()),
        )
    )


def _loaded_id_matches_repo(loaded_id: str, repo_id: str) -> bool:
    """True when *loaded_id* is *repo_id* or a file within it; ``/``-boundary aware so a
    loaded ``org/model-2512`` does not block deleting the sibling cached ``org/model``."""
    rid = repo_id.lower()
    lid = loaded_id.lower()
    return lid == rid or lid.startswith(f"{rid}/")


@router.delete("/delete-cached")
async def delete_cached_model(
    repo_id: str = Body(...),
    variant: Optional[str] = Body(None),
    cache_path: Optional[str] = Body(None),
    hf_token: HfTokenArg = Depends(get_request_hf_token),
    current_subject: str = Depends(get_current_subject),
):
    """Compatibility route backed by the shared multi-cache deletion service."""
    account_access.require_installation_owner()
    from hub.services.models import deletion

    # API-key callers have only the reference to name one copy; omitting it acts on the active root.
    return await deletion.delete_cached_model_response(
        repo_id, variant, hf_token, resolve_host_path_reference(cache_path) or cache_path
    )


def _resolve_cached_model_path(repo_id: str, variant: Optional[str]) -> Path:
    """Absolute path of a cached repo (newest snapshot dir) or, with *variant*, that quant's main GGUF file
    (first split of a sharded quant). Paths come from the HF cache scan only, so callers cannot probe
    arbitrary paths."""

    cache_scans = _all_hf_cache_scans()

    matching_repos = []
    for hf_cache in cache_scans:
        for repo_info in hf_cache.repos:
            if repo_info.repo_type != "model":
                continue
            if repo_info.repo_id.lower() == repo_id.lower():
                matching_repos.append(repo_info)
    if not matching_repos:
        raise HTTPException(status_code = 404, detail = "Model not found in cache")

    if variant:
        from hub.utils.gguf_sources import cached_gguf_sources

        source = cached_gguf_sources(repo_id).get(variant.strip().lower())
        if source is not None:
            path = source.snapshot / source.variant.filename
            if path.is_file():
                return path
        want = (variant or "").strip()
        candidate_revisions = sorted(
            (rev for repo_info in matching_repos for rev in repo_info.revisions),
            key = lambda rev: getattr(rev, "last_modified", 0) or 0,
            reverse = True,
        )
        for rev in candidate_revisions:
            snapshot = getattr(rev, "snapshot_path", None)
            ranked: dict[int, list[tuple[str, Path]]] = {0: [], 1: []}
            for f in rev.files:
                p = Path(f.file_path)
                rel = f.file_name
                if snapshot:
                    try:
                        rel = p.relative_to(snapshot).as_posix()
                    except ValueError:
                        pass
                rank = _main_variant_rank(rel, want)
                if rank is None:
                    continue
                # Listed as a file of the revision, and keyed like the weights beside it.
                if is_appledouble_metadata(p):
                    continue
                if p.exists() or p.is_symlink():
                    ranked[rank].append((rel, p))
            # Exact keys alone when any exist, else the legacy label spelling.
            matches = ranked[0] or ranked[1]
            if matches:
                # Path-sorted so a sharded quant deterministically yields its first split.
                return sorted(matches, key = lambda m: m[0].lower())[0][1]
        raise HTTPException(
            status_code = 404,
            detail = f"Variant {variant} not found in cache for {repo_id}",
        )

    def repo_size(repo_info) -> int:
        gguf_size = _repo_gguf_size_bytes(repo_info)
        if gguf_size > 0:
            return gguf_size
        return sum(
            (getattr(f, "size_on_disk", None) or 0)
            for rev in repo_info.revisions
            for f in rev.files
        )

    def repo_last_modified(repo_info) -> float:
        return max(
            (getattr(rev, "last_modified", 0) or 0 for rev in repo_info.revisions),
            default = 0,
        )

    target_repo = max(
        matching_repos,
        key = lambda repo_info: (repo_size(repo_info), repo_last_modified(repo_info)),
    )

    # Whole repo: the newest revision's snapshot dir holds the visible files.
    revisions = sorted(
        (rev for rev in target_repo.revisions if getattr(rev, "snapshot_path", None)),
        key = lambda rev: getattr(rev, "last_modified", 0) or 0,
        reverse = True,
    )
    for rev in revisions:
        p = Path(rev.snapshot_path)
        if p.exists():
            return p
    p = Path(target_repo.repo_path)
    if p.exists():
        return p
    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


@router.get("/cached-model-path", response_model = CachedModelPathResponse)
async def get_cached_model_path(
    repo_id: str = Query(..., description = "HuggingFace repo ID"),
    variant: str = Query("", description = "Quantization variant (empty for whole repo)"),
    current_subject: str = Depends(get_current_subject),
):
    """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)
    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()}


@router.post("/reveal-cached-model")
async def reveal_cached_model(
    repo_id: str = Body(...),
    variant: Optional[str] = Body(None),
    current_subject: str = Depends(get_current_subject),
):
    """Reveal a cached repo (or one GGUF variant's file) in the OS file manager."""
    account_access.require_installation_owner()
    if account_access.managed_account():
        await asyncio.to_thread(account_access.require_model_access, repo_id)
    from utils.paths.path_utils import reveal_in_file_manager

    variant = (variant or "").strip() or None
    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:
        logger.error(f"Failed to reveal {path}: {e}")
        raise HTTPException(status_code = 500, detail = "Failed to open file manager")
    return {"status": "ok", "path": str(path)}


@router.get("/checkpoints", response_model = CheckpointListResponse)
async def list_checkpoints(
    outputs_dir: str = Query(
        default = str(outputs_root()),
        description = "Directory to scan for checkpoints",
    ),
    current_subject: str = Depends(get_current_subject),
):
    """List checkpoints in the outputs directory.

    Scans the outputs folder for training runs and their checkpoints.
    """
    outputs_dir = account_access.private_directory(outputs_dir, "outputs")
    try:
        resolved_outputs_dir = str(resolve_output_dir(outputs_dir))
        # Reads every checkpoint's trainer_state.json: keep it off the event loop.
        raw_models = await asyncio.to_thread(
            scan_checkpoints, outputs_dir = resolved_outputs_dir, include_decision = True
        )

        models = [
            ModelCheckpoints(
                name = model_name,
                checkpoints = [
                    CheckpointInfo(display_name = display_name, path = path, loss = loss)
                    for display_name, path, loss in checkpoints
                ],
                base_model = metadata.get("base_model"),
                peft_type = metadata.get("peft_type"),
                lora_rank = metadata.get("lora_rank"),
                is_quantized = metadata.get("is_quantized", False),
                adapter_features = metadata.get("adapter_features"),
            )
            for model_name, checkpoints, metadata in raw_models
        ]

        return CheckpointListResponse(
            outputs_dir = resolved_outputs_dir,
            models = models,
        )
    except Exception as e:
        raise log_and_http_error(
            e,
            500,
            "Failed to list checkpoints",
            event = "models.list_checkpoints_failed",
            log = logger,
        )


# Successful estimates only, keyed by model id. Failures aren't cached so they can recover.
_EXPORT_SIZE_CACHE: dict[object, tuple[int, int, str]] = {}


def _is_sizable_local_path(model: str) -> bool:
    """True only for local paths under an Unsloth data root. Containment is decided lexically (no filesystem
    access) before the path is touched, then the path is symlink-resolved and re-checked so a symlink inside
    a root cannot point the sizer outside it."""
    from utils.paths import outputs_root, exports_root, studio_root
    from utils.paths.storage_roots import cache_root

    def _lexical(p: str) -> str:
        # Lexical only (no filesystem read); normpath collapses '..'.
        return os.path.normpath(os.path.abspath(os.path.expanduser(p)))

    raw_roots = [studio_root(), outputs_root(), exports_root(), cache_root()]
    roots = []
    for root in raw_roots:
        try:
            roots.append(_lexical(str(root)))
        except (OSError, RuntimeError, ValueError):
            continue

    try:
        candidate = _lexical(model)
    except (OSError, RuntimeError, ValueError):
        return False
    for root in roots:
        if candidate == root or candidate.startswith(root + os.sep):
            # Contained lexically; resolve symlinks and re-verify before touching the filesystem.
            try:
                real = os.path.realpath(candidate)
            except (OSError, RuntimeError, ValueError):
                return False
            for raw in raw_roots:
                try:
                    real_root = os.path.realpath(str(raw))
                except (OSError, RuntimeError, ValueError):
                    continue
                if real == real_root or real.startswith(real_root + os.sep):
                    return os.path.exists(real)
            return False
    return False


def _export_size_cached(
    model: str, hf_token: Optional[str]
) -> tuple[Optional[int], Optional[int], str]:
    """Blocking I/O, so call off-thread; failures return unavailable and are never cached."""
    # Keyed per managed account: a relative model name is private to a workspace.
    cache_key = (
        (account_access.current_account_id(), model) if account_access.managed_account() else model
    )
    cached = _EXPORT_SIZE_CACHE.get(cache_key)
    if cached is not None:
        return cached
    try:
        from utils.hardware.hardware import (
            _resolve_model_identifier_for_gpu_estimate,
            estimate_fp16_model_size_bytes,
        )

        # Re-validate the adapter's base so a crafted adapter can't escape the roots.
        if is_local_path(model):
            base = _resolve_model_identifier_for_gpu_estimate(model, hf_token = hf_token)
            if is_local_path(base) and not _is_sizable_local_path(base):
                return None, None, "unavailable"

        fp16_bytes, source = estimate_fp16_model_size_bytes(model, hf_token = hf_token)
        if not fp16_bytes or fp16_bytes <= 0:
            return None, None, source or "unavailable"
        result = (int(fp16_bytes), int(fp16_bytes) // 2, source)
        _EXPORT_SIZE_CACHE[cache_key] = result
        return result
    except Exception as e:  # a size hint must never break export
        logger.warning("Could not estimate export size for '%s': %s", model, e)
        return None, None, "unavailable"


@router.get("/export-size", response_model = ExportSizeResponse)
async def get_export_size(
    model: str = Query(..., description = "Base model id or local model path to size"),
    hf_token: Optional[str] = Header(None, alias = "X-HF-Token"),
    current_subject: str = Depends(get_current_subject),
):
    """Estimate a model's fp16/bf16-equivalent size for the Export page.

    Returns nulls with HTTP 200 when the size can't be determined. The HF token
    (for gated repos) comes from the X-HF-Token header so it never hits URLs/logs.
    """
    await _require_model_access_or_caller_token(model, _normalize_hf_token(hf_token))
    if is_local_path(model):
        if not _is_sizable_local_path(model):
            return ExportSizeResponse(
                model = model, fp16_bytes = None, total_params = None, source = "unavailable"
            )
        resolved = model
    else:
        resolved = resolve_cached_repo_id_case(model)
    # Blocking network/disk I/O: run off the event loop.
    fp16_bytes, total_params, source = await asyncio.to_thread(
        _export_size_cached, resolved, hf_token
    )
    return ExportSizeResponse(
        model = resolved,
        fp16_bytes = fp16_bytes,
        total_params = total_params,
        source = source,
    )