hugpy-engine 0.3.0__tar.gz → 0.3.2__tar.gz

{hugpy_engine-0.3.0 → hugpy_engine-0.3.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: hugpy-engine
-Version: 0.3.0
+Version: 0.3.2
 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.3.0 → hugpy_engine-0.3.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "hugpy-engine"
-version = "0.3.0"
+version = "0.3.2"
 description = "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"
 readme = "README.md"
 requires-python = ">=3.10"

hugpy_engine-0.3.2/src/hugpy_engine/__init__.py

@@ -0,0 +1,49 @@
+"""Hugpy inference engine — the one-call prompt API, revived.
+
+``execute_prompt(*args, **kwargs)`` returns the output you expected for a task:
+positional args are inferred by type (str -> a model id or a prompt, int ->
+max_new_tokens, float -> temperature then top_p, bool -> do_sample, list ->
+messages), the request is resolved to a model + task, and the call is handed to
+the box's fitevict front door through hugpy_core's relay (which picks the
+worker and owns evict-to-fit, load, serving and the call log).
+
+Chat/vision run today; a task whose runner has no front-door endpoint yet
+resolves to a clean, named error (fail-as-data).
+"""
+from __future__ import annotations
+
+try:
+    from importlib.metadata import version as _package_version
+
+    __version__ = _package_version("hugpy-engine")
+except Exception:  # pragma: no cover - source tree without metadata
+    __version__ = "0.0.0+unknown"
+
+from hugpy_engine.dispatch.dispatch import (
+    execute_chat_stream,
+    execute_prompt,
+    execute_prompt_stream,
+    infer_arg_name,
+    normalize_prompt_kwargs,
+    runner_for,
+)
+from hugpy_engine.resolvers import resolve, resolve_model_key
+from hugpy_engine.config.models.models_config import (
+    MODEL_REGISTRY,
+    get_model_registry,
+    refresh_registry,
+)
+
+__all__ = [
+    "MODEL_REGISTRY",
+    "execute_chat_stream",
+    "execute_prompt",
+    "execute_prompt_stream",
+    "get_model_registry",
+    "infer_arg_name",
+    "normalize_prompt_kwargs",
+    "refresh_registry",
+    "resolve",
+    "resolve_model_key",
+    "runner_for",
+]

hugpy_engine-0.3.2/src/hugpy_engine/categories.py

@@ -0,0 +1,132 @@
+"""Model-catalog domain constants: task vocabulary, servable pairs, defaults.
+
+The ``DEFAULT_*_MODEL`` values here are the env-configured defaults from
+``hugpy_platform.constants``; ``config.models.models_default`` reconciles them
+against the live registry after discovery and patches ``TASK_DEFAULTS`` /
+``MEDIA_DEFAULTS`` in place.
+"""
+from typing import Dict
+from hugpy_platform.constants import (
+    DEFAULT_CHAT_MODEL,
+    DEFAULT_DEPTH_MODEL,
+    DEFAULT_EMBED_MODEL,
+    DEFAULT_VISION_MODEL,
+    DEFAULT_WHISPER_MODEL,
+    DEFAULT_DETECT_MODEL,
+    DEFAULT_IMAGEGEN_MODEL,
+    DEFAULT_IMG_CLASSIFY_MODEL,
+    DEFAULT_KEYWORDS_MODEL,
+    DEFAULT_SEGMENT_MODEL,
+    DEFAULT_SUMMARIZE_MODEL,
+)
+# pipeline_tag -> task vocabulary. Every value is HF-derivable.
+HF_TASK_TO_TASKS = {
+    "text-generation": ["text-generation"],
+    "image-text-to-text": ["image-text-to-text", "text-generation"],
+    "automatic-speech-recognition": ["automatic-speech-recognition"],
+    # SPEECH OUT (chatterbox seat). Its absence here is why a row whose card
+    # says ``pipeline_tag: text-to-speech`` fell through to _base_tasks'
+    # conservative floor and advertised ["text-generation"] — a voice-cloning
+    # model offering itself as a chat model. The pair
+    # ("transformers","text-to-speech") is in RUNNER_PAIRS below, so the task is
+    # servable, not merely visible.
+    "text-to-speech": ["text-to-speech"],
+    "text-summarization": ["text-summarization"],
+    "text2text-generation": ["text-summarization", "text2text-generation"],
+    # KeyBERT rides any sentence-transformers model, so embedding models
+    # also serve keyword-extraction.
+    "feature-extraction": ["feature-extraction", "sentence-similarity", "keyword-extraction"],
+    "sentence-similarity": ["feature-extraction", "sentence-similarity", "keyword-extraction"],
+    "text-to-image": ["text-to-image"],
+    # VIDEO. A full video pipeline (Wan/LTX/Cog/Hunyuan/Mochi/…) is SERVEABLE:
+    # the runners live in hugpy_video's studio registry, and the
+    # ("transformers","text-to-video")/("transformers","image-to-video")
+    # RUNNER_PAIRS below make derive_model_config_row flag it serveable so it is
+    # graded like any other model (no-grader until a video suite exists) instead
+    # of the blanket "unservable/pipeline component" it read as before
+    # (2026-09-24). Before 2026-07-27 a Wan T2V model fell through _base_tasks'
+    # "conservative floor" and advertised ["text-generation"]: a video diffusion
+    # model offering itself as a chat model. A single-file GGUF video transformer
+    # is NOT a full pipeline — it stays a pipeline-component
+    # (models_config._correct_pipeline_component).
+    "text-to-video": ["text-to-video"],
+    "image-to-video": ["image-to-video"],
+    # NOTE: "image-to-image" is intentionally NOT a DISCOVERY pipeline_tag key.
+    # A raw HF pipeline_tag=image-to-image (native EDIT models like
+    # Qwen-Image-Edit) is still not auto-advertised from that tag alone. Instead,
+    # img2img capability is DERIVED at the config layer
+    # (models_config._derive_tasks): any image-GENERATION checkpoint — an
+    # SD/SDXL/flux-class diffusers model or a comfy SD-lineage checkpoint — serves
+    # image-to-image from the SAME weights it serves text-to-image with
+    # (AutoPipelineForImage2Image / the comfy image-conditioned graph), so it
+    # gains "image-to-image" whenever it advertises "text-to-image". (Operator
+    # ruling 2026-07-05: primary_task / pipeline_tag is NOT a definitive capability
+    # marker — plenty of models do img2img without saying so.) The
+    # ("transformers","image-to-image") / ("comfy","image-to-image") RUNNER_PAIRS
+    # entries below back that derivation.
+    # Vision-analysis family — HF pipeline tags map 1:1.
+    "depth-estimation": ["depth-estimation"],
+    "object-detection": ["object-detection"],
+    "image-classification": ["image-classification"],
+    "image-segmentation": ["image-segmentation"],
+}
+RUNNER_PAIRS = {
+    ("transformers", "text-generation"), ("gguf", "text-generation"),
+    ("transformers", "image-text-to-text"), ("gguf", "image-text-to-text"),
+    ("transformers", "automatic-speech-recognition"),
+    ("transformers", "text-to-speech"),
+    ("transformers", "text-summarization"), ("transformers", "text2text-generation"),
+    ("transformers", "feature-extraction"), ("transformers", "sentence-similarity"),
+    ("transformers", "text-to-image"), ("transformers", "image-to-image"),
+    # VIDEO (2026-09-24). Full diffusers video pipelines served by hugpy_video's
+    # studio runner registry (RunnerSpec for WAN/LTX/Hunyuan/Cog/Mochi/OpenSora/
+    # SkyReels, T2V + I2V + VACE). Declaring the pairs here is what flips a full
+    # video pipeline from serveable=False ("adapter / pipeline component") to a
+    # normal graded row. Where hugpy-video is not wired on a box,
+    # model_resolver._plugin_missing reports it as an uninstalled runner plugin
+    # and resolve() refuses at the point of use — it never fails import, and
+    # neither task is in TASK_DEFAULTS so no chat/media route can pick a video
+    # model.
+    ("transformers", "text-to-video"), ("transformers", "image-to-video"),
+    # ComfyUI engine rows (slice B) — the checkpoint lives in the WORKER's own
+    # ComfyUI install; hugpy holds no files for these.
+    ("comfy", "text-to-image"), ("comfy", "image-to-image"),
+    ("transformers", "keyword-extraction"),
+    ("transformers", "depth-estimation"), ("transformers", "object-detection"),
+    ("transformers", "image-classification"), ("transformers", "image-segmentation"),
+}
+
+# Frameworks whose ("<framework>","image-to-image") runner+builder pair is wired
+# above. DERIVED from RUNNER_PAIRS so it can't drift (same discipline as
+# frameworks.KNOWN_TASKS_REGISTRY). A generative-image checkpoint on one of these
+# frameworks serves img2img from the SAME weights it serves text-to-image with,
+# so models_config._derive_tasks advertises "image-to-image" for it whenever it
+# advertises "text-to-image". Today this is {"transformers", "comfy"}.
+IMG2IMG_CAPABLE_FRAMEWORKS: frozenset = frozenset(
+    framework for (framework, task) in RUNNER_PAIRS if task == "image-to-image"
+)
+MEDIA_DEFAULTS: Dict[str, str] = {
+    "document": DEFAULT_CHAT_MODEL,
+    "code":     DEFAULT_CHAT_MODEL,
+    "text":     DEFAULT_CHAT_MODEL,
+    "image":    DEFAULT_VISION_MODEL,
+    "audio":    DEFAULT_WHISPER_MODEL,
+    "video":    DEFAULT_WHISPER_MODEL,
+}
+
+TASK_DEFAULTS: Dict[str, str] = {
+    "text-generation":              DEFAULT_CHAT_MODEL,
+    "image-text-to-text":           DEFAULT_VISION_MODEL,
+    "automatic-speech-recognition": DEFAULT_WHISPER_MODEL,
+    "text-summarization":           DEFAULT_SUMMARIZE_MODEL,
+    "text2text-generation":         DEFAULT_SUMMARIZE_MODEL,
+    "feature-extraction":           DEFAULT_EMBED_MODEL,
+    "sentence-similarity":          DEFAULT_EMBED_MODEL,
+    "text-to-image":                DEFAULT_IMAGEGEN_MODEL,
+    "image-to-image":               DEFAULT_IMAGEGEN_MODEL,
+    "keyword-extraction":           DEFAULT_KEYWORDS_MODEL,
+    "depth-estimation":             DEFAULT_DEPTH_MODEL,
+    "object-detection":             DEFAULT_DETECT_MODEL,
+    "image-classification":         DEFAULT_IMG_CLASSIFY_MODEL,
+    "image-segmentation":           DEFAULT_SEGMENT_MODEL,
+}

hugpy_engine-0.3.2/src/hugpy_engine/config/main.py

@@ -0,0 +1,84 @@
+"""Registry lookups over the live MODEL_REGISTRY (hugpy_next cut 2, lean).
+
+The heavy disk/path resolution of the legacy config.main is DROPPED — hugpy
+hosts all weights and the box's fitevict front door owns every load, so the
+engine never resolves a model directory. These helpers answer "what are the
+facts of model X" from the registry (sourced from hugpy_core's catalog).
+"""
+from __future__ import annotations
+
+from typing import Optional
+
+from hugpy_engine.config.models.models_config import (
+    MODEL_REGISTRY,
+    get_model_registry,
+    refresh_registry,
+)
+
+
+def list_models():
+    refresh_registry()
+    return list(MODEL_REGISTRY.keys())
+
+
+def _resolve_model_key(model_key, registry, prefer=None):
+    """Map a possibly-bare model_key to a concrete registry key (exact, then a
+    unique ``owner~name`` tail, then the ``-GGUF`` format equivalent)."""
+    if model_key in registry:
+        return model_key
+
+    def _bare(k):
+        return k.split("~", 1)[1] if "~" in k else k
+
+    candidates = sorted(k for k in registry if _bare(k) == model_key)
+    if not candidates:
+        try:
+            from hugpy_engine.fit.types import key_equivalent
+            candidates = sorted(k for k in registry if key_equivalent(_bare(k), model_key))
+        except Exception:  # noqa: BLE001
+            candidates = []
+    if not candidates:
+        return None
+    if len(candidates) == 1:
+        return candidates[0]
+    for p in (prefer or []):
+        if p in candidates:
+            return p
+        for c in candidates:
+            if _bare(c) == _bare(p):
+                return c
+    return candidates[0]
+
+
+def get_model_config(model_key: str = None, dict_return=False, return_dict=False,
+                     key: str = None, prefer=None):
+    model_key = model_key or key
+    refresh_registry()
+    registry = get_model_registry(dict_return=dict_return, return_dict=return_dict)
+    resolved = _resolve_model_key(model_key, MODEL_REGISTRY, prefer=prefer)
+    if resolved is None:
+        raise KeyError(f"Unknown model: {model_key}")
+    return registry[resolved]
+
+
+def get_model_path(key: str) -> Optional[str]:
+    """The model's folder as recorded on its registry row. Not load-bearing (the
+    front door routes by model_key); best-effort for callers that still ask."""
+    cfg = get_model_config(key)
+    return getattr(cfg, "folder", None)
+
+
+def list_model_options():
+    refresh_registry()
+    return {
+        key: {
+            "name": cfg.name,
+            "hub_id": cfg.hub_id,
+            "folder": cfg.folder,
+            "tasks": cfg.tasks,
+            "framework": cfg.framework,
+            "filename": cfg.filename,
+            "port": cfg.port,
+        }
+        for key, cfg in MODEL_REGISTRY.items()
+    }

hugpy_engine-0.3.2/src/hugpy_engine/config/models/models_config.py

@@ -0,0 +1,190 @@
+"""models_config.py — the registry SOURCE (hugpy_next cut 2 seam).
+
+Operator ruling "hugpy.json is the model init": per-model facts (framework,
+tasks, primary_task, hub_id, name) are stamped in each model's hugpy.json. The
+worker stamps them, derives the model KEY per box (``owner~repo`` on an owner
+collision, else bare ``repo`` — fitevict/adapters/llama_cpp.discover_models),
+and relays both the key and the parsed hugpy.json to hugpy_core, which exposes
+them at ``GET {core}/models`` (catalog_rows). That endpoint is the ONE place
+that carries BOTH the core id (the id ``/v1/models`` serves and ``pick()``
+routes on) AND each model's hugpy.json facts — the core id is not derivable from
+a single hugpy.json on disk (the collision qualifier is per-box state), so the
+registry is keyed from core, never re-derived from disk.
+
+So: MODEL_REGISTRY is built by reading hugpy_core's catalog, keyed by the core
+id, mapping each row's hugpy.json facts through ``derive_model_config_row`` into
+``ModelConfig``. Read lazily, TTL-cached, fail-open: core unreachable / no
+workers online -> the registry keeps whatever it last had (empty at worst), and
+resolution then refuses cleanly ("no online worker has it" / "no chat default").
+
+There is NO curated ``MODELS`` fleet and NO disk discovery/classification here
+(operator: no hardcoded model names; every model already carries its task).
+"""
+from __future__ import annotations
+
+import json
+import logging
+import os
+import threading
+import time
+import urllib.request
+from typing import Dict, Optional, Tuple
+
+from hugpy_engine.schemas.model_schemas import ModelConfig
+
+logger = logging.getLogger(__name__)
+
+# No curated staples (operator: no hardcoded model names as defaults). Kept as an
+# empty dict because a few lifted call sites still read ``MODELS`` (e.g.
+# validate_registry's "is this a code-declared staple" check, media defaults).
+MODELS: Dict[str, dict] = {}
+
+# The live registry, keyed by the core id. Updated IN PLACE by refresh_registry
+# so modules that imported these names by reference always see the current set.
+MODEL_REGISTRY: Dict[str, ModelConfig] = {}
+MODEL_REGISTRY_DICT: Dict[str, dict] = {}
+
+_CORE_URL = (os.environ.get("HUGPY_CORE_URL") or "http://127.0.0.1:7020").rstrip("/")
+_TTL_S = float(os.environ.get("HUGPY_REGISTRY_TTL_S", "30"))
+_TIMEOUT_S = float(os.environ.get("HUGPY_REGISTRY_TIMEOUT_S", "10"))
+_lock = threading.RLock()
+_last_fetch = 0.0
+
+
+def _dedup(seq) -> list:
+    """Order-preserving de-dup, dropping falsy entries."""
+    out: list = []
+    for x in seq or []:
+        if x and x not in out:
+            out.append(x)
+    return out
+
+
+def derive_model_config_row(name, row) -> "Tuple[Optional[dict], Optional[str]]":
+    """One hugpy_core catalog row -> a ModelConfig-ready dict, or (None, reason).
+
+    ``name`` is the core id (the registry key). ``row`` is a catalog_rows entry;
+    its ``hugpy_json`` sub-dict is authoritative for framework/tasks/
+    primary_task/hub_id/name (operator: hugpy.json is the model init), with the
+    row's own top-level fields as the fallback the catalog already flattened.
+
+    framework == the wrapper's engine (gguf, transformers, comfy, ...): one
+    concept, kept verbatim. tasks are the plain HF pipeline-tag strings straight
+    from hugpy.json, no renaming. A null ``tasks`` (seen on some GGUF markers)
+    falls back to ``[primary_task]`` so every model has at least its own task.
+    """
+    hj = row.get("hugpy_json") if isinstance(row.get("hugpy_json"), dict) else {}
+
+    framework = hj.get("framework") or row.get("framework")
+    if isinstance(framework, (list, tuple)):
+        framework = framework[0] if framework else None
+    framework = str(framework or "").strip().lower() or None
+    if not framework:
+        return None, f"{name}: no framework/engine recorded"
+
+    tasks = hj.get("tasks") if isinstance(hj.get("tasks"), list) else None
+    if not tasks:
+        tasks = row.get("tasks") if isinstance(row.get("tasks"), list) else None
+    primary = hj.get("primary_task") or row.get("primary_task") or row.get("task")
+    tasks = _dedup(tasks or ([primary] if primary else []))
+    if not tasks:
+        return None, f"{name}: no tasks and no primary_task recorded"
+    if not primary or primary not in tasks:
+        primary = tasks[0]
+    else:
+        # primary must be present; already is. Keep order with primary first is
+        # not required (ModelConfig only checks membership).
+        pass
+
+    hub_id = hj.get("hub_id") or row.get("hub_id") or name
+    disp_name = hj.get("name") or row.get("name") or name
+    # folder is a required ModelConfig field; it is not load-bearing here (the
+    # fitevict front door routes by model_key, not folder), so the hub_id is a
+    # fine stable value.
+    folder = str(hub_id or name)
+
+    return {
+        "name": disp_name,
+        "model_key": name,
+        "hub_id": str(hub_id),
+        "folder": folder,
+        "framework": framework,
+        "tasks": tasks,
+        "primary_task": primary,
+        "filename": hj.get("filename") or row.get("file"),
+        "include": hj.get("include"),
+        "model_max_length": hj.get("model_max_length") or row.get("model_max_length"),
+    }, None
+
+
+def _fetch_catalog() -> "Optional[list]":
+    """GET {core}/models (catalog_rows). None on any failure (fail-open)."""
+    url = _CORE_URL + "/models"
+    try:
+        req = urllib.request.Request(url, headers={"Accept": "application/json"})
+        with urllib.request.urlopen(req, timeout=_TIMEOUT_S) as r:
+            data = json.loads(r.read().decode("utf-8") or "null")
+    except Exception as exc:  # noqa: BLE001 — the registry read never raises
+        logger.warning("registry: could not read %s (%s); keeping the last "
+                       "known model set (%d models)", url, exc, len(MODEL_REGISTRY))
+        return None
+    if isinstance(data, dict):
+        data = data.get("data") or data.get("models") or []
+    return data if isinstance(data, list) else []
+
+
+def refresh_registry(force: bool = False) -> None:
+    """Rebuild MODEL_REGISTRY / MODEL_REGISTRY_DICT from hugpy_core's catalog.
+
+    TTL-cached (HUGPY_REGISTRY_TTL_S) so a burst of calls hits core once. Updates
+    the dicts IN PLACE. Fail-open: a failed/empty fetch leaves the current set
+    untouched rather than emptying a working registry."""
+    global _last_fetch
+    now = time.time()
+    with _lock:
+        if not force and MODEL_REGISTRY and (now - _last_fetch) < _TTL_S:
+            return
+        rows = _fetch_catalog()
+        _last_fetch = now
+        if rows is None:
+            return  # keep the last known set
+        fresh: Dict[str, ModelConfig] = {}
+        fresh_dict: Dict[str, dict] = {}
+        dropped = []
+        for row in rows:
+            if not isinstance(row, dict):
+                continue
+            key = row.get("model_key") or row.get("id") or row.get("name")
+            if not key:
+                continue
+            values, why = derive_model_config_row(key, row)
+            if values is None:
+                dropped.append((key, why))
+                continue
+            try:
+                cfg = ModelConfig(**values)
+            except Exception as exc:  # noqa: BLE001 — a bad row never breaks the set
+                dropped.append((key, f"ModelConfig rejected: {exc}"))
+                continue
+            fresh[key] = cfg
+            fresh_dict[key] = cfg.to_dict()
+        if not fresh and MODEL_REGISTRY:
+            # Core answered but yielded nothing usable (all workers offline mid
+            # refresh): keep the last good set rather than blanking resolution.
+            logger.info("registry: catalog refresh yielded 0 usable rows; "
+                        "keeping %d previous models", len(MODEL_REGISTRY))
+            return
+        MODEL_REGISTRY.clear(); MODEL_REGISTRY.update(fresh)
+        MODEL_REGISTRY_DICT.clear(); MODEL_REGISTRY_DICT.update(fresh_dict)
+        if dropped:
+            logger.info("registry: %d/%d catalog rows not servable here: %s",
+                        len(dropped), len(rows),
+                        ", ".join(f"{k} ({w})" for k, w in dropped[:6]))
+        logger.info("registry: refreshed from %s — %d models",
+                    _CORE_URL, len(MODEL_REGISTRY))
+
+
+def get_model_registry(dict_return: bool = False, return_dict: bool = False):
+    if dict_return or return_dict:
+        return MODEL_REGISTRY_DICT
+    return MODEL_REGISTRY

hugpy_engine-0.3.2/src/hugpy_engine/config/models/models_default.py

@@ -0,0 +1,150 @@
+"""Default-model reconciliation (hugpy_next cut 2, lean).
+
+TASK_DEFAULTS / MEDIA_DEFAULTS are seeded in categories.py from the configured
+``DEFAULT_*`` constants. Those seeds are names a fresh box may not actually
+serve, so they are RECONCILED against the live registry (sourced from
+hugpy_core's catalog, keyed by core id): keep the configured default when the
+registry holds it, else stand in a registry model that serves the task group.
+
+Every registry row here is a model a worker is serving RIGHT NOW (it came from
+the live catalog), so "installed" is implicit — there is no disk check and no
+``route_destination`` import. ``reconcile_defaults()`` and
+``refresh_task_registries()`` are re-callable so resolve() heals the dicts from
+the current model set on every request.
+"""
+from typing import Dict
+
+from abstract_essentials import make_list
+from hugpy_engine.categories import MEDIA_DEFAULTS, TASK_DEFAULTS
+from hugpy_engine.config.models.models_config import MODEL_REGISTRY
+from hugpy_engine.schemas.model_schemas import ModelConfig
+from hugpy_platform.constants import (
+    DEFAULT_AGENT_BRAIN,
+    DEFAULT_CHAT_MODEL,
+    DEFAULT_EMBED_MODEL,
+    DEFAULT_VISION_MODEL,
+    DEFAULT_WHISPER_MODEL,
+)
+
+
+def get_context_tokens():
+    return {k: v.model_max_length for k, v in MODEL_REGISTRY.items()}
+
+
+def default_context_tokens_for_model(model_key: str) -> int:
+    return get_context_tokens().get(model_key, 8192)
+
+
+def get_models_dict_by_tasks(tasks=None):
+    tasks = make_list(tasks or [])
+    return {k: v for k, v in MODEL_REGISTRY.items()
+            if any(t in tasks for t in v.tasks)}
+
+
+def get_models_dict_by_names(names=None):
+    names = make_list(names or [])
+    out = {}
+    for k, v in MODEL_REGISTRY.items():
+        for name in names:
+            if name in v.name:
+                out[k] = v
+                break
+    return out
+
+
+def _reconcile_default(configured: str, registry: Dict[str, ModelConfig],
+                       prefer_task: str | None = None) -> str:
+    """Keep ``configured`` when the registry holds it; otherwise stand in a
+    registry model that serves ``prefer_task`` (then key order for determinism).
+    Returns ``configured`` unchanged when the registry is empty, so the honest
+    "not in MODEL_REGISTRY" refusal downstream stays accurate."""
+    if not registry:
+        return configured
+    if configured in registry:
+        return configured
+    pool = registry
+    if prefer_task:
+        preferred = {k: v for k, v in registry.items() if prefer_task in v.tasks}
+        pool = preferred or registry
+    if not pool:
+        return configured
+    return min(pool)
+
+
+# Seeds from constants.py; healed by reconcile_defaults() against the live set.
+_SEED = {
+    "chat": DEFAULT_CHAT_MODEL,
+    "vision": DEFAULT_VISION_MODEL,
+    "whisper": DEFAULT_WHISPER_MODEL,
+    "embed": DEFAULT_EMBED_MODEL,
+    "brain": DEFAULT_AGENT_BRAIN,
+}
+
+# Task-filtered views (updated IN PLACE — other modules hold them by reference).
+CHAT_MODELS_REGISTRY: Dict[str, ModelConfig] = {}
+VISION_MODELS_REGISTRY: Dict[str, ModelConfig] = {}
+WHISPER_MODELS_REGISTRY: Dict[str, ModelConfig] = {}
+EMBED_MODELS_REGISTRY: Dict[str, ModelConfig] = {}
+
+_TASK_REGISTRY_GROUPS = (
+    (CHAT_MODELS_REGISTRY,    ["text-generation", "text-generation-inference", "text2text-generation"]),
+    (VISION_MODELS_REGISTRY,  ["image-text-to-text", "text-to-image"]),
+    (WHISPER_MODELS_REGISTRY, ["automatic-speech-recognition", "speech-recognition"]),
+    (EMBED_MODELS_REGISTRY,   ["feature-extraction", "sentence-similarity", "sentence-transformers"]),
+)
+
+
+def refresh_task_registries() -> None:
+    """Rebuild the task-filtered registries in place from the live MODEL_REGISTRY
+    (update-then-prune so a concurrent reader never sees an empty dict)."""
+    for registry, tasks in _TASK_REGISTRY_GROUPS:
+        fresh = get_models_dict_by_tasks(tasks=tasks)
+        registry.update(fresh)
+        for stale in [k for k in registry if k not in fresh]:
+            registry.pop(stale, None)
+
+
+# The reconciled defaults (module globals, rebound by reconcile_defaults()).
+DEFAULT_CHAT_MODEL = _SEED["chat"]
+DEFAULT_VISION_MODEL = _SEED["vision"]
+DEFAULT_WHISPER_MODEL = _SEED["whisper"]
+DEFAULT_EMBED_MODEL = _SEED["embed"]
+DEFAULT_AGENT_BRAIN = _SEED["brain"]
+
+
+def reconcile_defaults() -> None:
+    """Recompute the DEFAULT_* model keys from the live registry and HEAL
+    TASK_DEFAULTS / MEDIA_DEFAULTS in place so a task-only / media-only / bare
+    request resolves to a real core id instead of a dangling configured name."""
+    global DEFAULT_CHAT_MODEL, DEFAULT_VISION_MODEL, DEFAULT_WHISPER_MODEL
+    global DEFAULT_EMBED_MODEL, DEFAULT_AGENT_BRAIN
+    refresh_task_registries()
+    DEFAULT_CHAT_MODEL = _reconcile_default(_SEED["chat"], CHAT_MODELS_REGISTRY,
+                                            prefer_task="text-generation")
+    DEFAULT_AGENT_BRAIN = _reconcile_default(_SEED["brain"], CHAT_MODELS_REGISTRY,
+                                             prefer_task="text-generation")
+    DEFAULT_VISION_MODEL = _reconcile_default(_SEED["vision"], VISION_MODELS_REGISTRY,
+                                              prefer_task="image-text-to-text")
+    DEFAULT_WHISPER_MODEL = _reconcile_default(_SEED["whisper"], WHISPER_MODELS_REGISTRY,
+                                               prefer_task="automatic-speech-recognition")
+    DEFAULT_EMBED_MODEL = _reconcile_default(_SEED["embed"], EMBED_MODELS_REGISTRY,
+                                             prefer_task="feature-extraction")
+    reconciled = {
+        _SEED["chat"]: DEFAULT_CHAT_MODEL,
+        _SEED["vision"]: DEFAULT_VISION_MODEL,
+        _SEED["whisper"]: DEFAULT_WHISPER_MODEL,
+        _SEED["embed"]: DEFAULT_EMBED_MODEL,
+    }
+    for defaults, keys_are_tasks in ((TASK_DEFAULTS, True), (MEDIA_DEFAULTS, False)):
+        for key, model in list(defaults.items()):
+            replacement = reconciled.get(model)
+            if not replacement or replacement == model:
+                continue
+            if keys_are_tasks and replacement in MODEL_REGISTRY \
+                    and key not in MODEL_REGISTRY[replacement].tasks:
+                continue  # the stand-in serves the group but not this exact task
+            defaults[key] = replacement
+
+
+# Heal once at import (registry may be empty here -> seeds, re-healed per request).
+reconcile_defaults()

hugpy_engine-0.3.2/src/hugpy_engine/dispatch/__init__.py

@@ -0,0 +1,36 @@
+"""Request dispatch: runner cache, execution, streaming, eviction."""
+from hugpy_engine.dispatch.dispatch import (
+    LoadRefusal,
+    clear,
+    ensure_headroom_for_load,
+    evict,
+    execute_chat_stream,
+    execute_prompt,
+    execute_prompt_stream,
+    infer_arg_name,
+    last_used_snapshot,
+    loaded_disk_detail,
+    loaded_model_keys,
+    loading_model_keys,
+    no_makeroom_active,
+    normalize_prompt_kwargs,
+    runner_for,
+    set_evict_reason,
+    set_evictable,
+    set_fit_check,
+    set_make_room,
+    set_post_evict_hook,
+    stream_runner,
+    supported_task_keys,
+    touch_model,
+)
+
+__all__ = [
+    "LoadRefusal", "clear", "ensure_headroom_for_load", "evict",
+    "execute_chat_stream", "execute_prompt", "execute_prompt_stream",
+    "infer_arg_name", "last_used_snapshot", "loaded_disk_detail",
+    "loaded_model_keys", "loading_model_keys", "no_makeroom_active",
+    "normalize_prompt_kwargs", "runner_for", "set_evict_reason", "set_evictable",
+    "set_fit_check", "set_make_room", "set_post_evict_hook", "stream_runner",
+    "supported_task_keys", "touch_model",
+]