hugpy-engine 0.2.6__tar.gz → 0.3.1__tar.gz

hugpy_engine-0.3.1/PKG-INFO

@@ -0,0 +1,22 @@
+Metadata-Version: 2.4
+Name: hugpy-engine
+Version: 0.3.1
+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
+Keywords: hugpy,llm,self-hosted,inference,llama.cpp,gguf,transformers,model-serving
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: hugpy-platform
+Requires-Dist: abstract-essentials
+Requires-Dist: pydantic>=2
+
+# hugpy-engine
+
+lean 0.3.0 — shared helpers for hugpy arms; everything else retired.

hugpy_engine-0.3.1/README.md

@@ -0,0 +1,3 @@
+# hugpy-engine
+
+lean 0.3.0 — shared helpers for hugpy arms; everything else retired.

hugpy_engine-0.3.1/pyproject.toml

@@ -0,0 +1,41 @@
+[build-system]
+requires = ["setuptools>=77"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "hugpy-engine"
+version = "0.3.1"
+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"
+license = "LicenseRef-Proprietary"
+authors = [{ name = "putkoff", email = "support@hugpy.ai" }]
+keywords = [
+    "hugpy",
+    "llm",
+    "self-hosted",
+    "inference",
+    "llama.cpp",
+    "gguf",
+    "transformers",
+    "model-serving",
+]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+]
+dependencies = [
+    "hugpy-platform",
+    "abstract-essentials",
+    "pydantic>=2",
+]
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+hugpy_engine = ["py.typed"]

hugpy_engine-0.3.1/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.1/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.1/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.1/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.2.6 → hugpy_engine-0.3.1}/src/hugpy_engine/dispatch/__init__.py

@@ -1,5 +1,4 @@
 """Request dispatch: runner cache, execution, streaming, eviction."""
-from hugpy_engine.dispatch.acquire import acquire
 from hugpy_engine.dispatch.dispatch import (
     LoadRefusal,
     clear,
@@ -27,7 +26,7 @@ from hugpy_engine.dispatch.dispatch import (
 )
 
 __all__ = [
-    "LoadRefusal", "acquire", "clear", "ensure_headroom_for_load", "evict",
+    "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",

{hugpy_engine-0.2.6 → hugpy_engine-0.3.1}/src/hugpy_engine/dispatch/dispatch.py

@@ -562,11 +562,31 @@ def infer_arg_name(arg: Any) -> Optional[str]:
             "/" in arg
             or "_gguf" in lowered
             or any(tag in lowered for tag in ("qwen", "llama", "mistral", "gpt"))
+            # Any live registry key is a model_key — core ids like
+            # ``AtomicChat~Qwen3.8-27B-GGUF`` / ``Echo-Mini`` carry none of the
+            # name tags above, so the positional model id must be recognised by
+            # membership (the one allowed addition, operator 2026-10-04). Guarded
+            # + fail-open: an unreachable/empty registry just leaves it "messages".
+            or _is_registry_key(arg)
         )
         return "model_key" if looks_like_model else "messages"
     return None
 
 
+def _is_registry_key(arg: str) -> bool:
+    """True when ``arg`` names a model the registry holds (exact or resolvable).
+    Fail-open to False so a registry/import hiccup never misclassifies a prompt."""
+    try:
+        from hugpy_engine.config.models.models_config import MODEL_REGISTRY, refresh_registry
+        refresh_registry()
+        if arg in MODEL_REGISTRY:
+            return True
+        from hugpy_engine.resolvers.assure_model_key import assure_model_key
+        return assure_model_key(arg, fuzzy=False) is not None
+    except Exception:  # noqa: BLE001
+        return False
+
+
 def normalize_prompt_kwargs(*args: Any, **kwargs: Any) -> Dict[str, Any]:
     """Convert flexible input into builder-compatible kwargs.
 
@@ -612,6 +632,20 @@ def runner_for(
     return _get_or_build_runner(res)
 
 
+def _run_coro_sync(coro):
+    """Drive an awaitable to its result from a SYNC caller. Uses asyncio.run when
+    no loop is running; if one is (rare for this entrypoint), runs it on a short
+    worker thread so execute_prompt still returns a concrete result rather than a
+    coroutine the sync caller would drop on the floor."""
+    try:
+        asyncio.get_running_loop()
+    except RuntimeError:
+        return asyncio.run(coro)
+    import concurrent.futures
+    with concurrent.futures.ThreadPoolExecutor(max_workers=1) as ex:
+        return ex.submit(lambda: asyncio.run(coro)).result()
+
+
 def execute_prompt(*args: Any, **kwargs: Any):
     """One-shot request -> result. Sync entrypoint; awaits inside if needed.
 
@@ -625,7 +659,15 @@ def execute_prompt(*args: Any, **kwargs: Any):
         req = res.builder(prompt_kwargs, res.model_key)
         runner = _get_or_build_runner(res)
         touch_model(res.model_key)   # residency idle clock
-        return runner.run(req=req)
+        out = runner.run(req=req)
+        # Sync one-call contract (the shape the operator loves): a sync caller
+        # gets the RESULT, not a coroutine. Runners are async now (the fitevict
+        # front door), so await-to-completion here when the caller isn't already
+        # in an event loop; under a running loop, hand back the awaitable so the
+        # async caller (the HTTP route via await_sync) drives it.
+        if inspect.isawaitable(out):
+            return _run_coro_sync(out)
+        return out
     finally:
         # The try body can resume in a DIFFERENT Context (async/greenlet hop),
         # where reset(token) raises "created in a different Context" and 500s