hugpy-engine 0.3.6__tar.gz → 0.3.7__tar.gz

hugpy_engine-0.3.7/PKG-INFO

@@ -0,0 +1,204 @@
+Metadata-Version: 2.4
+Name: hugpy-engine
+Version: 0.3.7
+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
+
+Inference resolution for the Hugpy arms. It turns "a prompt and maybe a file"
+into a model and a task, and hands the call to central's `/v1` relay. Central
+picks the worker, and that worker's wrapper does evict-to-fit, load, serving
+and the call log. The engine itself does not load models in fleet mode.
+
+Distribution `hugpy-engine`, import `hugpy_engine`. Dependencies:
+`hugpy-platform`, `abstract-essentials`, `pydantic>=2`.
+
+**Status: LIVE.** It is a library only: no service, no console script.
+
+- Installed in `/opt/hugpy-media/venv` (0.3.7) and `/opt/hugpy-video/venv`
+  (0.3.8).
+- Imported by `hugpy_media`, `hugpy_video` and `hugpy_oracle`.
+- Core's live basic mode does not use it. Only core's legacy
+  `config/prompt.py` does, and that code is not live.
+
+On 2026-10-15 the engine's last ties to `hugpy-storage` and `hugpy-control`
+are being removed, targeting 0.3.9 and later:
+
+- `vl_gguf_tasks` is ported in from `hugpy_storage.hugpy_marker`.
+- The `hugpy_storage.model_paths.route_destination` call is dropped; it was
+  dead in fleet mode.
+- `hugpy_storage.console.downloader.model_status` is replaced by registry
+  availability from `/v1/models`.
+- The guarded imports of the retired `hugpy_control.settings.settings_store`
+  are deleted.
+
+Check `pyproject.toml` for the current version. See
+[docs/packages.md](../../docs/packages.md#versions-in-flight).
+
+## Public API
+
+```python
+from hugpy_engine import (
+    execute_prompt, execute_prompt_stream, execute_chat_stream,
+    resolve, resolve_model_key,
+    MODEL_REGISTRY, get_model_registry, refresh_registry,
+    normalize_prompt_kwargs, infer_arg_name, runner_for,
+)
+```
+
+Positional arguments to `execute_prompt` are inferred by type:
+
+| type | meaning |
+|---|---|
+| `str` | a model id or a prompt |
+| `int` | `max_new_tokens` |
+| `float` | `temperature`, then `top_p` |
+| `bool` | `do_sample` |
+| `list` | `messages` |
+
+`execute_prompt_stream` is a single resolve, build and runner pass yielded as
+events (`TokenEvent`, `DoneEvent`, `ErrorEvent`). It accepts `cancel_event`.
+`execute_chat_stream` adds chat continuation on top of it.
+
+Chat and vision run today. A task whose runner has no front-door endpoint yet
+resolves to a clean, named error (fail-as-data).
+
+## execute_prompt: infer, rank, assure
+
+Full reference: [docs/execute_prompt.md](../../docs/execute_prompt.md).
+
+`execute_prompt` is not plain task routing. Its defining contract
+(operator): it "would infer programmatically what the user was looking to
+prompt, via file inspection, prompt type, and anything that necessarily
+indicated a model type — most assuredly to receive a response than most any
+other query method." Task bindings are only ONE input. The mechanic has three
+stages, all in the stdlib-only module `hugpy_engine.resolvers.task_resolution`,
+so that central can later serve the same resolution.
+
+1. **INFER.** `task_resolution.infer(args, kwargs)` works out WHAT to prompt
+   from several signals:
+   - positional args: a bare prompt, a messages list, an existing file, a
+     model-ish string, a `data:` URL or an http(s) URL
+   - file type: the extension maps to image, audio, video, document, code or
+     text
+   - message parts: `image_url`, `input_image`, audio, `data:` URLs
+   - explicit cues: `task=`, `model_format=`
+
+   It derives the task only when the caller gave no explicit `task` and no
+   explicit `model_key`:
+
+   | input | task |
+   |---|---|
+   | image | image-text-to-text |
+   | audio or video | asr |
+   | pdf or doc | extract + text |
+   | text | text-generation |
+
+   One-call use works: `execute_prompt("describe this", "/path/img.png")`
+   needs no task or model. Inference only ever *adds* a task. It never
+   overrides an explicit one, and a failure inside it never blocks the call.
+
+2. **RANK.** `task_resolution.resolve(...)` returns an ORDERED candidate
+   list, strongest first, by source precedence:
+
+       explicit model_key → binding → configured default → capability match
+
+   Capability matches are ranked **resident > available on a healthy worker
+   > other**. A row whose `primary_task` matches the task is preferred, then
+   order is deterministic by id. "No model in the fleet lists task X" appears
+   ONLY when no registry model can serve X. It is never a dead-end "bind one
+   in Settings".
+
+3. **ASSURE.** `execute_prompt` tries the candidates in order.
+   - On a MODEL-SIDE failure (worker down, load refusal, timeout, 5xx, empty
+     reply), it moves to the next candidate.
+   - A CALLER error (4xx validation, bad args) is surfaced immediately. The
+     same bad request would fail on every model, so it is never cascaded.
+   - The first real answer wins and carries `resolution` metadata:
+     `{task, source, model_key, attempts:[...]}`.
+   - When every candidate fails, it returns a fail-as-data result (`ok=False`)
+     with the full attempt list, never a bare exception that hides what was
+     tried.
+
+### Registry and bindings source
+
+**The registry** is built from basic core's `GET /v1/models` rows: `id`,
+`hugpy_json.tasks`, `task_override`, `engine`, `resident`, `available`,
+`workers` and `resident_on`. `derive_model_config_row` maps each row onto
+`ModelConfig`. If that fails, it falls back to the legacy `GET /models`, and
+then to a local `hugpy.json` disk scan of `HUGPY_MODELS_HOME` /
+`LLAMA_CPP_MODEL_DIR`. The scan is fail-soft and fails fast on an EIO models
+disk.
+
+**Bindings** are read from `GET /v1/task-bindings` (`{"defaults": {...}}`),
+then the legacy `GET /prompt/tasks`. A 404 means "no bindings". Live basic
+core (0.4.40) serves neither route, so the binding stage is empty today and
+resolution relies on explicit keys, configured defaults and capability
+matches.
+
+Both reads are TTL-cached and never raise on the resolve path.
+
+### Configuration
+
+`hugpy_engine.imports.constants` names every environment variable, timeout and
+TTL the chain reads:
+
+| variable | default | meaning |
+|---|---|---|
+| `HUGPY_CORE_URL` (legacy alias `HUGPY_FITEVICT_FRONT_DOOR`) | `http://127.0.0.1:7020` | central's base URL |
+| `HUGPY_REGISTRY_TTL_S` | 30 | registry and bindings cache lifetime |
+| `HUGPY_REGISTRY_TIMEOUT_S` | 10 | registry fetch timeout |
+| `HUGPY_TASK_ENDPOINT_TIMEOUT_S` | 900 | task endpoint call timeout |
+| `HUGPY_FITEVICT_TIMEOUT_S` | 900 | `/v1` call timeout |
+| `HUGPY_MODELS_HOME`, `LLAMA_CPP_MODEL_DIR` | unset | roots for the local disk-scan fallback |
+
+The same module holds the `TASK_DEFAULTS`, `MEDIA_DEFAULTS` and
+`MEDIA_TYPE_TO_TASK` tables.
+
+## The task plugin seam
+
+`hugpy_engine.tasks` holds the task registry. Packages add tasks through the
+`hugpy_engine.tasks` entry-point group (a zero-argument callable), which
+`tasks.load_entry_points()` imports. Two packages register today:
+
+- `hugpy-media`: `media = "hugpy_media.plugin:register"`
+- `hugpy-video`: `video = "hugpy_video.plugin:register"`
+
+`task_endpoints.TASK_ROUTES` maps tasks to the front-door endpoints.
+
+## Layout
+
+```
+hugpy_engine/
+  dispatch/       execute_prompt / execute_prompt_stream / execute_chat_stream; per-(model, task) runner cache
+  resolvers/      task_resolution (infer / rank, stdlib only), model_resolver (resolve), assure_model_key,
+                  categories/ (task + framework registries)
+  config/         models/ (MODEL_REGISTRY, models_config, defaults), main
+  llama/runners/  fitevict_runner: the runner that sends a call to central's /v1
+  schemas/        chat, event, metadata, model, runner, task schemas (pydantic)
+  fit/, placement.py   placement types and null single-box defaults
+  tasks.py, task_endpoints.py, task_deps.py, categories.py, name_match.py
+  utils/          json_scavenge, no_think
+  imports/        constants (every env name), functions, classes, init_imports
+                  (docs/packages.md#the-imports-layout-convention)
+```
+
+See also:
+
+- [docs/execute_prompt.md](../../docs/execute_prompt.md)
+- [docs/arms.md](../../docs/arms.md)
+- [docs/packages.md](../../docs/packages.md)

hugpy_engine-0.3.7/README.md

@@ -0,0 +1,185 @@
+# hugpy-engine
+
+Inference resolution for the Hugpy arms. It turns "a prompt and maybe a file"
+into a model and a task, and hands the call to central's `/v1` relay. Central
+picks the worker, and that worker's wrapper does evict-to-fit, load, serving
+and the call log. The engine itself does not load models in fleet mode.
+
+Distribution `hugpy-engine`, import `hugpy_engine`. Dependencies:
+`hugpy-platform`, `abstract-essentials`, `pydantic>=2`.
+
+**Status: LIVE.** It is a library only: no service, no console script.
+
+- Installed in `/opt/hugpy-media/venv` (0.3.7) and `/opt/hugpy-video/venv`
+  (0.3.8).
+- Imported by `hugpy_media`, `hugpy_video` and `hugpy_oracle`.
+- Core's live basic mode does not use it. Only core's legacy
+  `config/prompt.py` does, and that code is not live.
+
+On 2026-10-15 the engine's last ties to `hugpy-storage` and `hugpy-control`
+are being removed, targeting 0.3.9 and later:
+
+- `vl_gguf_tasks` is ported in from `hugpy_storage.hugpy_marker`.
+- The `hugpy_storage.model_paths.route_destination` call is dropped; it was
+  dead in fleet mode.
+- `hugpy_storage.console.downloader.model_status` is replaced by registry
+  availability from `/v1/models`.
+- The guarded imports of the retired `hugpy_control.settings.settings_store`
+  are deleted.
+
+Check `pyproject.toml` for the current version. See
+[docs/packages.md](../../docs/packages.md#versions-in-flight).
+
+## Public API
+
+```python
+from hugpy_engine import (
+    execute_prompt, execute_prompt_stream, execute_chat_stream,
+    resolve, resolve_model_key,
+    MODEL_REGISTRY, get_model_registry, refresh_registry,
+    normalize_prompt_kwargs, infer_arg_name, runner_for,
+)
+```
+
+Positional arguments to `execute_prompt` are inferred by type:
+
+| type | meaning |
+|---|---|
+| `str` | a model id or a prompt |
+| `int` | `max_new_tokens` |
+| `float` | `temperature`, then `top_p` |
+| `bool` | `do_sample` |
+| `list` | `messages` |
+
+`execute_prompt_stream` is a single resolve, build and runner pass yielded as
+events (`TokenEvent`, `DoneEvent`, `ErrorEvent`). It accepts `cancel_event`.
+`execute_chat_stream` adds chat continuation on top of it.
+
+Chat and vision run today. A task whose runner has no front-door endpoint yet
+resolves to a clean, named error (fail-as-data).
+
+## execute_prompt: infer, rank, assure
+
+Full reference: [docs/execute_prompt.md](../../docs/execute_prompt.md).
+
+`execute_prompt` is not plain task routing. Its defining contract
+(operator): it "would infer programmatically what the user was looking to
+prompt, via file inspection, prompt type, and anything that necessarily
+indicated a model type — most assuredly to receive a response than most any
+other query method." Task bindings are only ONE input. The mechanic has three
+stages, all in the stdlib-only module `hugpy_engine.resolvers.task_resolution`,
+so that central can later serve the same resolution.
+
+1. **INFER.** `task_resolution.infer(args, kwargs)` works out WHAT to prompt
+   from several signals:
+   - positional args: a bare prompt, a messages list, an existing file, a
+     model-ish string, a `data:` URL or an http(s) URL
+   - file type: the extension maps to image, audio, video, document, code or
+     text
+   - message parts: `image_url`, `input_image`, audio, `data:` URLs
+   - explicit cues: `task=`, `model_format=`
+
+   It derives the task only when the caller gave no explicit `task` and no
+   explicit `model_key`:
+
+   | input | task |
+   |---|---|
+   | image | image-text-to-text |
+   | audio or video | asr |
+   | pdf or doc | extract + text |
+   | text | text-generation |
+
+   One-call use works: `execute_prompt("describe this", "/path/img.png")`
+   needs no task or model. Inference only ever *adds* a task. It never
+   overrides an explicit one, and a failure inside it never blocks the call.
+
+2. **RANK.** `task_resolution.resolve(...)` returns an ORDERED candidate
+   list, strongest first, by source precedence:
+
+       explicit model_key → binding → configured default → capability match
+
+   Capability matches are ranked **resident > available on a healthy worker
+   > other**. A row whose `primary_task` matches the task is preferred, then
+   order is deterministic by id. "No model in the fleet lists task X" appears
+   ONLY when no registry model can serve X. It is never a dead-end "bind one
+   in Settings".
+
+3. **ASSURE.** `execute_prompt` tries the candidates in order.
+   - On a MODEL-SIDE failure (worker down, load refusal, timeout, 5xx, empty
+     reply), it moves to the next candidate.
+   - A CALLER error (4xx validation, bad args) is surfaced immediately. The
+     same bad request would fail on every model, so it is never cascaded.
+   - The first real answer wins and carries `resolution` metadata:
+     `{task, source, model_key, attempts:[...]}`.
+   - When every candidate fails, it returns a fail-as-data result (`ok=False`)
+     with the full attempt list, never a bare exception that hides what was
+     tried.
+
+### Registry and bindings source
+
+**The registry** is built from basic core's `GET /v1/models` rows: `id`,
+`hugpy_json.tasks`, `task_override`, `engine`, `resident`, `available`,
+`workers` and `resident_on`. `derive_model_config_row` maps each row onto
+`ModelConfig`. If that fails, it falls back to the legacy `GET /models`, and
+then to a local `hugpy.json` disk scan of `HUGPY_MODELS_HOME` /
+`LLAMA_CPP_MODEL_DIR`. The scan is fail-soft and fails fast on an EIO models
+disk.
+
+**Bindings** are read from `GET /v1/task-bindings` (`{"defaults": {...}}`),
+then the legacy `GET /prompt/tasks`. A 404 means "no bindings". Live basic
+core (0.4.40) serves neither route, so the binding stage is empty today and
+resolution relies on explicit keys, configured defaults and capability
+matches.
+
+Both reads are TTL-cached and never raise on the resolve path.
+
+### Configuration
+
+`hugpy_engine.imports.constants` names every environment variable, timeout and
+TTL the chain reads:
+
+| variable | default | meaning |
+|---|---|---|
+| `HUGPY_CORE_URL` (legacy alias `HUGPY_FITEVICT_FRONT_DOOR`) | `http://127.0.0.1:7020` | central's base URL |
+| `HUGPY_REGISTRY_TTL_S` | 30 | registry and bindings cache lifetime |
+| `HUGPY_REGISTRY_TIMEOUT_S` | 10 | registry fetch timeout |
+| `HUGPY_TASK_ENDPOINT_TIMEOUT_S` | 900 | task endpoint call timeout |
+| `HUGPY_FITEVICT_TIMEOUT_S` | 900 | `/v1` call timeout |
+| `HUGPY_MODELS_HOME`, `LLAMA_CPP_MODEL_DIR` | unset | roots for the local disk-scan fallback |
+
+The same module holds the `TASK_DEFAULTS`, `MEDIA_DEFAULTS` and
+`MEDIA_TYPE_TO_TASK` tables.
+
+## The task plugin seam
+
+`hugpy_engine.tasks` holds the task registry. Packages add tasks through the
+`hugpy_engine.tasks` entry-point group (a zero-argument callable), which
+`tasks.load_entry_points()` imports. Two packages register today:
+
+- `hugpy-media`: `media = "hugpy_media.plugin:register"`
+- `hugpy-video`: `video = "hugpy_video.plugin:register"`
+
+`task_endpoints.TASK_ROUTES` maps tasks to the front-door endpoints.
+
+## Layout
+
+```
+hugpy_engine/
+  dispatch/       execute_prompt / execute_prompt_stream / execute_chat_stream; per-(model, task) runner cache
+  resolvers/      task_resolution (infer / rank, stdlib only), model_resolver (resolve), assure_model_key,
+                  categories/ (task + framework registries)
+  config/         models/ (MODEL_REGISTRY, models_config, defaults), main
+  llama/runners/  fitevict_runner: the runner that sends a call to central's /v1
+  schemas/        chat, event, metadata, model, runner, task schemas (pydantic)
+  fit/, placement.py   placement types and null single-box defaults
+  tasks.py, task_endpoints.py, task_deps.py, categories.py, name_match.py
+  utils/          json_scavenge, no_think
+  imports/        constants (every env name), functions, classes, init_imports
+                  (docs/packages.md#the-imports-layout-convention)
+```
+
+See also:
+
+- [docs/execute_prompt.md](../../docs/execute_prompt.md)
+- [docs/arms.md](../../docs/arms.md)
+- [docs/packages.md](../../docs/packages.md)

{hugpy_engine-0.3.6 → hugpy_engine-0.3.7}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "hugpy-engine"
-version = "0.3.6"
+version = "0.3.7"
 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.6 → hugpy_engine-0.3.7}/src/hugpy_engine/categories.py

@@ -114,10 +114,29 @@ MEDIA_DEFAULTS: Dict[str, str] = {
     "video":    DEFAULT_WHISPER_MODEL,
 }
 
-# TASK DEFAULTS ARE NOT CONSTANTS ANY MORE (operator ruling 2026-10-04: "each
-# task is BOUND to a designated model in the DB. No guessing, no constants").
-# The task -> model_key map now lives in the DB (settings_policies
-# "task_bindings") and is read live from hugpy_core's GET /prompt/tasks
-# ``defaults`` via config.models.models_config.task_bindings(). This name is
-# kept EMPTY only so a mid-rollout importer does not break; nothing populates it.
-TASK_DEFAULTS: Dict[str, str] = {}
+# TASK_DEFAULTS — the configured task -> model_key seeds (ported back from the
+# monolith, abstract_hugpy_dev .../imports/src/constants/categories.py:83). These
+# are NO LONGER the sole authority (operator ruling 2026-10-04 made DB
+# task_bindings the designated choice); they are ONE RANKED INPUT to
+# resolvers.task_resolution.resolve(): a task resolves through
+#   explicit model_key -> DB binding -> THIS default -> capability match
+# so a fresh box with no bindings still resolves every task to a real model
+# instead of the dead-end "no model bound to task X". ``reconcile_defaults()``
+# heals these seeds against the live registry in place; a seed the fleet does not
+# serve is simply skipped (the default link falls through to capability match).
+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.6 → hugpy_engine-0.3.7}/src/hugpy_engine/config/models/models_config.py

@@ -44,6 +44,12 @@ MODELS: Dict[str, dict] = {}
 MODEL_REGISTRY: Dict[str, ModelConfig] = {}
 MODEL_REGISTRY_DICT: Dict[str, dict] = {}
 
+# The RAW catalog rows from the last successful fetch (the /v1/models shape).
+# Kept alongside the ModelConfig registry because the ranked resolver
+# (resolvers.task_resolution.resolve) ranks on the raw placement facts
+# (resident/available/workers/task_override) — one fetch, two consumers.
+_LAST_CATALOG: list = []
+
 _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"))
@@ -75,7 +81,10 @@ def derive_model_config_row(name, row) -> "Tuple[Optional[dict], Optional[str]]"
     """
     hj = row.get("hugpy_json") if isinstance(row.get("hugpy_json"), dict) else {}
 
-    framework = hj.get("framework") or row.get("framework")
+    # framework == the wrapper's engine. The basic core's /v1/models carries it
+    # as the top-level ``engine`` (hugpy_json.framework is authoritative when both
+    # are present); the legacy /models row used ``framework``. Read all three.
+    framework = hj.get("framework") or row.get("framework") or row.get("engine")
     if isinstance(framework, (list, tuple)):
         framework = framework[0] if framework else None
     framework = str(framework or "").strip().lower() or None
@@ -85,6 +94,16 @@ def derive_model_config_row(name, row) -> "Tuple[Optional[dict], Optional[str]]"
     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
+    # task_override (operator override on the catalog row) is additive capability:
+    # a row that lists it CAN serve it. Fold it into the model's tasks so capability
+    # matching in resolvers.task_resolution sees it.
+    override = row.get("task_override")
+    if override is None:
+        override = hj.get("task_override")
+    if isinstance(override, (list, tuple)):
+        tasks = list(tasks or []) + [o for o in override if o]
+    elif isinstance(override, str) and override:
+        tasks = list(tasks or []) + [override]
     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:
@@ -114,23 +133,54 @@ def derive_model_config_row(name, row) -> "Tuple[Optional[dict], Optional[str]]"
         "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"),
+        # PLACEMENT FACTS from the catalog row, carried verbatim into ModelConfig
+        # .extra (frozen, additive) so capability ranking in
+        # resolvers.task_resolution can prefer resident > available-on-a-healthy-
+        # worker > other without re-reading core. Never load-bearing for routing.
+        "resident": bool(row.get("resident")),
+        "available": bool(row.get("available")),
+        "workers": list(row.get("workers") or []),
+        "resident_on": list(row.get("resident_on") or []),
+        "dir": row.get("dir") or row.get("path"),
     }, 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))
+    """The live catalog as raw rows. None on total failure (fail-open).
+
+    Source order (resolvers.task_resolution.load_catalog, the dependency-light
+    fetcher hugpy_core will share): ``GET {core}/v1/models`` (the basic core's
+    real endpoint) -> legacy ``GET {core}/models`` -> a local hugpy.json disk
+    scan (HUGPY_MODELS_HOME / LLAMA_CPP_MODEL_DIR, fail-soft and fail-fast on the
+    EIO models disk). Stores the rows in ``_LAST_CATALOG`` so the ranked resolver
+    reads the same fetch."""
+    global _LAST_CATALOG
+    from hugpy_engine.resolvers import task_resolution as _tr
+
+    def _log(msg):
+        logger.warning("registry: %s; keeping the last known model set (%d models)",
+                       msg, len(MODEL_REGISTRY))
+
+    rows = _tr.load_catalog(_CORE_URL, timeout=_TIMEOUT_S, on_log=_log)
+    if not rows:
+        # core gave us nothing usable — try the local disk marker scan before
+        # giving up (fail-open). The scan abandons an EIO root fast.
+        local = _tr.load_local_scan(on_log=lambda m: logger.warning("registry: %s", m))
+        if local:
+            logger.info("registry: core catalog empty/unreachable; local hugpy.json "
+                        "scan found %d model(s)", len(local))
+            _LAST_CATALOG = local
+            return local
         return None
-    if isinstance(data, dict):
-        data = data.get("data") or data.get("models") or []
-    return data if isinstance(data, list) else []
+    _LAST_CATALOG = rows
+    return rows
+
+
+def catalog_rows() -> list:
+    """The raw catalog rows from the last successful fetch (the /v1/models shape).
+    Read by the ranked resolver so it can prefer resident/available models. A copy,
+    so a caller can filter it without disturbing the cache."""
+    return list(_LAST_CATALOG)
 
 
 def refresh_registry(force: bool = False) -> None:
@@ -205,25 +255,31 @@ _bindings_at = 0.0
 
 
 def task_bindings(force: bool = False) -> dict:
-    """The live {task: model_key} bindings from hugpy_core's /prompt/tasks
-    ``defaults``. TTL-cached; a failed/empty read keeps the last-known map."""
+    """The live {task: model_key} bindings.
+
+    Source order (resolvers.task_resolution.load_bindings): ``GET
+    {core}/v1/task-bindings`` -> ``{"defaults": {...}}`` (the endpoint the core
+    owner is adding) -> legacy ``GET {core}/prompt/tasks`` -> {}. A 404 on both
+    means "no bindings" (returned as {}, the honest empty map that lets the
+    default/capability links of the chain pick instead). TTL-cached; a transient
+    unreachable read keeps the last-known map. Bindings are now ONE input to the
+    ranked resolver, not the sole authority."""
     global _bindings, _bindings_at
     now = time.time()
     if not force and _bindings and (now - _bindings_at) < _TTL_S:
         return dict(_bindings)
-    url = _CORE_URL + "/prompt/tasks"
-    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 — never raise on the resolve path
-        logger.warning("registry: could not read task bindings from %s (%s); "
-                       "keeping the last-known map (%d)", url, exc, len(_bindings))
-        _bindings_at = now
-        return dict(_bindings)
-    defaults = (data or {}).get("defaults") if isinstance(data, dict) else None
-    if isinstance(defaults, dict):
-        _bindings = {str(k): str(v) for k, v in defaults.items() if v}
+    from hugpy_engine.resolvers import task_resolution as _tr
+    _unreachable = []
+    fresh = _tr.load_bindings(_CORE_URL, timeout=_TIMEOUT_S,
+                              on_log=lambda m: _unreachable.append(m))
+    if fresh:
+        _bindings = fresh
+    elif _unreachable and _bindings:
+        # a transient error (not a clean 404) — keep the last-known map.
+        logger.warning("registry: task bindings unreachable (%s); keeping the "
+                       "last-known map (%d)", "; ".join(_unreachable), len(_bindings))
+    else:
+        _bindings = {}      # clean "no bindings" answer
     _bindings_at = now
     return dict(_bindings)