hugpy-engine 0.2.2__tar.gz

hugpy_engine-0.2.2/LICENSE

@@ -0,0 +1,41 @@
+hugpy — Source-Available License
+
+Copyright (c) 2026 putkoff (hugpy.ai). All rights reserved.
+
+Permission is granted, free of charge, to use this software ("hugpy") for
+personal and non-commercial purposes, and for time-limited commercial
+evaluation, subject to the following conditions:
+
+1. Non-commercial use means use by an individual for personal purposes, or
+   use by a non-profit or educational institution for its own internal
+   purposes. Any use by, for, or on behalf of a for-profit business or in
+   connection with revenue-generating activity is commercial use — including
+   internal business use, use in producing goods or services, and use on
+   paid engagements.
+
+2. Commercial use requires a commercial license from the copyright holder.
+   Exception: a business may evaluate the software internally for up to
+   thirty (30) days free of charge; continued use after that requires a
+   commercial license.
+
+3. Redistribution of this software, in source or binary form, modified or
+   unmodified, is not permitted without prior written permission from the
+   copyright holder. Downloading the software from an official distribution
+   channel (PyPI, npm, hugpy.ai) is not redistribution.
+
+4. Modification for personal use or internal evaluation is permitted;
+   distribution of modified versions is not.
+
+5. This notice must be retained in all copies or substantial portions of
+   the software.
+
+6. Any use outside these terms automatically terminates this license.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+COPYRIGHT HOLDER BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY ARISING
+FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
+IN THE SOFTWARE.
+
+For commercial licensing or redistribution permission: https://hugpy.ai

hugpy_engine-0.2.2/PKG-INFO

@@ -0,0 +1,116 @@
+Metadata-Version: 2.4
+Name: hugpy-engine
+Version: 0.2.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
+Project-URL: Homepage, https://hugpy.ai
+Project-URL: Documentation, https://github.com/hugpy/hugpy/blob/main/py/inference/hugpy_engine/README.md
+Project-URL: Repository, https://github.com/hugpy/hugpy
+Project-URL: Source, https://github.com/hugpy/hugpy/tree/main/py/inference/hugpy_engine
+Project-URL: Issues, https://github.com/hugpy/hugpy/issues
+Project-URL: Changelog, https://github.com/hugpy/hugpy/releases
+Project-URL: Architecture, https://github.com/hugpy/hugpy/blob/main/PARTITION.md
+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
+License-File: LICENSE
+Requires-Dist: hugpy-platform
+Requires-Dist: hugpy-control
+Requires-Dist: hugpy-storage
+Requires-Dist: abstract-essentials
+Requires-Dist: pydantic>=2
+Requires-Dist: httpx
+Requires-Dist: requests
+Requires-Dist: huggingface-hub
+Requires-Dist: psutil
+Provides-Extra: gguf
+Requires-Dist: llama-cpp-python; extra == "gguf"
+Provides-Extra: transformers
+Requires-Dist: torch; extra == "transformers"
+Requires-Dist: transformers; extra == "transformers"
+Requires-Dist: accelerate; extra == "transformers"
+Requires-Dist: safetensors; extra == "transformers"
+Provides-Extra: finetune
+Requires-Dist: peft; extra == "finetune"
+Provides-Extra: index
+Requires-Dist: psycopg[binary]; extra == "index"
+Provides-Extra: test
+Requires-Dist: pytest>=8; extra == "test"
+Requires-Dist: pytest-timeout; extra == "test"
+Dynamic: license-file
+
+# hugpy-engine
+
+`hugpy-engine` is the standalone boundary for Hugpy's complete inference path:
+
+```text
+prompt/messages
+    -> model discovery and resolution
+    -> RAM/VRAM allocation and admission
+    -> engine and runner selection/loading
+    -> generation and continuation
+    -> streamed events or a completed reply
+```
+
+The package is split by responsibility:
+
+- `catalog` — discovered models, task/media/default model resolution;
+- `allocation` — feasible modes, default placement, spill and admission plans;
+- `engines` — native llama.cpp discovery and GGUF runner lifecycle;
+- `runtime` — request resolution, execution, runner caching and eviction;
+- `query` — prompt/messages to streamed events, text, or `QueryResult`;
+- `backend` — the injection contract joining those layers to an implementation.
+
+The package imports CPU-only: `import hugpy_engine` never loads llama_cpp,
+torch, transformers or peft. Those arrive through extras and are imported by
+the runner that needs them:
+
+| extra | provides |
+|---|---|
+| `hugpy-engine[gguf]` | in-process GGUF inference via `llama-cpp-python` |
+| `hugpy-engine[transformers]` | the transformers text-generation runner |
+| `hugpy-engine[finetune]` | PEFT adapter loading |
+| `hugpy-engine[index]` | the optional Postgres model index |
+
+The default backend is the in-process `LocalBackend` (`hugpy_engine.backends`),
+built from the engine's own catalog, allocation, native-engine and dispatch
+modules; `configure_backend(...)` / `backend_scope(...)` swap in another
+`InferenceBackend` (a fake in tests, a remote proxy in a thin client).
+
+```python
+from hugpy_engine import query_sync
+
+reply = query_sync("Explain tensor parallelism", model_key="my-model")
+```
+
+Async callers use `await query(...)`. `stream_query(...)` yields engine events;
+`query_result(...)` retains request ID, finish reason, usage, and timings.
+
+## Seams (what the engine asks of the packages above it)
+
+- `hugpy_engine.placement` — Protocols + `get_*()/set_*()` providers for
+  everything the engine asks about the fleet (worker registry and key forms,
+  worker HTTP transport/breaker, eviction telemetry ledger, blocklist, model
+  metrics, priority groups). Null defaults mean "no fleet"; `hugpy_fleet`
+  implements them and the server wires them.
+- `hugpy_engine.tasks` — the task-runner registry. Media and video runners
+  plug in with `register_task(task, runner=..., build_request=...,
+  frameworks=(...), extra=..., source=...)`; `FRAMEWORK_RUNNERS`,
+  `MODEL_REQUEST_BUILDERS` and `KNOWN_TASKS_REGISTRY` in
+  `hugpy_engine.resolvers.categories` are live views over it. Packages may
+  also expose a `hugpy_engine.tasks` entry point (a zero-arg register
+  function); the engine loads those on first use.
+- `hugpy_engine.catalog_bridge` — installs the engine's registry as
+  `hugpy_storage`'s catalog source, the hot cache as its serve-path hook, and
+  refreshes discovery on `hugpy_control.bus` `catalog.changed` events.
+  `LocalBackend` installs it lazily.
+- `hugpy_engine.name_match` — the pure eliminate-then-rank name pipeline
+  (`resolve_name`, `Candidate`) that `assure_model_key` uses; the oracle
+  re-exports it.

hugpy_engine-0.2.2/README.md

@@ -0,0 +1,68 @@
+# hugpy-engine
+
+`hugpy-engine` is the standalone boundary for Hugpy's complete inference path:
+
+```text
+prompt/messages
+    -> model discovery and resolution
+    -> RAM/VRAM allocation and admission
+    -> engine and runner selection/loading
+    -> generation and continuation
+    -> streamed events or a completed reply
+```
+
+The package is split by responsibility:
+
+- `catalog` — discovered models, task/media/default model resolution;
+- `allocation` — feasible modes, default placement, spill and admission plans;
+- `engines` — native llama.cpp discovery and GGUF runner lifecycle;
+- `runtime` — request resolution, execution, runner caching and eviction;
+- `query` — prompt/messages to streamed events, text, or `QueryResult`;
+- `backend` — the injection contract joining those layers to an implementation.
+
+The package imports CPU-only: `import hugpy_engine` never loads llama_cpp,
+torch, transformers or peft. Those arrive through extras and are imported by
+the runner that needs them:
+
+| extra | provides |
+|---|---|
+| `hugpy-engine[gguf]` | in-process GGUF inference via `llama-cpp-python` |
+| `hugpy-engine[transformers]` | the transformers text-generation runner |
+| `hugpy-engine[finetune]` | PEFT adapter loading |
+| `hugpy-engine[index]` | the optional Postgres model index |
+
+The default backend is the in-process `LocalBackend` (`hugpy_engine.backends`),
+built from the engine's own catalog, allocation, native-engine and dispatch
+modules; `configure_backend(...)` / `backend_scope(...)` swap in another
+`InferenceBackend` (a fake in tests, a remote proxy in a thin client).
+
+```python
+from hugpy_engine import query_sync
+
+reply = query_sync("Explain tensor parallelism", model_key="my-model")
+```
+
+Async callers use `await query(...)`. `stream_query(...)` yields engine events;
+`query_result(...)` retains request ID, finish reason, usage, and timings.
+
+## Seams (what the engine asks of the packages above it)
+
+- `hugpy_engine.placement` — Protocols + `get_*()/set_*()` providers for
+  everything the engine asks about the fleet (worker registry and key forms,
+  worker HTTP transport/breaker, eviction telemetry ledger, blocklist, model
+  metrics, priority groups). Null defaults mean "no fleet"; `hugpy_fleet`
+  implements them and the server wires them.
+- `hugpy_engine.tasks` — the task-runner registry. Media and video runners
+  plug in with `register_task(task, runner=..., build_request=...,
+  frameworks=(...), extra=..., source=...)`; `FRAMEWORK_RUNNERS`,
+  `MODEL_REQUEST_BUILDERS` and `KNOWN_TASKS_REGISTRY` in
+  `hugpy_engine.resolvers.categories` are live views over it. Packages may
+  also expose a `hugpy_engine.tasks` entry point (a zero-arg register
+  function); the engine loads those on first use.
+- `hugpy_engine.catalog_bridge` — installs the engine's registry as
+  `hugpy_storage`'s catalog source, the hot cache as its serve-path hook, and
+  refreshes discovery on `hugpy_control.bus` `catalog.changed` events.
+  `LocalBackend` installs it lazily.
+- `hugpy_engine.name_match` — the pure eliminate-then-rank name pipeline
+  (`resolve_name`, `Candidate`) that `assure_model_key` uses; the oracle
+  re-exports it.

hugpy_engine-0.2.2/docs/ALLOCATION-MODES.md

@@ -0,0 +1,174 @@
+# Allocation modes — where your model's memory lives
+
+Every model gets **one of five modes** that says how its weights (and KV
+context) are placed across the GPU (VRAM) and system RAM. Pick the intent; the
+fleet does the math.
+
+> **The promise:** a *slow* mode you chose is yours; a model with *no working
+> mode at all* is our bug. The default never OOMs — a blank model serves.
+
+## The five modes
+
+| mode | what it does | when it refuses ("bust") |
+|---|---|---|
+| **gpu-only** | Every layer on the GPU, no spill. Fastest when it fits. | Won't fit the GPU (even after evicting idle residents) → refuse. Never a half-load. |
+| **ram-only** | Everything in system RAM; the GPU is never touched (binds the CPU even when a GPU is present). | Won't fit RAM → refuse. |
+| **max-gpu** | *The default.* As much GPU as is available and needed, the rest spills to RAM. Zero knobs — "use my GPU, spill the rest". | Only when GPU + RAM together can't hold it. |
+| **max-ram** | Mirror of max-gpu: fill RAM first, only the overflow rides the GPU. For keeping cards free while big models stay warm. | Only when RAM + GPU together can't hold it. |
+| **explicit** | You set the targets: a VRAM and/or RAM budget, a **leniency %**, and a **priority device** (`gpu` default, or `ram`), plus the tolerance bands/priority you already know. | Can't hit the target *even at the loosened floor* → refuse. |
+
+`max-gpu` and `max-ram` are internally explicit-with-generous-leniency — but
+they stay flat, named modes on purpose: simple intent gets a simple pick; the
+moment you want to tune numbers, you reach for `explicit`.
+
+## Leniency — how much off-device you tolerate
+
+**N% leniency = up to N% of the MODEL may land off its ideal device before we
+refuse.**
+
+Example: `100% GPU target + 30% leniency`
+- Try 100% on GPU first.
+- Under pressure, degrade step by step — 90/10, 80/20 … — down to the **floor:
+  70% GPU / 30% RAM**.
+- If even 70/30 won't fit, the load refuses **honestly**, naming the mode and
+  the floor (e.g. *"explicit: even the loosened floor won't fit — target 100%
+  of the model on GPU with 30% leniency gives a floor of 70% …"*).
+
+No leniency set = exact target or refuse (no undeclared tolerance is ever
+assumed). Degradation only happens under real contention — a model that fits
+at its target always gets its target.
+
+## Engine coverage
+
+Two transformers families load differently, so they honor the modes by
+different mechanisms:
+
+- **transformers TEXT** (`AutoModelFor*`: the causal-LM generator, the flan /
+  seq2seq / summarization back-ends, the vision-language coder) place weights
+  with **accelerate** — `device_map="auto"` + a `max_memory` budget map. Every
+  mode maps onto that budget map.
+- **diffusers** (text-to-image / image-to-image pipelines) do **not** take
+  `device_map`/`max_memory`. They spill via diffusers' own **CPU-offload API**
+  instead (see the note below the table).
+
+| mode | GGUF (llama.cpp) | transformers TEXT (accelerate) | diffusers (image) |
+|---|---|---|---|
+| gpu-only | ✅ | ✅ whole model on the card (no CPU budget) | ✅ `.to(cuda)` |
+| ram-only | ✅ | ✅ CPU placement (gpu budget 0) | ✅ `enable_sequential_cpu_offload()` |
+| max-gpu | ✅ | ✅ accelerate fit-and-spill | ✅ `.to(cuda)` (auto/default) |
+| max-ram | ✅ | ✅ RAM-priority `max_memory` [^purerram] | ✅ `enable_model_cpu_offload()` |
+| explicit | ✅ | ❌ GGUF-only (banded leniency floor has no transformers analogue) | ❌ GGUF-only (same rationale) |
+
+[^purerram]: **Pure-RAM caveat.** Without a resolved `model_need_bytes` the
+transformers loaders take the SAFE pure-RAM path (the whole model on the CPU) —
+they do not yet compute the RAM-first / GPU-overflow split. A follow-up may add
+overflow-to-GPU sizing; until then max-ram on a non-GGUF text model means "RAM
+first" without spilling the remainder onto the card when the size is unknown.
+
+**Loader-level vs central gate.** Slice C wired the transformers gap loaders to
+the spill seam, so at the WORKER a transformers text model honors max-ram
+(RAM-priority `max_memory`) and the gpu-only / ram-only / max-gpu placement
+intents. **Central now accepts max-ram for non-GGUF models** (operator-approved
+2026-07-24): the engine gate at `/assign` was opened for the max-ram *mode*
+because all three gap loaders honor it (text via `transformers_max_memory`'s
+RAM-priority branch, imagegen via `enable_model_cpu_offload`). **`explicit`
+stays GGUF-only at the central gate** — its banded leniency floor is a
+llama.cpp concept with no transformers analogue, so admitting it would break the
+mode's promise. The remaining GGUF-only knobs (`gpu_mem_gib` / `cpu_mem_gib` /
+`threads` / `tensor_split` / the t21 bands / MoE `n_cpu_moe`) stay refused for
+non-GGUF exactly as before.
+
+**diffusers offload mechanism.** A diffusers pipeline can't shard by a
+`max_memory` map, so the honest spill is diffusers' offload API, chosen from the
+SAME placement seam (`spill.n_gpu_layers_intent` / `alloc_mode_env`):
+- CPU-leaning intent (ram-only / `n_gpu_layers` `off`/`0`) →
+  `enable_sequential_cpu_offload()` — submodules stream one at a time,
+  smallest VRAM footprint (slowest).
+- max-ram → `enable_model_cpu_offload()` — whole submodules ride RAM, pulled to
+  the card only while active (big model, one consumer GPU, no OOM).
+- gpu-only / auto / no intent → today's `.to(cuda)` — byte-identical when the
+  seam is silent.
+- A pipeline class without the requested offload method is a **genuine
+  capability gap**: it is logged once and falls back to `.to(cuda)` rather than
+  silently ignoring the mode.
+
+`explicit`'s numeric leniency floor is a llama.cpp-only concept with no
+transformers/diffusers analogue, so `explicit` is refused for non-GGUF at the
+central gate and is not a reachable live path for transformers. (Were the gate
+opened, a transformers/diffusers model under explicit would get only the
+budgeted fit-and-spill, not the banded degrade-to-floor — which is exactly why
+the mode's promise can't be kept there and the gate stays closed.)
+
+## MoE models — the expert split (measured, on by default)
+
+A Mixture-of-Experts GGUF is mostly **cold expert tensors**: on
+Qwen3-Coder-Next (80B-A3B class, 512 experts / 10 used per token) the expert
+FFN tensors are ~43.6 GiB of the ~45.1 GiB file — the always-hot
+attention/shared/KV share is only ~1.5 GiB. Splitting **by kind of bytes**
+instead of by whole layers changes everything:
+
+| plan (ae / RTX 3090, coder-next) | tok/s | VRAM |
+|---|---|---|
+| naive layer split (autofit, 17/48 layers) | ~15.2 | 16.6 GiB |
+| **MoE split** (`n_gpu_layers=-1` + `--n-cpu-moe 999`) | **~24.1** | **3.2 GiB** |
+
++59% throughput AND 5× less VRAM — a strict improvement, so it is the
+**default** for the hybrid case:
+
+- **Auto policy** (no knobs): a detected-MoE GGUF whose whole file does **not**
+  fit the card (exactly when autofit would have produced a partial layer
+  split) serves with all layers on the GPU and the expert tensors on CPU.
+  *Whole model fits → fully on GPU, unchanged. Dense model → byte-identical to
+  before (no expert tensors, nothing to split).* Detection is the GGUF header
+  the loader already parses: `expert_count > 0` is a MoE; the expert tensors
+  are the `blk.<i>.ffn_*_exps.*` names (`_exps` is the per-tensor expert bit).
+- **The knob**: `n_cpu_moe` — a first-class serve override / spill key (like
+  `n_gpu_layers`): the number of MoE layers whose expert tensors stay on CPU
+  (`999` = all, `0` = experts on GPU). An explicit value always wins over the
+  auto policy, and explicit `n_gpu_layers` designations (gpu-only/ram-only or
+  a layer count) always win over the auto split.
+- **Fit/feasibility price the split**: probes, the ⭐ boot load, admission and
+  central's feasibility judge a MoE by its **non-expert GPU share** (+KV) when
+  the split governs — a 41.6 GB MoE on an empty 24 GB card *fits* (needs
+  ~3 GiB of VRAM); its expert bytes are checked against host RAM instead.
+- **Engine**: needs a native `llama-server` with `--n-cpu-moe` (probed once;
+  an older binary or the `llama_cpp.server` python fallback degrades to the
+  layer-split behavior with one log line — never a crash).
+
+**Coexistence note**: ae's worker unit currently carries
+`LLAMA_ARG_N_CPU_MOE=999` (the transition-era env hack that proved the win).
+Explicit `--n-cpu-moe` argv beats the env in llama-server, so this feature is
+correct with or without it — the env line can be removed once this ships.
+
+## Legacy names (the honest rename)
+
+Old controls were misleadingly named; existing settings keep working — old
+names are accepted on input, resolved, and never written back:
+
+| old name / setting | is now | why |
+|---|---|---|
+| **autofit** ({} / no knobs) | **max-gpu** | it always was "as much GPU as fits, spill the rest" |
+| **Max GPU** (`n_gpu_layers: -1`) | **gpu-only** | it was all-or-OOM, not "maximize" — now it refuses instead of crashing |
+| **CPU only** (`n_gpu_layers: "off"`) | **ram-only** | RAM is what it actually binds |
+| **budget** / **bands** (chaos) | **explicit** | a budget/band IS an explicit allocation |
+
+Nothing on the wire changed for these three: `gpu-only` still rides
+`n_gpu_layers: -1`, `ram-only` still rides `"off"`, `max-gpu` is still `{}`.
+Your `serve_overrides.json` is never rewritten — the mode is **derived at read
+time** (`-1` → gpu-only, `0/"off"` → ram-only, budgets/bands → explicit, unset
+→ max-gpu).
+
+## Old workers
+
+`max-ram` and `explicit` ride new spill keys (`alloc_mode`, `leniency_pct`,
+`priority_device`), and the MoE `n_cpu_moe` knob rides the same gate.
+Central only emits them to workers running **0.1.203+**;
+an older worker gets max-gpu (autofit) for that request and the downgrade is
+logged — your persisted choice is kept and applies the moment the worker
+updates. A selected mode is never a silent dead knob.
+
+## Protection is unchanged
+
+Modes reorder *placement*, never protection: 🔒 static residents and models
+actively answering are never evicted to make room, whatever mode the incoming
+model carries.

hugpy_engine-0.2.2/pyproject.toml

@@ -0,0 +1,82 @@
+[build-system]
+requires = ["setuptools>=77", "setuptools-scm>=8"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "hugpy-engine"
+dynamic = ["version"]
+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"
+license-files = ["LICENSE"]
+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",
+    "hugpy-control",
+    "hugpy-storage",
+    "abstract-essentials",
+    "pydantic>=2",
+    "httpx",
+    "requests",
+    "huggingface-hub",
+    "psutil",
+]
+
+[project.urls]
+Homepage = "https://hugpy.ai"
+Documentation = "https://github.com/hugpy/hugpy/blob/main/py/inference/hugpy_engine/README.md"
+Repository = "https://github.com/hugpy/hugpy"
+Source = "https://github.com/hugpy/hugpy/tree/main/py/inference/hugpy_engine"
+Issues = "https://github.com/hugpy/hugpy/issues"
+Changelog = "https://github.com/hugpy/hugpy/releases"
+Architecture = "https://github.com/hugpy/hugpy/blob/main/PARTITION.md"
+
+[project.optional-dependencies]
+# In-process GGUF inference (LlamaCppPythonRunner). Without it the engine
+# still serves GGUF models through llama-server slots or remote workers.
+gguf = ["llama-cpp-python"]
+# transformers text-generation runner (DeepCoderChatRunner).
+transformers = ["torch", "transformers", "accelerate", "safetensors"]
+# PEFT adapter loading on top of a transformers base.
+finetune = ["peft"]
+# Postgres-backed model index (HUGPY_REGISTRY_DB=pg); inert without it.
+index = ["psycopg[binary]"]
+test = ["pytest>=8", "pytest-timeout"]
+
+[project.scripts]
+hugpy-serve = "hugpy_engine.serve.serve_cli:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+hugpy_engine = ["py.typed"]
+
+# ---------------------------------------------------------------------------
+# Lockstep workspace version (2026-09-22): every in-tree hugpy-* distribution
+# takes ONE version from the workspace git tag (vX.Y.Z at the repo root), so a
+# release is a tag and a build always carries the commit it came from
+# (X.Y.Z.devN+g<sha>[.dirty] between tags). A checkout without git metadata
+# builds as 0.0.0+unknown, which central refuses to advertise to workers.
+[tool.setuptools_scm]
+root = "../../.."
+fallback_version = "0.0.0+unknown"

hugpy_engine-0.2.2/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

hugpy_engine-0.2.2/src/hugpy_engine/__init__.py

@@ -0,0 +1,163 @@
+"""Standalone Hugpy inference boundary.
+
+Prompt/messages -> model discovery and resolution -> RAM/VRAM allocation ->
+engine/runner selection -> generation -> streamed events or a completed reply.
+
+The package imports CPU-only: llama_cpp / torch / transformers / peft load
+lazily inside the runner that needs them (``pip install hugpy-engine[gguf]``,
+``[transformers]``, ``[finetune]``). Engine-owned contracts (task capability
+map, catalog vocabulary, manifest helpers, wire schemas, the placement and
+task-plugin seams) are exposed lazily via ``__getattr__`` so ``import
+hugpy_engine`` stays light.
+"""
+
+from __future__ import annotations
+
+import importlib
+
+try:
+    from importlib.metadata import version as _package_version
+
+    __version__ = _package_version("hugpy-engine")
+except Exception:
+    __version__ = "0.0.0+unknown"  # source tree without metadata
+
+from .allocation import (
+    allocation_spill,
+    choose_allocation,
+    feasible_allocations,
+    plan_admission,
+    resource_status,
+)
+from .backend import InferenceBackend, backend_scope, configure_backend, get_backend
+from .catalog import get_model, list_models, refresh_models, resolve_model, text_chat_task
+from .contracts import ModelDescriptor, QueryError, QueryResult
+from .engines import (
+    build_native_engine,
+    evict_llama_runner,
+    install_native_engine,
+    llama_runner,
+    loaded_llama_runners,
+    native_engine_binaries,
+    native_engine_status,
+)
+from .query import query, query_result, query_result_sync, query_sync, stream_query
+from .runtime import (
+    clear_models,
+    evict_model,
+    execute_request,
+    loaded_models,
+    loading_models,
+    resolve_request,
+    runner_for,
+    stream_chat_request,
+    stream_request,
+    supported_tasks,
+)
+
+# Engine-owned contracts and seams, resolved on first attribute access
+# (PEP 562) so the package import never touches discovery or pydantic.
+_LAZY = {
+    # task capability map (consumed by fleet, oracle, server)
+    "TASK_DEPS": ("hugpy_engine.task_deps", "TASK_DEPS"),
+    "task_capabilities": ("hugpy_engine.task_deps", "task_capabilities"),
+    # catalog vocabulary
+    "HF_TASK_TO_TASKS": ("hugpy_engine.categories", "HF_TASK_TO_TASKS"),
+    "RUNNER_PAIRS": ("hugpy_engine.categories", "RUNNER_PAIRS"),
+    "TASK_DEFAULTS": ("hugpy_engine.categories", "TASK_DEFAULTS"),
+    "MEDIA_DEFAULTS": ("hugpy_engine.categories", "MEDIA_DEFAULTS"),
+    # manifest helpers
+    "load_manifest": ("hugpy_engine.manifest", "load_manifest"),
+    "load_manifest_or_empty": ("hugpy_engine.manifest", "load_manifest_or_empty"),
+    "save_manifest": ("hugpy_engine.manifest", "save_manifest"),
+    "key_for_hub_id": ("hugpy_engine.manifest", "key_for_hub_id"),
+    "upsert_model": ("hugpy_engine.manifest", "upsert_model"),
+    # seams
+    "placement": ("hugpy_engine.placement", None),
+    "tasks": ("hugpy_engine.tasks", None),
+    "register_task": ("hugpy_engine.tasks", "register_task"),
+    "runner_for_task": ("hugpy_engine.tasks", "runner_for_task"),
+    "request_builder_for_task": ("hugpy_engine.tasks", "request_builder_for_task"),
+    "catalog_bridge": ("hugpy_engine.catalog_bridge", None),
+    "LocalBackend": ("hugpy_engine.backends.local", "LocalBackend"),
+    # wire schema modules (pydantic bodies shared with the HTTP layer)
+    "wire": ("hugpy_engine.wire", None),
+    "schemas": ("hugpy_engine.schemas", None),
+}
+
+
+def __getattr__(name: str):
+    target = _LAZY.get(name)
+    if target is None:
+        raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+    module = importlib.import_module(target[0])
+    value = module if target[1] is None else getattr(module, target[1])
+    globals()[name] = value
+    return value
+
+
+def __dir__():
+    return sorted(set(globals()) | set(_LAZY))
+
+
+__all__ = [
+    "HF_TASK_TO_TASKS",
+    "InferenceBackend",
+    "LocalBackend",
+    "MEDIA_DEFAULTS",
+    "ModelDescriptor",
+    "QueryError",
+    "QueryResult",
+    "RUNNER_PAIRS",
+    "TASK_DEFAULTS",
+    "TASK_DEPS",
+    "allocation_spill",
+    "backend_scope",
+    "build_native_engine",
+    "catalog_bridge",
+    "choose_allocation",
+    "clear_models",
+    "configure_backend",
+    "evict_llama_runner",
+    "evict_model",
+    "execute_request",
+    "feasible_allocations",
+    "get_backend",
+    "get_model",
+    "install_native_engine",
+    "key_for_hub_id",
+    "list_models",
+    "llama_runner",
+    "load_manifest",
+    "load_manifest_or_empty",
+    "loaded_llama_runners",
+    "loaded_models",
+    "loading_models",
+    "native_engine_binaries",
+    "native_engine_status",
+    "placement",
+    "plan_admission",
+    "query",
+    "query_result",
+    "query_result_sync",
+    "query_sync",
+    "refresh_models",
+    "register_task",
+    "request_builder_for_task",
+    "resolve_model",
+    "resolve_request",
+    "resource_status",
+    "runner_for",
+    "runner_for_task",
+    "save_manifest",
+    "schemas",
+    "stream_chat_request",
+    "stream_query",
+    "stream_request",
+    "supported_tasks",
+    "task_capabilities",
+    "tasks",
+    "text_chat_task",
+    "upsert_model",
+    "wire",
+]