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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: hugpy-engine
-Version: 0.2.3
+Version: 0.2.5
 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.5}/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.5}/src/hugpy_engine/catalog_bridge.py

@@ -52,7 +52,14 @@ class EngineCatalogSource:
     def canonical_key(self, model_key: str) -> Optional[str]:
         from hugpy_engine.resolvers.assure_model_key import assure_model_key
 
-        return assure_model_key(model_key)
+        # IDENTITY resolution only (operator rule 2026-09-29): this is the
+        # storage/provision seam a WORKER uses to re-resolve a key central
+        # already resolved (ensure_model_registered -> _assure_local_key). The
+        # shorthand fuzzy tier must never answer here — on ae it turned
+        # ``Qwen3.8-9B-GGUF`` into the resident ``Qwen3.8-9B-Distill-GGUF``
+        # (same file, different model) and served it (S3/F7). None means
+        # "learn the row from central", never "use the nearest sibling".
+        return assure_model_key(model_key, fuzzy=False)
 
     def resolve_dir(self, model_key: str) -> Optional[str]:
         from hugpy_engine.config.main import get_model_path

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

@@ -50,6 +50,14 @@ def _resolve_model_key(model_key, registry, prefer=None):
     def _bare(k):  # name without the "owner~" qualifier
         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:
+        # FORMAT EQUIVALENCE (operator rule 2026-09-29): ``X`` and ``X-GGUF``
+        # are one key, so either spelling resolves to the row on record under
+        # the other. Nothing else is folded — ``X-Distill-GGUF`` is a different
+        # model and never answers for ``X-GGUF`` (S3/F7). Lazy import keeps the
+        # config module's import graph unchanged.
+        from hugpy_engine.fit.types import key_equivalent
+        candidates = sorted(k for k in registry if key_equivalent(_bare(k), model_key))
     if not candidates:
         return None
     if len(candidates) == 1:
@@ -101,6 +109,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.5}/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.5}/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.5}/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"}
 
@@ -92,6 +95,13 @@ def snapshot() -> list:
             "kind": d["kind"],
             "prompt": d.get("prompt") or "",
             "state": state,
+            # WHERE a processing call is (2026-09-29): "prefill" while the
+            # engine is still reading the prompt (n_past/n_prompt ride on
+            # progress/input_tokens), "" once tokens flow. Without this the
+            # queue read "answering, 0 tokens" for a 105 s legitimate prefill.
+            "stage": d.get("stage") or "",
+            "progress": d.get("progress"),
+            "input_tokens": d.get("input_tokens"),
             "elapsed": d["elapsed"],
             "wait": d["wait"],
             "tokens": d["tokens"],
@@ -105,6 +115,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.5}/src/hugpy_engine/dispatch/dispatch.py

@@ -697,7 +697,25 @@ async def stream_runner(runner, req, cancel_event=None):
                         timings=getattr(result, "timings", None))
     else:
         yield ErrorEvent(request_id=req.request_id,
-                         message=getattr(result, "error", None) or "run failed")
+                         message=getattr(result, "error", None) or "run failed",
+                         load_failure=(getattr(result, "load_failure", None)
+                                       if isinstance(getattr(result, "load_failure", None), dict)
+                                       else None))
+
+
+def _rewrap_error_event(event, rid):
+    """The ONE re-wrap of an inner ErrorEvent under the outer request id
+    (S5, 2026-09-29). It used to rebuild the event from ``message`` alone, so
+    the worker's structured ``load_failure`` (class + fit_failure + refusal —
+    F3) and ``code`` were dropped HERE, on central, between the relay and the
+    /v1 envelope: the client saw ``type: api_error`` with no ``fit_failure``
+    although the worker had logged kind=vram_fit. Carry both."""
+    return ErrorEvent(request_id=rid,
+                      message=getattr(event, "message", None) or "run failed",
+                      load_failure=(getattr(event, "load_failure", None)
+                                    if isinstance(getattr(event, "load_failure", None), dict)
+                                    else None),
+                      code=(str(getattr(event, "code")) if getattr(event, "code", None) else None))
 
 
 async def execute_prompt_stream(*args, cancel_event=None, **kwargs):
@@ -948,8 +966,7 @@ async def execute_chat_stream(*args, cancel_event=None, **kwargs):
                                         output_chunks=1, finish_reason="stop",
                                         usage=usage_totals, timings=timings_last)
                     else:
-                        yield ErrorEvent(request_id=rid,
-                                         message=getattr(event, "message", None) or "run failed")
+                        yield _rewrap_error_event(event, rid)
                     errored = True
                     break
                 else:

hugpy_engine-0.2.5/src/hugpy_engine/fit/__init__.py

@@ -0,0 +1,28 @@
+"""``hugpy_engine.fit`` — the pure, deterministic evict-to-fit core.
+
+Standalone: imports only ``hugpy_engine`` siblings (``eviction``, ``spill``)
+and the standard library — no torch, no nvml, no fleet. See ``plan.py``.
+"""
+from __future__ import annotations
+
+from hugpy_engine.fit.flex import (  # noqa: F401
+    FlexPlan, PartialPlan, band_bounds, band_ceiling, band_floor,
+    ctx_band_bounds, flex_priority_key, kv_at_ctx_pct, leniency_floor_pct,
+    plan_explicit_offload, plan_flex, plan_partial_offload,
+)
+from hugpy_engine.fit.plan import evict_order, need_split, plan_fit  # noqa: F401
+from hugpy_engine.fit.types import (  # noqa: F401
+    FAILURE_KINDS, DeviceVram, Eviction, FitFailure, FitPlan, FitPolicy,
+    FitRequest, MoeSplit, Resident, ResourceSnapshot, VramSnapshot,
+    canonical_key, key_equivalent,
+)
+
+__all__ = [
+    "plan_fit", "evict_order", "need_split",
+    "ResourceSnapshot", "VramSnapshot", "DeviceVram", "FitPolicy", "Resident",
+    "FitRequest", "Eviction", "MoeSplit", "FitFailure", "FAILURE_KINDS", "FitPlan",
+    "canonical_key", "key_equivalent",
+    "FlexPlan", "PartialPlan", "band_bounds", "band_ceiling", "band_floor",
+    "ctx_band_bounds", "flex_priority_key", "kv_at_ctx_pct", "leniency_floor_pct",
+    "plan_explicit_offload", "plan_flex", "plan_partial_offload",
+]