hugpy-engine 0.2.3__tar.gz → 0.2.4__tar.gz

{hugpy_engine-0.2.3/src/hugpy_engine.egg-info → hugpy_engine-0.2.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: hugpy-engine
-Version: 0.2.3
+Version: 0.2.4
 Summary: Hugpy engine: model discovery and classification, allocation and eviction, native llama.cpp and GGUF runners, and the prompt-to-reply inference path with task and placement seams
 Author-email: putkoff <support@hugpy.ai>
 License-Expression: LicenseRef-Proprietary

{hugpy_engine-0.2.3 → hugpy_engine-0.2.4}/src/hugpy_engine/apis/get_module.py

@@ -133,6 +133,25 @@ def get_all_configs(verbose: bool = False, get_code: bool = False,
 
         hub_id = clean_hub_id(directory, folder)
         framework = (marker or {}).get("framework") or infer_framework(directory)
+        marked_context = (marker or {}).get("model_max_length")
+        if (isinstance(marked_context, (int, float)) and
+                not isinstance(marked_context, bool) and marked_context > 0):
+            max_model_length = int(marked_context)
+        elif framework == "gguf":
+            # Legacy registry walk also needs the trained context. The generic
+            # JSON scanner has no GGUF metadata and otherwise substitutes the
+            # global default for models whose marker predates context capture.
+            try:
+                from hugpy_engine.config.main import get_gguf_file
+                from hugpy_storage.gguf_inspect import gguf_metadata
+                gguf_path = get_gguf_file(
+                    directory, None, prefer=(marker or {}).get("filename"))
+                context = (gguf_metadata(gguf_path, (".context_length",))
+                           .get(".context_length") if gguf_path else None)
+                if isinstance(context, (int, float)) and not isinstance(context, bool) and context > 0:
+                    max_model_length = int(context)
+            except Exception as exc:  # noqa: BLE001 — best-effort metadata only
+                logger.debug("GGUF context unavailable for %s: %s", name, exc)
         tasks = (marker or {}).get("tasks") or tasks_data.get(name)
         primary_task = (marker or {}).get("primary_task") or (tasks[0] if tasks else None)
 
@@ -278,12 +297,36 @@ def resolve_hugpy_marker(directory: str, hub_id: str) -> dict:
     tasks = marker.get("tasks")
     if tasks is not None and not isinstance(tasks, list):
         tasks = [tasks]
-    return {k: v for k, v in {
+    out = {k: v for k, v in {
         "name":         marker.get("name"),
         "framework":    marker.get("framework"),
         "tasks":        tasks,
         "primary_task": marker.get("primary_task"),
     }.items() if v is not None}
+    context = marker.get("model_max_length")
+    if isinstance(context, (int, float)) and not isinstance(context, bool) and context > 0:
+        out["model_max_length"] = int(context)
+    return out
+
+
+def resolve_gguf_context(directory: str, hub_id: str) -> dict:
+    """Read the selected GGUF's trained context from its header."""
+    try:
+        from hugpy_storage.hugpy_marker import read_hugpy_marker
+        marker = read_hugpy_marker(directory) or {}
+        if (marker.get("framework") or infer_framework(directory)) != "gguf":
+            return {}
+        from hugpy_engine.config.main import get_gguf_file
+        from hugpy_storage.gguf_inspect import gguf_metadata
+        gguf = get_gguf_file(directory, None, prefer=marker.get("filename"))
+        if not gguf:
+            return {}
+        value = gguf_metadata(gguf, (".context_length",)).get(".context_length")
+        if isinstance(value, (int, float)) and not isinstance(value, bool) and value > 0:
+            return {"model_max_length": int(value)}
+    except Exception as exc:  # noqa: BLE001 — metadata inspection must not block discovery
+        logger.debug("GGUF context unavailable for %s: %s", hub_id, exc)
+    return {}
 
 
 # Storage families that imply a framework. "misc" implies nothing — comfy and
@@ -374,6 +417,7 @@ def build_resolver_chain(*, api: Any = None,
     chain: List[Tuple[str, ResolverFn]] = [
         ("dir_declaration", resolve_dir_declaration),
         ("hugpy_marker",    resolve_hugpy_marker),
+        ("gguf_context",    resolve_gguf_context),
         ("local_config",    resolve_local_config),
         ("local_tokenizer", resolve_local_tokenizer),
     ]
@@ -441,7 +485,8 @@ def discover_model(save_json: bool = True, verbose: bool = True, use_hub: bool =
             "architectures":           meta.architectures,
             "model_type":              meta.model_type,
             "max_position_embeddings": meta.max_position_embeddings,
-            "model_max_length":        meta.tokenizer_model_max_length
+            "model_max_length":        meta.model_max_length
+                                       or meta.tokenizer_model_max_length
                                        or meta.max_position_embeddings
                                        or DEFAULT_MAX_TOKENS,
             "parameter_count":         meta.parameter_count,
@@ -484,6 +529,9 @@ def discover_models(save_json: bool = True, verbose: bool = True, use_hub: bool
         meta, meta_sources = enrich(directory, hub_id, chain)
 
         row = meta.to_dict()
+        row["model_max_length"] = (meta.model_max_length
+                                   or meta.tokenizer_model_max_length
+                                   or meta.max_position_embeddings)
         # Declared name (hugpy.json) wins; the bare basename is the fallback —
         # a marker-stamped "comfy-sd-turbo" must not degrade to "sd-turbo" and
         # collide with the staple's display name.

{hugpy_engine-0.2.3 → hugpy_engine-0.2.4}/src/hugpy_engine/config/main.py

@@ -101,6 +101,14 @@ def get_model_path(key: str):
         return env_override
     cfg = get_model_config(key)
     path = os.path.join(MODELS_HOME,cfg.folder)
+    # A managed copy takes precedence.  The worker's external pointer is used
+    # only when its Hugpy cache does not hold the model.
+    external = (getattr(cfg, "extra", None) or {}).get("external_location")
+    if external and not model_looks_downloaded(path, cfg) and (
+            os.path.isdir(external) or
+            ((getattr(cfg, "extra", None) or {}).get("ollama_model") and
+             os.path.isfile(external))):
+        return external
     # Read-through (2026-07-12 hotfix): cfg.folder is CENTRAL's layout — after
     # the store flattening it names the FLAT dir, but a worker's files may
     # still sit under a legacy task path. Without the resolver here, every

{hugpy_engine-0.2.3 → hugpy_engine-0.2.4}/src/hugpy_engine/config/models/model_meta.py

@@ -142,12 +142,18 @@ def model_meta(cfg: Any, *, vram_bytes: Optional[int] = None,
     framework = d.get("framework") or ""
     model_dir = _model_dir(d)
     dir_bytes = dir_size_bytes(model_dir)          # whole dir (every file/variant)
+    # Host discovery may know the exact effective checkpoint size even though
+    # Central cannot read that worker's path (Ollama blobs and API-served
+    # vLLM checkpoints are common examples). Use that measured catalog value
+    # when no local directory is available; local GGUF resolution below still
+    # takes precedence when the weights are on Central.
+    discovered_size = d.get("effective_bytes") or d.get("size_bytes")
 
     # A GGUF repo often holds several quantizations but only ONE serves, so the
     # dir sum badly overstates "the model" — and it flowed straight into the VRAM
     # recommendation. Resolve the single effective quant (+ its mmproj) exactly as
     # the runner will, honoring the operator's gguf_file choice, and size by that.
-    size = dir_bytes
+    size = dir_bytes or discovered_size
     gguf = {}
     if str(framework).lower() in ("gguf", "llama_cpp") and model_dir:
         try:
@@ -157,6 +163,8 @@ def model_meta(cfg: Any, *, vram_bytes: Optional[int] = None,
             gguf = {}
         if gguf.get("effective_bytes"):
             size = gguf["effective_bytes"]
+        elif discovered_size:
+            size = discovered_size
 
     selected = selected_err = None
     gguf_sel = str(select_gguf or "").strip()
@@ -177,7 +185,7 @@ def model_meta(cfg: Any, *, vram_bytes: Optional[int] = None,
     out = {
         "model_key": d.get("model_key"),
         "size_bytes": size,                        # effective quant for GGUF
-        "dir_bytes": dir_bytes,                     # whole-dir footprint (all variants)
+        "dir_bytes": dir_bytes or (discovered_size if not model_dir else None),
         "quant": parse_quant(gguf.get("effective_gguf") or filename),
         "params_b": parse_params_b(name, hub_id, filename),
         "ctx_max": ctx_max,

{hugpy_engine-0.2.3 → hugpy_engine-0.2.4}/src/hugpy_engine/config/models/models_config.py

@@ -16,6 +16,8 @@ refresh_registry() explicitly — e.g. on hugpy module startup.
 
 import json
 import os
+import time
+import hashlib
 from dataclasses import MISSING, fields
 from typing import Dict
 from abstract_essentials import get_logFile, safe_dump_to_file, safe_load_from_json
@@ -773,6 +775,7 @@ def derive_model_config_row(name, row):
             or row.get("tokenizer_model_max_length")
             or row.get("max_position_embeddings") or DEFAULT_MAX_TOKENS_LOCAL,
         "filename": row.get("filename"), "include": row.get("include"),
+        **({"ollama_model": row["ollama_model"]} if row.get("ollama_model") else {}),
         "port": row.get("port"), "host": row.get("host"),
         # SERVEABLE = at least one advertised task has a runner (k61). It used to
         # mean "EVERY task has one", which made a partially-servable row read as
@@ -813,6 +816,10 @@ def _absorb_disk(staple, disc):
     for k in ("dir", "folder", "filename"):
         if disc.get(k):
             staple[k] = disc[k]
+    for k in ("model_max_length", "tokenizer_model_max_length",
+              "max_position_embeddings"):
+        if disc.get(k) is not None:
+            staple[k] = disc[k]
 
 def merge_discovery_into_models(discovery, base=None):
     base = base if base is not None else MODELS
@@ -1492,6 +1499,8 @@ def get_models_dict(models_dict_path=None, dict_return=False, return_dict=False,
     # discovery/path (a fresh walk) forces a rebuild. During the import-time
     # build the globals aren't bound yet -> globals().get() is None -> build.
     if discovery is None and models_dict_path is None:
+        if "_apply_worker_catalog" in globals():
+            _apply_worker_catalog()
         cached = globals().get("MODEL_REGISTRY_DICT" if dict_return else "MODEL_REGISTRY")
         if cached:
             return cached
@@ -1536,6 +1545,171 @@ def get_models_dict(models_dict_path=None, dict_return=False, return_dict=False,
 MODEL_REGISTRY: Dict[str, ModelConfig] = get_models_dict()
 MODEL_REGISTRY_DICT: Dict[str, dict] = get_models_dict(dict_return=True)
 
+# A worker owns the path to its external weights.  Central stores only the
+# catalog metadata and a per-worker path pointer; it must never resolve that
+# pointer as a path on Central or offer it as a central transfer source.
+_WORKER_CATALOG_PATH = os.path.join(os.path.dirname(MODELS_DISCOVERY_PATH),
+                                    "worker_model_catalog.json")
+_WORKER_CATALOG_SEEN = 0.0
+_WORKER_ONLY_KEYS: set[str] = set()
+_WORKER_TOUCHED_KEYS: set[str] = set()
+
+
+def _central_copy_present(key: str) -> bool:
+    """A registry row alone does not prove Central owns transferable bytes."""
+    try:
+        from hugpy_engine.config.main import get_model_path
+        from hugpy_storage.model_presence import model_looks_downloaded
+        cfg = MODEL_REGISTRY[key]
+        return model_looks_downloaded(get_model_path(key), cfg)
+    except Exception:  # noqa: BLE001 — uncertain means no destructive cold reset
+        return False
+
+
+def record_worker_models(worker_id: str, rows: dict) -> list[str]:
+    """Persist one host scan, shared by all Central web processes."""
+    import fcntl
+    path = _WORKER_CATALOG_PATH
+    os.makedirs(os.path.dirname(path), exist_ok=True)
+    with open(path + ".lock", "a+") as lock:
+        fcntl.flock(lock, fcntl.LOCK_EX)
+        try:
+            with open(path, encoding="utf-8") as fh:
+                data = json.load(fh)
+        except (OSError, ValueError):
+            data = {}
+        clean = {}
+        for key, row in (rows or {}).items():
+            if not isinstance(key, str) or not isinstance(row, dict):
+                continue
+            location = row.get("external_location")
+            api_url = row.get("api_url")
+            try:
+                from urllib.parse import urlsplit
+                parsed_api = urlsplit(api_url) if isinstance(api_url, str) else None
+                is_api = bool(parsed_api and parsed_api.scheme == "http"
+                              and parsed_api.hostname in ("127.0.0.1", "localhost", "::1")
+                              and parsed_api.port and not parsed_api.username
+                              and not parsed_api.password and parsed_api.path in ("", "/")
+                              and not parsed_api.query and not parsed_api.fragment)
+            except ValueError:
+                is_api = False
+            if not ((isinstance(location, str) and os.path.isabs(location)) or is_api):
+                continue
+            hub = str(row.get("hub_id") or "").strip("/").lower()
+            current = MODEL_REGISTRY.get(key)
+            if (not is_api and current is not None and
+                    str(current.hub_id or "").strip("/").lower() != hub):
+                owner = str(row.get("hub_id") or "local").split("/", 1)[0]
+                key = f"{owner}~{key}"
+            current = MODEL_REGISTRY.get(key)
+            if ((not is_api and current is not None and
+                 str(current.hub_id or "").strip("/").lower() != hub) or
+                    (key in clean and clean[key].get("worker_location") != location
+                     and clean[key].get("api_url") != api_url)):
+                key += "~" + hashlib.sha256(location.encode()).hexdigest()[:8]
+            clean[key] = {k: row.get(k) for k in (
+                "name", "hub_id", "framework", "tasks", "primary_task",
+                "filename", "model_max_length", "model_key", "size_bytes",
+                "effective_bytes", "ollama_model", "api_url", "served_model",
+                "service_kind") if row.get(k) is not None}
+            clean[key]["model_key"] = key
+            if isinstance(location, str) and os.path.isabs(location):
+                clean[key]["worker_location"] = location
+        old = (data.get(worker_id) or {}).get("models")
+        changed = old != clean
+        if changed:
+            data[worker_id] = {"at": time.time(), "models": clean}
+            tmp = path + f".{os.getpid()}.tmp"
+            with open(tmp, "w", encoding="utf-8") as fh:
+                json.dump(data, fh)
+            os.replace(tmp, path)
+        fcntl.flock(lock, fcntl.LOCK_UN)
+    _apply_worker_catalog(force=changed)
+    # The canonical keys may differ from worker-local scan keys when central
+    # already has a same-named model from another hub. Return those identities
+    # so heartbeat placement uses the same keys as the shared model catalog.
+    return sorted(clean)
+
+
+def _apply_worker_catalog(force=False) -> None:
+    """Overlay worker-only rows on the regular catalog, preserving local rows."""
+    global _WORKER_CATALOG_SEEN
+    registry = globals().get("MODEL_REGISTRY")
+    registry_dict = globals().get("MODEL_REGISTRY_DICT")
+    if registry is None or registry_dict is None:
+        return  # import-time base build
+    try:
+        stamp = os.stat(_WORKER_CATALOG_PATH).st_mtime_ns
+        if not force and stamp == _WORKER_CATALOG_SEEN:
+            return
+        with open(_WORKER_CATALOG_PATH, encoding="utf-8") as fh:
+            data = json.load(fh)
+    except (OSError, ValueError):
+        return
+    locations: dict[str, dict[str, str]] = {}
+    external_apis: dict[str, dict[str, dict]] = {}
+    candidates: dict[str, dict] = {}
+    for worker_id, entry in data.items():
+        for key, row in (entry.get("models") or {}).items():
+            if not isinstance(row, dict):
+                continue
+            if row.get("worker_location"):
+                locations.setdefault(key, {})[worker_id] = row["worker_location"]
+            if row.get("api_url"):
+                external_apis.setdefault(key, {})[worker_id] = {
+                    field: row[field] for field in ("api_url", "served_model", "service_kind")
+                    if row.get(field) is not None}
+            candidates.setdefault(key, row)
+
+    for key in list(_WORKER_ONLY_KEYS - candidates.keys()):
+        registry.pop(key, None)
+        registry_dict.pop(key, None)
+        _WORKER_ONLY_KEYS.discard(key)
+    for key in _WORKER_TOUCHED_KEYS - candidates.keys():
+        if key in registry_dict:
+            registry_dict[key].pop("worker_locations", None)
+            registry_dict[key].pop("worker_external_apis", None)
+            registry_dict[key].pop("worker_only", None)
+        if key in registry:
+            registry[key].extra.pop("worker_only", None)
+    for key, row in candidates.items():
+        if key not in registry:
+            clean = {k: v for k, v in row.items() if k != "worker_location"}
+            derived, _ = derive_model_config_row(key, clean)
+            if not derived:
+                continue
+            derived["worker_only"] = True
+            for size_key in ("size_bytes", "effective_bytes"):
+                if row.get(size_key) is not None:
+                    derived[size_key] = row[size_key]
+            cfg = get_assessed_model_config(derived)
+            if not cfg:
+                continue
+            registry[key] = cfg
+            registry_dict[key] = cfg.to_dict()
+            for size_key in ("size_bytes", "effective_bytes"):
+                if row.get(size_key) is not None:
+                    registry_dict[key][size_key] = row[size_key]
+            _WORKER_ONLY_KEYS.add(key)
+        worker_only = key in _WORKER_ONLY_KEYS or not _central_copy_present(key)
+        registry_dict[key]["worker_locations"] = locations.get(key, {})
+        if external_apis.get(key):
+            registry_dict[key]["worker_external_apis"] = external_apis[key]
+        else:
+            registry_dict[key].pop("worker_external_apis", None)
+        registry_dict[key]["worker_only"] = worker_only
+        if worker_only:
+            registry[key].extra["worker_only"] = True
+        else:
+            registry[key].extra.pop("worker_only", None)
+    _WORKER_TOUCHED_KEYS.clear()
+    _WORKER_TOUCHED_KEYS.update(candidates)
+    _WORKER_CATALOG_SEEN = stamp
+
+
+_apply_worker_catalog(force=True)
+
 
 def get_model_registry(dict_return=False, return_dict=False):
     dict_return = dict_return or return_dict
@@ -1569,6 +1743,8 @@ def refresh_registry(run_discovery=True):
     MODEL_REGISTRY_DICT.update(fresh_dict)
     for stale in [k for k in MODEL_REGISTRY_DICT if k not in fresh_dict]:
         MODEL_REGISTRY_DICT.pop(stale, None)
+    _WORKER_ONLY_KEYS.clear()  # fresh is the central base; recalculate ownership
+    _apply_worker_catalog(force=True)
     try:
         from hugpy_engine.config.models.models_default import refresh_task_registries
         refresh_task_registries()

{hugpy_engine-0.2.3 → hugpy_engine-0.2.4}/src/hugpy_engine/dispatch/activity.py

@@ -32,7 +32,10 @@ def format_prompt(messages=None, prompt=None) -> str:
     return json.dumps(messages, ensure_ascii=False, indent=2, default=str)
 
 # view state <- canonical status
-_VIEW_STATE = {"pending": "waiting", "processing": "waiting",
+# Keep queue presentation aligned with the canonical job lifecycle.  A request
+# assigned to a worker but still pre-filling/loading is processing, not waiting;
+# collapsing the two made a live worker request look orphaned in the console.
+_VIEW_STATE = {"pending": "waiting", "processing": "processing",
                "streaming": "active"}
 _QUEUE_KINDS_EXCLUDED = {"download"}
 
@@ -105,6 +108,8 @@ def counts() -> dict:
             if d["kind"] not in _QUEUE_KINDS_EXCLUDED]
     waiting = sum(1 for d in live
                   if _VIEW_STATE.get(d["status"]) == "waiting")
+    # Preserve the existing API shape (`active` is the non-waiting bucket),
+    # while snapshots distinguish `processing` from token-producing `active`.
     active = sum(1 for d in live
-                 if _VIEW_STATE.get(d["status"]) == "active")
+                 if _VIEW_STATE.get(d["status"]) in ("processing", "active"))
     return {"waiting": waiting, "active": active, "total": waiting + active}

{hugpy_engine-0.2.3 → hugpy_engine-0.2.4}/src/hugpy_engine/resolvers/__init__.py

@@ -14,6 +14,7 @@ from hugpy_engine.resolvers.remote import (
     set_no_worker_diagnostic,
     set_no_worker_skips,
     set_placement_provider,
+    set_serving_provider,
     set_worker_provider,
 )
 
@@ -21,5 +22,5 @@ __all__ = [
     "EXTERNAL_TASK_RUNNERS", "Peer", "ensure_staple_weights", "external_runner_for",
     "get_worker_provider", "peer_for", "resolve", "resolve_model_key",
     "set_no_worker_diagnostic", "set_no_worker_skips", "set_placement_provider",
-    "set_worker_provider", "validate_registry",
+    "set_serving_provider", "set_worker_provider", "validate_registry",
 ]

{hugpy_engine-0.2.3 → hugpy_engine-0.2.4}/src/hugpy_engine/resolvers/assure_model_key.py

@@ -320,6 +320,102 @@ def _quant_rank(key: str) -> int:
     return max((_QUANT_BITS[t] for t in toks if t in _QUANT_BITS), default=0)
 
 
+# Packaging / quant / framework markers — a name carrying any of these named a
+# representation, not merely a base-name family. Single source for both the
+# serving-override gate (_package_specific) and the logical-identity strip
+# (_logical_id) so the two never drift.
+_FORMAT_TOKENS = frozenset({
+    "gguf", "transformers", "transformer", "safetensors", "pytorch",
+    "awq", "gptq", "exl2", "exl3", "mlx", "bnb", "4bit", "8bit",
+    "fp8", "fp16", "bf16", "f16", "q2", "q3", "q4", "q5", "q6", "q8",
+})
+
+# The GGUF engine family (mirrors alloc_modes.GGUF_ENGINES; inlined to keep this
+# resolver import-cheap and cycle-free).
+_GGUF_ENGINES = frozenset({"gguf", "llama_cpp"})
+
+
+def _package_specific(model_key: str) -> bool:
+    """Whether the caller explicitly selected a model packaging/framework.
+
+    A bare family request (``Qwen3-Coder-Next``) must follow the live serving
+    representation, whether that is GGUF or Transformers.  ``GGUF`` and the
+    common Transformers/package markers are deliberate specificity and must
+    remain exact rather than being rewritten to whichever sibling is hot.
+    """
+    return bool(set(_tokens(model_key)) & _FORMAT_TOKENS)
+
+
+def _framework_of(key: str):
+    """The registry framework for ``key`` (scalar), or None when absent."""
+    cfg = MODEL_REGISTRY.get(key)
+    fw = getattr(cfg, "framework", None) if cfg is not None else None
+    if isinstance(fw, (list, tuple)):
+        fw = fw[0] if fw else None
+    return fw
+
+
+def _representation_of(key: str):
+    """The gguf-vs-transformers REPRESENTATION of a registry key, read from its
+    framework (never a name substring). GGUF family -> "gguf"; any other
+    concrete framework -> "transformers"; None when the key is not in the
+    registry."""
+    fw = _framework_of(key)
+    if fw is None:
+        return None
+    return "gguf" if str(fw).strip().lower() in _GGUF_ENGINES else "transformers"
+
+
+def _logical_id(key: str) -> str:
+    """Base-name identity of a key with packaging/quant tokens dropped, so the
+    GGUF and Transformers rows of one model share it (``…-Coder-Next-GGUF`` and
+    ``…-Coder-Next`` -> ``coder next``). Used ONLY to pair representation
+    siblings under an explicit model_format."""
+    return " ".join(t for t in _tokens(_bare_tail(key)) if t not in _FORMAT_TOKENS)
+
+
+def _owner_of(key: str) -> str:
+    """The publisher qualifier of ``key`` (``Owner~Repo`` / ``owner/repo``), or
+    its hub_id owner, or "" — the same owner rule _match_tier enforces, so a
+    representation redirect never crosses publishers."""
+    s = str(key)
+    if "~" in s:
+        return _slugify(s.split("~", 1)[0])
+    hub_id = getattr(MODEL_REGISTRY.get(key), "hub_id", None)
+    if hub_id and "/" in str(hub_id):
+        return _slugify(str(hub_id).split("/", 1)[0])
+    if "/" in s:
+        return _slugify(s.split("/", 1)[0])
+    return ""
+
+
+def _redirect_to_format(resolved: str, model_key: str, fmt: str, *, strict: bool):
+    """Return the key of the requested REPRESENTATION for the model ``resolved``
+    names. When ``resolved`` is already that representation it is returned
+    unchanged; otherwise the same-logical-identity, same-owner sibling of
+    representation ``fmt`` is chosen (deterministically). When the registry has
+    no such representation the resolved key is kept and a warning logged — a
+    resolver cannot invent a row that is not on record."""
+    if not resolved or _representation_of(resolved) == fmt:
+        return resolved
+    want_logical = _logical_id(resolved)
+    want_owner = _owner_of(resolved)
+    siblings = [
+        k for k in MODEL_REGISTRY
+        if _representation_of(k) == fmt
+        and _logical_id(k) == want_logical
+        and (not want_owner or _owner_of(k) == want_owner)
+    ]
+    if not siblings:
+        _log.warning("assure_model_key: model_format=%r requested for %r but no "
+                     "%s representation of %r is on record; kept %s",
+                     fmt, model_key, fmt, resolved, resolved)
+        return resolved
+    if len(siblings) == 1:
+        return siblings[0]
+    return _pick_by_total_order(siblings, strict=strict) or siblings[0]
+
+
 def _match_tier(key, values, slug, bare_slug, model_key) -> int:
     """The strongest identity tier at which ``key`` matches the request, or 0."""
     if _slugify(key) == slug:
@@ -330,7 +426,26 @@ def _match_tier(key, values, slug, bare_slug, model_key) -> int:
     folder = getattr(values, "folder", None)
     if folder and _path_suffix_matches(folder, model_key):
         return _TIER_FOLDER
+    # A qualified request names a publisher, not merely a base-name family.
+    # Never let the bare-tail tier silently turn an explicit
+    # ``unsloth~Qwen3-Coder-Next-GGUF`` request into the Qwen variant (or vice
+    # versa) when one qualified registry row is absent.  The qualified owner
+    # may be represented by the registry key or by the model's Hub ID while
+    # the registry key itself remains bare.
     if _slugify(_bare_tail(key)) == bare_slug:
+        requested_owner = ""
+        if "~" in str(model_key):
+            requested_owner = str(model_key).split("~", 1)[0].strip()
+        elif "/" in str(model_key):
+            requested_owner = str(model_key).split("/", 1)[0].strip()
+        if requested_owner:
+            candidate_owner = ""
+            if "~" in str(key):
+                candidate_owner = str(key).split("~", 1)[0].strip()
+            elif hub_id and "/" in str(hub_id):
+                candidate_owner = str(hub_id).split("/", 1)[0].strip()
+            if _slugify(candidate_owner) != _slugify(requested_owner):
+                return 0
         return _TIER_BARE
     return 0
 
@@ -351,7 +466,29 @@ def _pick_by_total_order(keys, *, strict):
     return ranked[0]
 
 
-def assure_model_key(model_key, *, strict: bool = False, _expand_aliases: bool = True):
+def assure_model_key(model_key, *, strict: bool = False, fmt: str = "auto",
+                     _expand_aliases: bool = True):
+    """Resolve a model reference to a canonical registry key.
+
+    ``fmt`` (model_format: "auto" | "gguf" | "transformers") is the EXPLICIT
+    representation override (operator 2026-09-29). "auto" (default) is
+    byte-identical to legacy resolution. "gguf"/"transformers" is authoritative:
+    the base resolution runs first, then :func:`_redirect_to_format` swaps in the
+    same-model, same-owner sibling of the requested representation (ignoring what
+    is currently serving and any contradicting name suffix). The GGUF-vs-
+    Transformers special-casing downstream keys off the RESOLVED key's framework,
+    so nothing beyond the returned key needs to know about ``fmt``.
+    """
+    resolved = _assure_model_key_base(model_key, strict=strict,
+                                      _expand_aliases=_expand_aliases)
+    if resolved and fmt and str(fmt).strip().lower() not in ("", "auto"):
+        return _redirect_to_format(resolved, model_key, str(fmt).strip().lower(),
+                                   strict=strict)
+    return resolved
+
+
+def _assure_model_key_base(model_key, *, strict: bool = False,
+                           _expand_aliases: bool = True):
     """
     Resolve a user-provided model key, repo id, manifest slug, folder name,
     or folder suffix into the canonical key from MODEL_REGISTRY.
@@ -387,7 +524,7 @@ def assure_model_key(model_key, *, strict: bool = False, _expand_aliases: bool =
     if _expand_aliases:
         target = _alias_target(model_key)
         if target and target != model_key:
-            resolved = assure_model_key(target, strict=strict, _expand_aliases=False)
+            resolved = _assure_model_key_base(target, strict=strict, _expand_aliases=False)
             if resolved is not None:
                 _log.debug("assure_model_key: alias %r -> %r -> %s",
                            model_key, target, resolved)
@@ -410,6 +547,15 @@ def assure_model_key(model_key, *, strict: bool = False, _expand_aliases: bool =
         top = [k for k, t in tiers.items() if t == top_tier]
         if len(top) == 1:
             return top[0]
+        # Same-family variants (notably GGUF vs Transformers) are not a real
+        # ambiguity when the caller did not name a packaging.  Let the normal
+        # serving-aware pipeline choose the live representation first.  An
+        # explicitly qualified request still takes the deterministic exact
+        # path below and cannot be redirected across frameworks.
+        if not _package_specific(model_key):
+            chosen = _pipeline_pick(model_key, top)
+            if chosen is not None:
+                return chosen
         winner = _pick_by_total_order(top, strict=strict)
         if winner is not None:
             _log.debug("assure_model_key: broke tier-%d tie for %r -> %s (of %s)",

{hugpy_engine-0.2.3 → hugpy_engine-0.2.4}/src/hugpy_engine/resolvers/categories/builders.py

@@ -79,9 +79,13 @@ def _build_chat_request(kwargs: Dict[str, Any], model_key: str) -> ChatRequest:
     # the keys above; without forwarding it here the /v1 route's derived client
     # identity never reaches ChatRequest.caller, so every call records as "api".
     # It is central-only (dropped from model_dump before the worker wire).
+    # model_format: central-only representation pin (operator 2026-09-29) — rides
+    # ChatRequest so the serving fast-route matches by representation; dropped
+    # from the worker wire by ChatRequest's serializer, same as ``caller``.
     for k in ("max_new_tokens", "temperature", "top_p", "do_sample", "request_id",
               "unbounded", "max_chunks", "pool", "images", "alloc",
-              "chat_template_kwargs", "logit_bias", "no_makeroom", "caller"):
+              "chat_template_kwargs", "logit_bias", "no_makeroom", "caller",
+              "model_format"):
         if k in kwargs:
             out[k] = kwargs[k]
     out.setdefault("request_id", make_request_id())

{hugpy_engine-0.2.3 → hugpy_engine-0.2.4}/src/hugpy_engine/resolvers/model_resolver.py

@@ -180,12 +180,16 @@ def _adopt_vl_tasks_from_disk(model_key, cfg, task):
     return None
 
 
+_MODEL_FORMATS = ("auto", "gguf", "transformers")
+
+
 def resolve_model_key(
     *,
     model_key: Optional[str] = None,
     file: Optional[str] = None,
     media_type: Optional[str] = None,
     task: Optional[str] = None,
+    model_format: Optional[str] = None,
 ) -> str:
     """Pick a model_key via explicit resolution chain.
 
@@ -194,15 +198,25 @@ def resolve_model_key(
 
     `task`, when given alongside `model_key`, is validated against
     cfg.tasks. When given alone, it picks TASK_DEFAULTS[task].
+
+    `model_format` ("auto" | "gguf" | "transformers", default auto) is the
+    explicit representation override — authoritative when choosing between the
+    GGUF and Transformers rows of the same model (operator 2026-09-29).
     """
     if task is not None and task not in KNOWN_TASKS_REGISTRY:
         raise KeyError(
             f"Unknown task={task!r}; known: {sorted(KNOWN_TASKS_REGISTRY)}"
         )
-    
+    fmt = (model_format or "auto").strip().lower() if model_format else "auto"
+    if fmt not in _MODEL_FORMATS:
+        raise ValueError(
+            f"Unknown model_format={model_format!r}; expected one of "
+            f"{list(_MODEL_FORMATS)}"
+        )
+
     if model_key is not None:
         requested = model_key
-        model_key = assure_model_key(model_key)
+        model_key = assure_model_key(model_key, fmt=fmt)
         if not model_key:
             # Fail with NEAR MATCHES, not the whole registry. Two cases produce
             # a None here: nothing matched, or a fuzzy tie the pipeline could
@@ -349,6 +363,7 @@ def resolve(prompt_kwargs: Dict[str, Any]) -> Resolution:
         file=prompt_kwargs.get("file"),
         media_type=prompt_kwargs.get("media_type"),
         task=requested_task,
+        model_format=prompt_kwargs.get("model_format"),
     )
 
     cfg = MODEL_REGISTRY[model_key]