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.

6.6 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

"""DFlash sidecar discovery for a local GGUF model. DFlash is published as a ``dflash-`` prefixed sibling of the weights it drafts for, so discovery is a naming question first and a header question second. That order is deliberate: a caller with a directory lease (a native grant) hands in ``accept``, and that has to answer before anything is opened, because reading the header of a symlink pointing out of the lease is the very thing the lease exists to prevent, and no later rejection takes a read back."""

import logging
import os
from pathlib import Path
from typing import Callable, Optional

from utils.models.gguf_metadata import read_gguf_architecture
from utils.models.drafters.common import (
    _drafter_launch_path,
    _drafter_matches_weight,
    _drafter_names_other_weight,
    _drafter_split_is_complete,
    _drafter_stem_rank,
    _drafter_total_size,
)
from utils.models.drafters.preference import (
    dflash_precision_rank,
    dflash_preference_key,
    dflash_repo_preference_key,
)

logger = logging.getLogger(__name__)


def is_dflash_architecture(path: str) -> bool:
    """Decided by header general.architecture = dflash, which no real weight declares; a dflash- filename can name a real weight, so downloads trust only the header."""
    return (read_gguf_architecture(str(path)) or "").lower() == "dflash"


def detect_dflash_file(
    path: str,
    search_root: Optional[str] = None,
    accept: Optional[Callable[[str], bool]] = None,
) -> Optional[str]:
    """Root level only, not dflash/ (a family name for real weights); header checked, since dflash-kquant.gguf names no family; a family-named sidecar ranks first."""
    from utils.models.model_config import _local_gguf_load_path

    def _rank(candidate: Path) -> tuple[int, int, int, int, str]:
        # A sidecar naming THIS weight's family first, then any unpaired one, then precision, then total size so a split copy cannot outrank a smaller single file, then name for a stable order.
        paired = _drafter_matches_weight(candidate.name, weight_name, kind = "dflash")
        return (
            0 if paired else 1,
            _drafter_stem_rank(candidate.name, kind = "dflash") if paired else 0,
            dflash_precision_rank(candidate.name),
            _drafter_total_size(candidate),
            candidate.name.lower(),
        )

    p = Path(path)
    weight_name = p.name if p.suffix.lower() == ".gguf" else None
    start_dir = p.parent if p.is_file() else p
    # Not assets/: the sidecar names no family, so it is ambiguous in Hermes' shared pool.
    dirs = [start_dir]
    if search_root is not None:
        dirs.append(Path(search_root))

    candidates: list[Path] = []
    other_weights: list[str] = []
    seen: set[Path] = set()
    # dict.fromkeys: search_root is the weight's own parent for a flat layout, and scanning it twice doubles the directory reads for nothing.
    for root in dict.fromkeys(dirs):
        try:
            entries = list(root.iterdir())
        except OSError:
            continue
        for candidate in entries:
            lower = candidate.name.lower()
            if not lower.endswith(".gguf"):
                continue
            # Prefix form only: the shared predicates (_drafter_path_kind / is_mtp_drafter_path) know DFlash by the dflash- prefix, so accepting <model>-dflash.gguf would make one file both a drafter and a selectable Q8_0 main model (#7811). No published DFlash sidecar uses the suffix form; the shipped one is dflash-kquant.gguf.
            if not lower.startswith("dflash-"):
                # Every other GGUF in the folder is a weight some sidecar could be naming. Recorded so a sidecar belonging to a NEIGHBOUR can be told apart from one naming no family at all (below).
                other_weights.append(candidate.name)
                continue
            try:
                # Collapse a split copy to shard 1 before ranking.
                launch = _local_gguf_load_path(candidate)
                # is_file() follows the link, so this also drops a dangling snapshot symlink and a directory named like a sidecar, which --model-draft cannot open and which fails the whole load. detect_dspark_file guards the same way.
                if not (launch.is_file() and _drafter_split_is_complete(launch)):
                    continue
                resolved = launch.resolve()
            except OSError:
                continue
            if resolved in seen:
                continue
            seen.add(resolved)
            candidates.append(launch)

    # A sidecar naming a NEIGHBOUR weight's family is that neighbour's drafter: ranking alone floated the foreign one to the top, so loading model B beside dflash-model-A-Q8_0.gguf and dflash-kquant.gguf launched model A's drafter for model B, and both carry a real dflash header so the architecture check cannot catch it. _drafter_names_other_weight decides against the weights actually present and is shared with the remote paths through dflash_repo_preference_key.
    if weight_name is not None and other_weights:
        kept: list[Path] = []
        for candidate in candidates:
            if _drafter_names_other_weight(candidate.name, weight_name, other_weights):
                logger.info(
                    "detect_dflash_file: dropped %s (names another weight in this folder)",
                    candidate.name,
                )
                continue
            kept.append(candidate)
        candidates = kept

    for candidate in sorted(candidates, key = _rank):
        # Resolve and validate before opening anything: a dflash-*.gguf reached through a native grant can be a symlink outside the lease, and reading the header first cannot be undone.
        try:
            launch = _drafter_launch_path(candidate)
        except OSError:
            continue
        if accept is not None and not accept(launch):
            logger.info(
                "detect_dflash_file: dropped %s (outside the granted directory)",
                candidate.name,
            )
            continue
        if not is_dflash_architecture(launch):
            logger.info(
                "detect_dflash_file: dropped %s (architecture %r is not dflash)",
                candidate.name,
                # Re-read only on the reject path, and header reads are cached by (path, mtime, size), so naming the offending architecture in the log costs nothing.
                read_gguf_architecture(launch),
            )
            continue
        logger.info("Detected DFlash drafter: %s", launch)
        return launch
    return None