hugpy-resources 0.1.3__py3-none-any.whl

hugpy_resources/__init__.py

@@ -0,0 +1,3 @@
+"""Pure resource contracts; no engines, database connections or hardware probes."""
+
+

hugpy_resources/imports/__init__.py

@@ -0,0 +1,35 @@
+"""Public shared constants, classes and generic utilities.
+
+Function/class ownership is declared only in their projections. Constants load
+on first use; optional function implementations load only when requested.
+"""
+
+from importlib import import_module as _import_module
+
+from . import classes as _classes
+from . import functions as _functions
+
+
+def __getattr__(name):
+    if name == "__all__":
+        constants = _import_module(f"{__name__}.constants")
+        value = list(dict.fromkeys([
+            *constants.__all__, *_functions.__all__, *_classes.__all__,
+        ]))
+    elif name in _functions.__all__:
+        # A loaded child module can have the same name as an exported function
+        # (for example environment). Resolve the declared owner explicitly.
+        value = _functions.__getattr__(name)
+    elif name in _classes.__all__:
+        value = _classes.__getattr__(name)
+    else:
+        constants = _import_module(f"{__name__}.constants")
+        if name not in constants.__all__:
+            raise AttributeError(f"{__name__!r} has no attribute {name!r}") from None
+        value = getattr(constants, name)
+    globals()[name] = value
+    return value
+
+
+def __dir__():
+    return sorted(set(globals()) | set(__getattr__("__all__")))

hugpy_resources/imports/classes/__init__.py

@@ -0,0 +1,24 @@
+"""Canonical reusable errors, records, protocol parsers and HTTP scaffold."""
+
+from hugpy_resources.lazy_imports import import_registry, resolve_import
+
+from ..init_imports import import_module
+
+_EXPORTS = import_registry({
+    '.errors': (
+        'GGUFHeaderError PathEscape LocalRequestError ChatRequestError TaskRequestError '
+        'StoreError'
+    ),
+    '.database': 'Row Cursor',
+    '.nvml': '_MemV2 _Mem _ProcV3',
+    '.thinking': 'ThinkSplitter',
+    '.tool_calls': 'StreamSplitter',
+    '.http': 'make_child_handler',
+})
+
+
+def __getattr__(name):
+    return resolve_import(globals(), _EXPORTS, name)
+
+
+__all__ = list(_EXPORTS)

hugpy_resources/imports/classes/database.py

@@ -0,0 +1,49 @@
+"""Reusable database definitions."""
+
+from __future__ import annotations
+
+
+class Row:
+    """sqlite3.Row compatible access, including duplicate projection names."""
+
+    def __init__(self, names, values):
+        self._names, self._values = tuple(names), tuple(values)
+
+    def __getitem__(self, key):
+        if isinstance(key, (int, slice)):
+            return self._values[key]
+        try:
+            return self._values[self._names.index(key)]
+        except ValueError:
+            raise KeyError(key) from None
+
+    def __iter__(self):
+        return iter(self._values)
+
+    def __len__(self):
+        return len(self._values)
+
+    def keys(self):
+        return self._names
+
+    def get(self, key, default=None):
+        try:
+            return self[key]
+        except KeyError:
+            return default
+
+
+class Cursor:
+    def __init__(self, rows, rowcount=0, lastrowid=None, columns=(), values=()):
+        self.rows = iter(
+            [Row(columns, row) for row in values]
+            if columns
+            else [Row(row.keys(), row.values()) for row in rows]
+        )
+        self.rowcount, self.lastrowid = rowcount, lastrowid
+
+    def fetchone(self):
+        return next(self.rows, None)
+
+    def fetchall(self):
+        return list(self.rows)

hugpy_resources/imports/classes/errors.py

@@ -0,0 +1,74 @@
+"""Reusable parsing errors."""
+
+
+class GGUFHeaderError(ValueError):
+    """The GGUF header is unreadable (magic, version, extent or EOF)."""
+
+
+__all__ = ["GGUFHeaderError"]
+
+
+class PathEscape(ValueError):
+    """A path resolved outside the confinement root."""
+
+
+__all__ += ["PathEscape"]
+
+
+class LocalRequestError(Exception):
+    """Fallback request error so a runner / child module is importable and
+    py_compile-clean on its own (e.g. a unit test imports ``handle`` directly).
+
+    The child process INJECTS its own ``RequestError`` class into the runner's
+    namespace before serving; that class carries the same ``(status, message)``
+    and a ``.body`` dict, so ``raise RequestError(400, …)`` stays catchable.
+    """
+
+    def __init__(self, status: int, message: str, **extra):
+        super().__init__(message)
+        self.status = int(status)
+        self.message = message
+        self.extra = extra
+
+    @property
+    def body(self) -> dict:
+        err = {
+            "message": self.message,
+            "type": "invalid_request_error",
+            "code": self.status,
+        }
+        err.update(self.extra)
+        return {"error": err}
+
+
+class ChatRequestError(Exception):
+    """An OpenAI-style client error: HTTP ``status`` + error body."""
+
+    def __init__(
+        self, status: int, message: str, etype: str = "invalid_request_error", **extra
+    ):
+        super().__init__(message)
+        self.status = status
+        self.body = {
+            "error": {"code": status, "type": etype, "message": message, **extra}
+        }
+
+
+class TaskRequestError(Exception):
+    """An OpenAI-style client error: HTTP ``status`` + error body. INJECTED into
+    the runner module's namespace before use, so a runner raises
+    ``RequestError(400, …)`` and it is caught here as a 4xx (never a 500)."""
+
+    def __init__(
+        self, status: int, message: str, etype: str = "invalid_request_error", **extra
+    ):
+        super().__init__(message)
+        self.status = int(status)
+        self.message = message
+        self.body = {
+            "error": {"code": int(status), "type": etype, "message": message, **extra}
+        }
+
+
+class StoreError(RuntimeError):
+    """The store could not be opened or migrated."""

hugpy_resources/imports/classes/http.py

@@ -0,0 +1,116 @@
+"""HTTP scaffold for engine children."""
+
+from __future__ import annotations
+from ..init_imports import json
+from ..init_imports import traceback
+from ..init_imports import BaseHTTPRequestHandler
+
+
+def _not_found(path: str) -> dict:
+    return {
+        "error": {"code": 404, "type": "not_found_error", "message": f"no route {path}"}
+    }
+
+
+def make_child_handler(server, request_error_cls, *, chat: bool = True, log=None):
+    """Build the ``BaseHTTPRequestHandler`` subclass the child model servers use.
+
+    Shared across tf_child / vision_child / task_child: ``log_message`` (silent —
+    stderr is the loader-log channel), ``_json``, and the GET routes
+    (``/health``, ``/v1/models``, ``/props``). With ``chat=True`` (tf/vision) the
+    POST route is ``/v1/chat/completions``, errors fall back to a 500 (logged via
+    ``log`` if given), and the subclass supplies ``_stream``; with ``chat=False``
+    (task) the subclass supplies its own ``do_POST``.
+
+    ``server`` must expose ``models_doc()``/``props_doc()`` and, for chat,
+    ``lock``/``prepare(body)``/``complete(job)``. ``request_error_cls`` is the
+    child's injected ``RequestError``; ``log`` is the child's ``_log``.
+    """
+    RequestError = request_error_cls
+
+    class _Handler(BaseHTTPRequestHandler):
+        protocol_version = "HTTP/1.0"
+
+        def log_message(self, fmt, *args):  # keep the loader log for errors only
+            pass
+
+        def _json(self, status: int, doc: dict) -> None:
+            data = json.dumps(doc).encode()
+            self.send_response(status)
+            self.send_header("Content-Type", "application/json")
+            self.send_header("Content-Length", str(len(data)))
+            self.end_headers()
+            self.wfile.write(data)
+
+        def do_GET(self):
+            path = self.path.split("?", 1)[0]
+            if path == "/health":
+                return self._json(200, {"status": "ok"})
+            if path == "/v1/models":
+                return self._json(200, server.models_doc())
+            if path == "/props":
+                return self._json(200, server.props_doc())
+            return self._json(404, _not_found(path))
+
+        if chat:
+
+            def do_POST(self):
+                path = self.path.split("?", 1)[0]
+                if path not in ("/v1/chat/completions", "/tokenize"):
+                    return self._json(404, _not_found(path))
+                try:
+                    n = int(self.headers.get("Content-Length") or 0)
+                    body = json.loads(self.rfile.read(n) or b"{}")
+                    if not isinstance(body, dict):
+                        raise RequestError(400, "request body must be a JSON object")
+                except (ValueError, RequestError) as exc:
+                    err = (
+                        exc
+                        if isinstance(exc, RequestError)
+                        else RequestError(400, f"bad JSON: {exc}")
+                    )
+                    return self._json(err.status, err.body)
+                if path == "/tokenize":
+                    tokenize = getattr(server, "tokenize_doc", None)
+                    if tokenize is None:
+                        return self._json(404, _not_found(path))
+                    if not server.lock.acquire(blocking=False):
+                        return self._json(
+                            409,
+                            {
+                                "error": {
+                                    "message": "Tokenizer preflight deferred while the engine is busy"
+                                }
+                            },
+                        )
+                    try:
+                        return self._json(200, tokenize(body))
+                    except RequestError as exc:
+                        return self._json(exc.status, exc.body)
+                    except Exception as exc:
+                        return self._json(400, {"error": {"message": str(exc)}})
+                    finally:
+                        server.lock.release()
+                with server.lock:
+                    try:
+                        job = server.prepare(body)
+                        if not body.get("stream"):
+                            return self._json(200, server.complete(job))
+                        return self._stream(job)
+                    except RequestError as exc:
+                        return self._json(exc.status, exc.body)
+                    except Exception as exc:  # noqa: BLE001 — the real error, to the caller and the log
+                        if log:
+                            log(traceback.format_exc())
+                        return self._json(
+                            500,
+                            {
+                                "error": {
+                                    "code": 500,
+                                    "type": "server_error",
+                                    "message": f"{type(exc).__name__}: {exc}",
+                                }
+                            },
+                        )
+
+    return _Handler

hugpy_resources/imports/classes/nvml.py

@@ -0,0 +1,32 @@
+"""Reusable nvml definitions."""
+
+from __future__ import annotations
+
+from ..init_imports import ctypes
+
+
+class _MemV2(ctypes.Structure):
+    _fields_ = [
+        ("version", ctypes.c_uint),
+        ("total", ctypes.c_ulonglong),
+        ("reserved", ctypes.c_ulonglong),
+        ("free", ctypes.c_ulonglong),
+        ("used", ctypes.c_ulonglong),
+    ]
+
+
+class _Mem(ctypes.Structure):
+    _fields_ = [
+        ("total", ctypes.c_ulonglong),
+        ("free", ctypes.c_ulonglong),
+        ("used", ctypes.c_ulonglong),
+    ]
+
+
+class _ProcV3(ctypes.Structure):
+    _fields_ = [
+        ("pid", ctypes.c_uint),
+        ("usedGpuMemory", ctypes.c_ulonglong),
+        ("gpuInstanceId", ctypes.c_uint),
+        ("computeInstanceId", ctypes.c_uint),
+    ]

hugpy_resources/imports/classes/thinking.py

@@ -0,0 +1,77 @@
+# Streaming sibling of no_think.strip_think: separate a model's <think> reasoning
+# from its answer prose INCREMENTALLY, as content deltas arrive, so the front
+# door can re-emit delta.reasoning_content vs delta.content live. The engine
+# (llama-server --reasoning-format deepseek) usually separates reasoning itself;
+# this is the fallback for inline-tag replies (reasoning-format none / a model
+# whose template leaves <think> tags in message.content).
+#
+# Final-assembly semantics match no_think.strip_think (<think>...</think> blocks
+# and an unclosed <think>...EOF are reasoning). An ORPHAN </think> (a template
+# that opens <think> in the prompt, so the reply starts mid-reasoning with no
+# opening tag) is handled downstream by hugpy_core.grader.strip_think on the
+# assembled text; live, text before an orphan close streams as content and the
+# answer after it streams as content too — the grader's rule salvages the answer.
+"""Incremental <think> splitter for streamed content."""
+
+from __future__ import annotations
+
+from ..constants import THINK_CLOSE_TAG as _CLOSE
+from ..constants import THINK_OPEN_TAG as _OPEN
+
+
+from ..functions.thinking import _partial_tail
+
+
+class ThinkSplitter:
+    """Feed streamed content text; get back (channel, chunk) pairs where channel
+    is 'reasoning' (inside a <think> block) or 'content' (the answer). Holds back
+    a short tail when the buffer might end mid-tag, so a tag split across two
+    feeds is still recognised."""
+
+    def __init__(self) -> None:
+        self._buf = ""
+        self._mode = "content"  # 'content' | 'reasoning'
+
+    def feed(self, text: str) -> "list[tuple[str, str]]":
+        out: "list[tuple[str, str]]" = []
+        if not text:
+            return out
+        self._buf += text
+        while True:
+            low = self._buf.lower()
+            i_open = low.find(_OPEN)
+            i_close = low.find(_CLOSE)
+            cands = [p for p in (i_open, i_close) if p != -1]
+            if cands:
+                idx = min(cands)
+                is_open = idx == i_open
+                tag = _OPEN if is_open else _CLOSE
+                before = self._buf[:idx]
+                if before:
+                    out.append((self._mode, before))
+                self._buf = self._buf[idx + len(tag) :]
+                self._mode = "reasoning" if is_open else "content"
+                continue
+            hold = _partial_tail(self._buf)
+            if hold:
+                emit = self._buf[: len(self._buf) - hold]
+                if emit:
+                    out.append((self._mode, emit))
+                self._buf = self._buf[len(self._buf) - hold :]
+            else:
+                if self._buf:
+                    out.append((self._mode, self._buf))
+                self._buf = ""
+            break
+        return out
+
+    def close(self) -> "list[tuple[str, str]]":
+        """Flush whatever is held (a dangling partial tag, treated as text)."""
+        out: "list[tuple[str, str]]" = []
+        if self._buf:
+            out.append((self._mode, self._buf))
+            self._buf = ""
+        return out
+
+
+__all__ = ["ThinkSplitter"]

hugpy_resources/imports/classes/tool_calls.py

@@ -0,0 +1,53 @@
+"""Reusable tool calls definitions."""
+
+from __future__ import annotations
+
+from ..functions.tool_calls import _calls
+from ..constants import _BLOCK
+from ..constants import DSML_TOOLS_TAGS as _TAGS
+
+
+class StreamSplitter:
+    """Streamed reply: feed() content pieces; yields ("content", text) for prose and
+    ("tool_calls", [call, ...]) once a whole block has arrived. Text that may be the
+    start of a block is held back until it is known not to be one."""
+
+    def __init__(self):
+        self.buf = ""
+        self.emitted = 0  # tool calls sent so far (their stream index)
+
+    def _hold_from(self) -> int:
+        """Index from which the buffer must be held (a block, or a possible tag start)."""
+        starts = [i for tag in _TAGS if (i := self.buf.find(tag)) >= 0]
+        if starts:
+            return min(starts)
+        for k in range(min(max(map(len, _TAGS)) - 1, len(self.buf)), 0, -1):
+            if any(tag.startswith(self.buf[-k:]) for tag in _TAGS):
+                return len(self.buf) - k
+        return len(self.buf)
+
+    def feed(self, piece: str):
+        self.buf += piece or ""
+        out = []
+        while True:
+            m = _BLOCK.search(self.buf)
+            if m:
+                if m.start():
+                    out.append(("content", self.buf[: m.start()]))
+                calls = _calls(m.group(2))
+                if calls:
+                    out.append(("tool_calls", calls))
+                else:
+                    out.append(("content", m.group(0)))
+                self.buf = self.buf[m.end() :]
+                continue
+            cut = self._hold_from()
+            if cut:
+                out.append(("content", self.buf[:cut]))
+                self.buf = self.buf[cut:]
+            return out
+
+    def close(self):
+        """End of stream: an unfinished block is passed through as text (never lost)."""
+        rest, self.buf = self.buf, ""
+        return [("content", rest)] if rest else []

hugpy_resources/imports/constants/__init__.py

@@ -0,0 +1,45 @@
+"""Typed constants projected from terms, exported once by each domain.
+
+Domains load together when this projection is first requested. Public exports
+come from their __all__ declarations; no second list of symbols is maintained.
+"""
+
+from importlib import import_module as _import_module
+
+_DOMAINS = (
+    'math',
+    'terms',
+    'platform',
+    'formats',
+    'gguf',
+    'tensors',
+    'architecture',
+    'memory',
+    'hardware',
+    'engines',
+    'text',
+    'tool_calls',
+    'identity',
+    'transfer',
+    'comfy',
+    'placement',
+    'cpu',
+    'context',
+    'admission',
+    'validation',
+    'drives',
+    'timing',
+    'audit',
+)
+
+__all__ = []
+for _domain_name in _DOMAINS:
+    _domain = _import_module(f"{__name__}.{_domain_name}")
+    globals()[_domain_name] = _domain
+    for _name in _domain.__all__:
+        if _name in __all__:
+            raise ValueError(f"duplicate constant export: {_name}")
+        globals()[_name] = getattr(_domain, _name)
+        __all__.append(_name)
+
+del _domain_name, _domain, _name

hugpy_resources/imports/constants/admission.py

@@ -0,0 +1,19 @@
+"""Admission projections of terms.json; authored values belong to terms."""
+
+from __future__ import annotations
+
+from .terms import value as _value, group as _group
+
+from .terms import knob_schema
+
+RESIDENCY_MODES = _value('admission', 'residency_modes')
+
+ADMISSION_KNOB_TERMS = _group('admission_knobs')
+
+ADMISSION_KNOB_SCHEMA = knob_schema(ADMISSION_KNOB_TERMS)
+
+__all__ = [
+    'RESIDENCY_MODES',
+    'ADMISSION_KNOB_TERMS',
+    'ADMISSION_KNOB_SCHEMA',
+]

hugpy_resources/imports/constants/architecture.py

@@ -0,0 +1,84 @@
+"""Architecture projections of terms.json; authored values belong to terms."""
+
+from __future__ import annotations
+
+from .terms import value as _value, group as _group
+
+TRANSFORMERS_GATED_DELTA = _value('architecture', 'transformers_gated_delta')
+
+
+NO_CONTEXT_HEADS = _value('architecture', 'no_context_heads')
+
+
+DENSE_DECODERS = _value('architecture', 'dense_decoders')
+
+
+MOE_DECODERS = _value('architecture', 'moe_decoders')
+
+
+DTYPE_BITS = {key: term["bits"] for key, term in _group("tensor_dtypes").items()}
+
+RECURRENT_COUNT_FIELDS = _value('architecture', 'recurrent_count_fields')
+
+TEXT_CONFIG_KEYS = _value('architecture', 'text_config_keys')
+
+DECODER_LAYER_KEYS = _value('architecture', 'decoder_layer_keys')
+
+MODEL_LAYER_KEYS = _value('architecture', 'model_layer_keys')
+
+DECODER_ATTENTION_HEAD_KEYS = _value('architecture', 'decoder_attention_head_keys')
+
+ATTENTION_HEAD_KEYS = _value('architecture', 'attention_head_keys')
+
+KV_HEAD_KEYS = _value('architecture', 'kv_head_keys')
+
+HEAD_DIM_KEYS = _value('architecture', 'head_dim_keys')
+
+HIDDEN_SIZE_KEYS = _value('architecture', 'hidden_size_keys')
+
+ATTENTION_LAYER_TYPES = _value('architecture', 'attention_layer_types')
+
+RECURRENT_LAYER_TYPES = _value('architecture', 'recurrent_layer_types')
+
+RECURRENT_MODEL_TYPES = _value('architecture', 'recurrent_model_types')
+
+CONTEXT_LENGTH_KEYS = _value('architecture', 'context_length_keys')
+
+LINEAR_STATE_KEYS = _value('architecture', 'linear_state_keys')
+
+UNSUPPORTED_OUTPUT_FLAGS = _value('architecture', 'unsupported_output_flags')
+
+EXPERT_COUNT_KEYS = _value('architecture', 'expert_count_keys')
+
+RUNTIME_DENSE_GEOMETRY_FIELDS = _value('architecture', 'runtime_dense_geometry_fields')
+
+RUNTIME_EXPERT_GEOMETRY_FIELDS = _value('architecture', 'runtime_expert_geometry_fields')
+
+RUNTIME_DENSE_DTYPES = _value('architecture', 'runtime_dense_dtypes')
+
+__all__ = [
+    'TRANSFORMERS_GATED_DELTA',
+    'NO_CONTEXT_HEADS',
+    'DENSE_DECODERS',
+    'MOE_DECODERS',
+    'DTYPE_BITS',
+    'RECURRENT_COUNT_FIELDS',
+    'TEXT_CONFIG_KEYS',
+    'DECODER_LAYER_KEYS',
+    'MODEL_LAYER_KEYS',
+    'DECODER_ATTENTION_HEAD_KEYS',
+    'ATTENTION_HEAD_KEYS',
+    'KV_HEAD_KEYS',
+    'HEAD_DIM_KEYS',
+    'HIDDEN_SIZE_KEYS',
+    'ATTENTION_LAYER_TYPES',
+    'RECURRENT_LAYER_TYPES',
+    'RECURRENT_MODEL_TYPES',
+    'CONTEXT_LENGTH_KEYS',
+    'LINEAR_STATE_KEYS',
+    'UNSUPPORTED_OUTPUT_FLAGS',
+    'EXPERT_COUNT_KEYS',
+    'RUNTIME_DENSE_GEOMETRY_FIELDS',
+    'RUNTIME_EXPERT_GEOMETRY_FIELDS',
+    'RUNTIME_DENSE_DTYPES',
+]

hugpy_resources/imports/constants/audit.py

@@ -0,0 +1,6 @@
+"""Audit and row-history projections of terms.json."""
+from .terms import value as _value
+HISTORY_TABLE = _value('audit', 'history_table')
+VOLATILE_COLUMNS = _value('audit', 'history_volatile_columns')
+HISTORY_CHUNK = _value('audit', 'history_chunk')
+__all__ = ['HISTORY_TABLE', 'VOLATILE_COLUMNS', 'HISTORY_CHUNK']

hugpy_resources/imports/constants/comfy.py

@@ -0,0 +1,15 @@
+"""Comfy projections of terms.json; authored values belong to terms."""
+
+from .terms import value as _value
+
+COMFY_REFERENCE_FAMILIES = _value('comfy', 'comfy_reference_families')
+
+COMFY_REFERENCE_FIELDS = _value('comfy', 'comfy_reference_fields')
+
+COMFY_REFERENCE_FILE_FIELDS = _value('comfy', 'comfy_reference_file_fields')
+
+__all__ = [
+    'COMFY_REFERENCE_FAMILIES',
+    'COMFY_REFERENCE_FIELDS',
+    'COMFY_REFERENCE_FILE_FIELDS',
+]

hugpy_resources/imports/constants/context.py

@@ -0,0 +1,37 @@
+"""Context projections of terms.json; authored values belong to terms."""
+
+from __future__ import annotations
+
+from .terms import value as _value, group as _group
+
+from .terms import knob_schema
+
+CONTEXT_PERCENT_KNOBS = _value('context', 'context_percent_knobs')
+
+KV_CACHE_TYPES = _value('context', 'kv_cache_types')
+
+CONTEXT_PRESETS = _value('context', 'context_presets')
+
+CONTEXT_PERCENT_MIN = _value('context', 'context_percent_min')
+
+PAIR_KNOB_RENAMES = _value('context', 'pair_knob_renames')
+
+CONTEXT_KNOB_TERMS = _group('context_knobs')
+
+CONTEXT_KNOB_SCHEMA = knob_schema(CONTEXT_KNOB_TERMS)
+
+# Derived from the schema so they can never drift from the context knobs themselves.
+CONTEXT_KEYS = tuple(knob["key"] for knob in CONTEXT_KNOB_SCHEMA)
+CONTEXT_BOOLEAN_KNOBS = tuple(knob["key"] for knob in CONTEXT_KNOB_SCHEMA if knob["type"] == "bool")
+
+__all__ = [
+    'CONTEXT_PERCENT_KNOBS',
+    'KV_CACHE_TYPES',
+    'CONTEXT_PRESETS',
+    'CONTEXT_PERCENT_MIN',
+    'PAIR_KNOB_RENAMES',
+    'CONTEXT_KNOB_TERMS',
+    'CONTEXT_KNOB_SCHEMA',
+    'CONTEXT_KEYS',
+    'CONTEXT_BOOLEAN_KNOBS',
+]