hugpy-resources 0.1.3__tar.gz

hugpy_resources-0.1.3/PKG-INFO

@@ -0,0 +1,10 @@
+Metadata-Version: 2.4
+Name: hugpy-resources
+Version: 0.1.3
+Summary: Shared generic utilities, file inspection and model resource evidence contracts
+Requires-Python: >=3.9
+Provides-Extra: inspection
+Requires-Dist: sentencepiece>=0.2; extra == "inspection"
+Requires-Dist: protobuf>=4; extra == "inspection"
+Provides-Extra: yaml
+Requires-Dist: PyYAML; extra == "yaml"

hugpy_resources-0.1.3/README.md

@@ -0,0 +1,144 @@
+# Shared resource evidence
+
+`hugpy-resources` owns pure payload formulas, Transformers config geometry and
+resource-term accounting for Discovery and Wrapper. Its base install uses the standard library; it imports no engine, external
+database driver or hardware probe. Shared file inspection and filesystem
+utilities perform their work only when called. Consumer import boundaries resolve the canonical definitions; formula catalog pointers name their actual owners.
+
+`imports.functions.requirements.transformer_memory` returns per-device loading and serving terms.
+Their maximum is the required peak; any missing term leaves that peak unknown.
+Historical measurements are retained as component observations. They do not
+prove unrecorded runtime/workload scope or missing peak bounds. Explicit
+`resource_bounds` must be scoped by the caller to the selected artifact,
+runtime, placement and workload. There is currently no persisted producer of
+complete backend bounds, so legacy Transformers facts alone cannot certify a load.
+
+`imports.functions.runtime.derive` produces conditional loading and inference tensor reservations
+from shared config geometry and selected safetensors metadata. Wrapper collects
+the largest selected shard and largest BF16/FP16 destination tensor using
+headers/stat only. The same derivation feeds adapter and sizing requirements.
+It does not substitute an observed after-load size for a loading peak. See
+[runtime derivation](RUNTIME_DERIVATION.md) for equations, scope and actual
+inventory results. Backend workspace, loader workspace and allocator overhead
+remain named unknowns until supported evidence supplies them.
+
+Wrapper attaches these records to `ModelFootprint`. Unknown requirements refuse
+before resident replacement; the pure commit check compares complete selected
+requirements with captured device/host budgets before unloading victims. The
+existing eviction eligibility and ordering modules retain victim authority.
+
+Install this package alongside staged Discovery and Wrapper sources. Wrapper's
+offline Debian builder includes its wheel. Source changes are not deployed by
+editing these files. No tests or runtime load validation were run for this
+refactor; existing database validation records belong to the previous revision.
+
+## Source organization
+
+The package source is `src/hugpy_resources`. Standard-library and external
+imports go through `imports/init_imports.py`; shared constants live in
+`imports/constants/`. Reusable arithmetic lives in `imports/functions/`,
+grouped into integer validation, tensors, KV cache, recurrent state,
+quantization, placement, memory budgets, configuration, geometry, runtime
+envelopes, evidence, cache ladders, feasibility and requirements.
+
+Import implementations directly from `hugpy_resources.imports.functions` or a
+specific module in that package. The former `formulas`, `geometry`, `devices`,
+`runtime`, and `requirements` forwarding modules have been removed. Internal
+imports are relative; shared tables and vocabularies live in `imports/constants/`.
+Optional parser dependencies load only when the corresponding format is read.
+
+## Generic function reference
+
+Resources is the shared reference for generic utilities used by Discovery.
+Implementations live in `src/hugpy_resources/imports/functions/`; generic
+constants, parsing errors and MIME data live beside them under `imports/`.
+
+| Script | Responsibility |
+| --- | --- |
+| `json_utils.py` | Stable JSON, duplicate-key validation and content digests |
+| `formatting.py` | Human-readable byte counts |
+| `ast_utils.py` | Dotted AST names and JSON-compatible literals |
+| `paths.py` | Path resolution, metadata snapshots and repository-relative paths |
+| `locking.py` | Nonblocking exclusive file locks |
+| `sqlite.py`, `sqlite_connections.py` | SQL identifiers, row writes, read-only connections and WAL retry |
+| `file_types.py` | MIME hints and bounded file-format identification |
+| `tensor_files.py` | Header-only tensor inspection, separate from `tensors.py` arithmetic |
+| `gguf_headers.py`, `gguf_moe.py`, `gguf_structure.py` | GGUF headers, integrity, expert tensors and geometry |
+| `content_proofs.py` | Stable-file SHA256 and Git-blob SHA1, without queues or publication |
+| `source_fingerprints.py` | Deterministic package code/data fingerprints |
+
+Use `hugpy_resources.imports` or a specific implementation module. Optional
+SentencePiece/protobuf decoding is installed with `hugpy-resources[inspection]`
+and imported only for that inspection. Generic helpers do not import Discovery,
+Storage, Wrapper or a provider SDK. Consumers supply workflow policy; for
+example, `directory_snapshot(root, excluded_directories=...)` accepts the
+consumer's exclusions.
+
+
+## Tools consume shared implementations
+
+`hugpy-tools` imports Resources for its generic file/path operations, structured
+data, hashing, text, time and local search engine. Consumers import Resources directly. The old generic Tools modules are
+removed; tool registration, input schemas, dispatch and backend adapters stay
+in Tools. Resources never imports Tools.
+
+Additional generic groups are `filesystem.py`, `hashing.py`,
+`structured_data.py`, `text.py`, `time_utils.py`, `search.py` and `processes.py`.
+Path operations share `paths.py`; safe JSON dumping/key traversal share
+`json_utils.py`; common limits and patterns live in `imports/constants/`.
+`PathEscape` is defined once in `imports/classes.py`.
+
+Search's `read_text` keeps its own search-specific result contract; the shared
+`imports.read_text` export names the filesystem reader. Use the search module
+for search operations. Token estimation remains approximate; no model or
+provider package is loaded by the base implementation. YAML parsing is optional
+through `hugpy-resources[yaml]` or Tools' existing YAML extra.
+
+`./ops.sh local-pip-update --plan` shows a local install plan. Local installs
+build and archive a new numeric revision. `./ops.sh push-to-pypi --plan` and
+`./ops.sh push-to-github --plan` show the existing release actions; Tools' push
+plan runs Resources first.
+
+Generic argument parsing (`coerce_args`, `parse_bool`), SQL quoting
+(`sql_identifier`, `sql_literal`), and explicit environment-file parsing
+(`environment`, `home_dir`, `expand_home`, `parse_env_file`) are grouped under
+`imports/functions/`. `terminal_text.py` supplies shared terminal sanitization,
+Unicode cell widths, clipping, and wrapping; the shared export surface uses
+`clean_terminal_text`, `terminal_cell_width`, `terminal_text_width`,
+`cut_terminal_text`, and `wrap_terminal_text` to distinguish these operations
+from generic text processing.
+
+## Suite nomenclature
+
+[Resource and storage nomenclature](docs/nomenclature.md) defines store roles,
+T0/T1/T2 capacity tiers, allocation accounting, module ownership, and the
+non-expert-first GPU priority for spill placement. Import `TERM_LABELS`,
+`TERM_DEFINITIONS`, and `PLACEMENT_TERM_ALIASES` from `hugpy_resources.imports`
+for shared strings. MoE names architecture; Spill names the placement policy.
+Legacy placement identifiers remain compatible; the glossary distinguishes
+that policy contract from backend implementation status.
+
+`response_shape` is the pure response-structure validator used by Wrapper's
+engine capability probes. It checks chat, embeddings, and explicitly required
+JSON keys without launching engines or interpreting a pass as general model
+compatibility. Probe orchestration and evidence persistence remain in Wrapper.
+
+## Consolidated runtime primitives
+
+Wrapper, Discovery and Toolserver share implementations below the application
+layer. `imports/classes/` owns exceptions, row/cursor adapters, HTTP scaffolding,
+NVML structures and stream splitters. `imports/constants/` separates evidence
+contracts from shared platform, format and protocol contracts.
+
+Environment overrides and application paths live in `env_values`, `environment`
+and `application_paths`. CPU/process/host/NVML readers, model config/identity,
+Comfy declarations, GGUF shard grouping, strict safetensors selection, inference
+timings, reasoning and tool-call parsing are grouped by purpose under
+`imports/functions/`. Similar APIs with different error or identity semantics
+remain separate. `python_environments.provision_python_environment` performs
+explicit installation only when called; the caller owns package/version policy.
+
+Resources has no mandatory backend or application dependencies. Standard and
+external imports resolve through `imports/init_imports.py`. Hardware libraries,
+model backends and optional parsers remain deferred to their feature call sites.
+Wrapper-specific placement and quantization preference policies remain in Wrapper.

hugpy_resources-0.1.3/pyproject.toml

@@ -0,0 +1,20 @@
+[build-system]
+requires = ["setuptools>=61"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "hugpy-resources"
+version = "0.1.3"
+description = "Shared generic utilities, file inspection and model resource evidence contracts"
+requires-python = ">=3.9"
+dependencies = []
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[project.optional-dependencies]
+inspection = ["sentencepiece>=0.2", "protobuf>=4"]
+yaml = ["PyYAML"]
+
+[tool.setuptools.package-data]
+"hugpy_resources.imports" = ["*.json"]

hugpy_resources-0.1.3/setup.cfg

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

hugpy_resources-0.1.3/src/hugpy_resources/__init__.py

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

hugpy_resources-0.1.3/src/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-0.1.3/src/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-0.1.3/src/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-0.1.3/src/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-0.1.3/src/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-0.1.3/src/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-0.1.3/src/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-0.1.3/src/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 []