zu-huggingface 0.2.2__py3-none-any.whl

zu_huggingface/__init__.py

@@ -0,0 +1,74 @@
+"""zu-huggingface — HuggingFace models behind Zu's typed ports (§8.3–8.5).
+
+HuggingFace is not a model — it is the largest hub of open models across every
+modality. This package reaches it three ways, all behind configuration:
+
+* **Chat / vision-language models as the policy** need *no code here* — they
+  speak the OpenAI chat API on all three serving surfaces (the router's ``/v1``,
+  an Endpoint's ``/v1``, or a local vLLM), so a HuggingFace model as the brain
+  is the existing ``openai-compatible`` provider pointed at a HuggingFace base
+  URL (see this package's README). It is the OpenRouter story exactly.
+
+* **Task models** (ASR, OCR, detection, embeddings, classification,
+  summarisation, translation) are *not* chat models — each has its own typed
+  I/O — so they enter through the non-policy ports by their role: as **Tools**
+  (``tools.py``) and as **detectors / validators** (``roles.py``), over the one
+  :class:`HfClient` seam (``client.py``) that works hosted or local.
+
+* **The supply chain** (``supply_chain.py``) makes pulling any of them safe by
+  default: pin + hash, safetensors not pickle, never trust remote code.
+"""
+
+from __future__ import annotations
+
+from .client import HF_ROUTER, HfClient, InferenceClientBackend, PipelineBackend
+from .roles import HfClassifierDetector, HfClassifierValidator
+from .supply_chain import (
+    ModelPin,
+    SupplyChainError,
+    SupplyChainPolicy,
+    assert_no_remote_code,
+    file_sha256,
+    safe_pipeline_kwargs,
+    verify_file_hash,
+    verify_model_source,
+)
+from .tools import (
+    Classify,
+    DetectObjects,
+    Embed,
+    ImageToText,
+    Summarize,
+    Transcribe,
+    Translate,
+    ZeroShotClassify,
+)
+
+__all__ = [
+    # client seam
+    "HfClient",
+    "HF_ROUTER",
+    "InferenceClientBackend",
+    "PipelineBackend",
+    # tools
+    "Transcribe",
+    "ImageToText",
+    "DetectObjects",
+    "Embed",
+    "Classify",
+    "ZeroShotClassify",
+    "Summarize",
+    "Translate",
+    # role wrappers
+    "HfClassifierDetector",
+    "HfClassifierValidator",
+    # supply chain
+    "ModelPin",
+    "SupplyChainPolicy",
+    "SupplyChainError",
+    "verify_model_source",
+    "assert_no_remote_code",
+    "safe_pipeline_kwargs",
+    "file_sha256",
+    "verify_file_hash",
+]

zu_huggingface/client.py

@@ -0,0 +1,187 @@
+"""The HuggingFace client seam — one task-method interface, three serving surfaces.
+
+Most HuggingFace models are *not* chat models: OCR, speech recognition, object
+detection, and embedding models each have their own typed input/output, so they
+enter Zu through the non-policy ports by their role (§8.5). This module is the
+thin seam the HuggingFace *tools* call, so the same tool works whether the model
+is served hosted (the Inference Providers router) or local (a transformers
+pipeline) — the integration is done once, here.
+
+``HfClient`` is the protocol the tools depend on. Two adapters implement it:
+
+* :class:`InferenceClientBackend` — wraps ``huggingface_hub.InferenceClient``
+  (hosted; the router or a dedicated Endpoint), egressing to the HF router.
+* :class:`PipelineBackend` — wraps ``transformers.pipeline`` (local; the
+  air-gapped / on-prem case), constructed only through the supply-chain guards
+  (§8.3): a pinned revision and ``trust_remote_code=False``.
+
+Both heavy SDKs are imported lazily, so installing ``zu-huggingface`` without
+the extras costs nothing and the tools are testable offline against a fake
+client. Credentials (``HF_TOKEN``) are resolved from the environment *inside*
+the backend, never placed in the model's context.
+"""
+
+from __future__ import annotations
+
+import os
+from typing import Any, Protocol, runtime_checkable
+
+from .supply_chain import ModelPin, SupplyChainPolicy, safe_pipeline_kwargs
+
+# The Inference Providers router — the hosted default, OpenAI-compatible for
+# chat at /v1 but task-native through the InferenceClient methods.
+HF_ROUTER = "router.huggingface.co"
+
+
+@runtime_checkable
+class HfClient(Protocol):
+    """The task methods the HuggingFace tools call. Inputs/outputs are plain
+    Python (bytes for media, str for text, list[dict] for structured) so the
+    tools own the translation to/from typed :class:`zu_core.content` Content."""
+
+    def transcribe(self, audio: bytes, model: str) -> str: ...
+    def image_to_text(self, image: bytes, model: str) -> str: ...
+    def object_detection(self, image: bytes, model: str) -> list[dict]: ...
+    def text_classification(self, text: str, model: str) -> list[dict]: ...
+    def zero_shot(self, text: str, labels: list[str], model: str) -> list[dict]: ...
+    def embed(self, text: str, model: str) -> list[float]: ...
+    def summarize(self, text: str, model: str) -> str: ...
+    def translate(self, text: str, model: str) -> str: ...
+
+
+def _scores(raw: Any) -> list[dict]:
+    """Normalise a classifier response to ``[{"label","score"}, …]`` sorted by
+    score desc — the shape every classification tool/detector reads."""
+    out: list[dict] = []
+    if isinstance(raw, dict) and "labels" in raw and "scores" in raw:  # zero-shot shape
+        out = [{"label": str(lbl), "score": float(sc)}
+               for lbl, sc in zip(raw["labels"], raw["scores"], strict=False)]
+    elif isinstance(raw, list):
+        for item in raw:
+            if isinstance(item, dict) and "label" in item:
+                out.append({"label": str(item["label"]), "score": float(item.get("score", 0.0))})
+    return sorted(out, key=lambda d: d["score"], reverse=True)
+
+
+class InferenceClientBackend:
+    """Hosted HuggingFace via ``huggingface_hub.InferenceClient`` (lazy import).
+
+    The same model id works through the serverless router or a dedicated
+    Endpoint; ``HF_TOKEN`` is read from the environment here.
+    """
+
+    egress_host = HF_ROUTER
+
+    def __init__(
+        self,
+        *,
+        provider: str = "hf-inference",
+        token_env: str = "HF_TOKEN",
+        client: Any = None,
+    ) -> None:
+        self._provider = provider
+        self._token_env = token_env
+        self._client = client  # injectable for tests
+
+    def _c(self) -> Any:
+        if self._client is None:
+            try:
+                from huggingface_hub import InferenceClient
+            except ImportError as e:  # pragma: no cover - exercised only without the extra
+                raise RuntimeError(
+                    "the hosted HuggingFace backend needs `huggingface_hub` "
+                    "(install zu-huggingface[hosted])"
+                ) from e
+            self._client = InferenceClient(provider=self._provider, api_key=os.environ.get(self._token_env))
+        return self._client
+
+    def transcribe(self, audio: bytes, model: str) -> str:
+        r = self._c().automatic_speech_recognition(audio, model=model)
+        return r if isinstance(r, str) else str(getattr(r, "text", r))
+
+    def image_to_text(self, image: bytes, model: str) -> str:
+        r = self._c().image_to_text(image, model=model)
+        return r if isinstance(r, str) else str(getattr(r, "generated_text", r))
+
+    def object_detection(self, image: bytes, model: str) -> list[dict]:
+        r = self._c().object_detection(image, model=model)
+        return [dict(item) for item in r]
+
+    def text_classification(self, text: str, model: str) -> list[dict]:
+        return _scores(self._c().text_classification(text, model=model))
+
+    def zero_shot(self, text: str, labels: list[str], model: str) -> list[dict]:
+        return _scores(self._c().zero_shot_classification(text, candidate_labels=labels, model=model))
+
+    def embed(self, text: str, model: str) -> list[float]:
+        r = self._c().feature_extraction(text, model=model)
+        return [float(x) for x in (r.tolist() if hasattr(r, "tolist") else r)]
+
+    def summarize(self, text: str, model: str) -> str:
+        r = self._c().summarization(text, model=model)
+        return r if isinstance(r, str) else str(getattr(r, "summary_text", r))
+
+    def translate(self, text: str, model: str) -> str:
+        r = self._c().translation(text, model=model)
+        return r if isinstance(r, str) else str(getattr(r, "translation_text", r))
+
+
+class PipelineBackend:
+    """Local HuggingFace via ``transformers.pipeline`` (lazy import).
+
+    The only option for air-gapped / on-prem. Every pipeline is built through
+    :func:`safe_pipeline_kwargs` — a pinned revision and ``trust_remote_code``
+    forced off — so the §8.3 supply-chain rules hold by construction. Pipelines
+    are cached per (task, model).
+    """
+
+    egress_host = ""  # local — no egress
+
+    def __init__(self, policy: SupplyChainPolicy | None = None) -> None:
+        self._policy = policy or SupplyChainPolicy()
+        self._cache: dict[tuple[str, str], Any] = {}
+
+    def _pipe(self, task: str, model: str) -> Any:
+        key = (task, model)
+        if key not in self._cache:
+            try:
+                from transformers import pipeline
+            except ImportError as e:  # pragma: no cover - exercised only without the extra
+                raise RuntimeError(
+                    "the local HuggingFace backend needs `transformers` "
+                    "(install zu-huggingface[local])"
+                ) from e
+            kwargs = safe_pipeline_kwargs(ModelPin(repo_id=model), self._policy)
+            self._cache[key] = pipeline(task, **kwargs)
+        return self._cache[key]
+
+    def transcribe(self, audio: bytes, model: str) -> str:
+        return str(self._pipe("automatic-speech-recognition", model)(audio)["text"])
+
+    def image_to_text(self, image: bytes, model: str) -> str:
+        r = self._pipe("image-to-text", model)(image)
+        return str(r[0]["generated_text"] if isinstance(r, list) else r["generated_text"])
+
+    def object_detection(self, image: bytes, model: str) -> list[dict]:
+        return [dict(item) for item in self._pipe("object-detection", model)(image)]
+
+    def text_classification(self, text: str, model: str) -> list[dict]:
+        return _scores(self._pipe("text-classification", model)(text))
+
+    def zero_shot(self, text: str, labels: list[str], model: str) -> list[dict]:
+        return _scores(self._pipe("zero-shot-classification", model)(text, candidate_labels=labels))
+
+    def embed(self, text: str, model: str) -> list[float]:
+        r = self._pipe("feature-extraction", model)(text)
+        # pipelines return [[token-vectors]]; mean-pool to one vector
+        vecs = r[0] if isinstance(r, list) else r
+        if vecs and isinstance(vecs[0], list):
+            cols = list(zip(*vecs, strict=False))
+            return [sum(c) / len(c) for c in cols]
+        return [float(x) for x in vecs]
+
+    def summarize(self, text: str, model: str) -> str:
+        return str(self._pipe("summarization", model)(text)[0]["summary_text"])
+
+    def translate(self, text: str, model: str) -> str:
+        return str(self._pipe("translation", model)(text)[0]["translation_text"])

zu_huggingface/roles.py

@@ -0,0 +1,139 @@
+"""HuggingFace models in the detector and validator roles (§8.5, §9.1).
+
+The port is the role, assigned per agent. A zero-shot or text-classification
+model that *gates control flow* is a **detector**; one that *checks the final
+result* is a **validator**. A trained classifier as a detector is cheaper,
+faster, and more reliable than asking an LLM the same yes/no question — the
+right-sized-model discipline the economics rest on (§9.1).
+
+These are configured per agent (a model + the labels that matter + a threshold),
+so they enter the registry *by reference in config* rather than as a zero-config
+entry point. Both reuse the same :class:`HfClient` seam as the tools.
+"""
+
+from __future__ import annotations
+
+from zu_core.contracts import Result
+from zu_core.ports import RunContext, Scope, Severity, Verdict
+
+from .client import HfClient
+
+_CONTENT_KEYS = ("html", "text", "content")
+
+
+def _text_of(obs: object) -> str:
+    """The text of an observation, concatenating the content keys (mirrors the
+    built-in detectors so they agree on "the content")."""
+    if isinstance(obs, dict):
+        parts = [v for k in _CONTENT_KEYS if isinstance(v := obs.get(k), str) and v]
+        return "\n".join(parts)
+    return ""
+
+
+class HfClassifierDetector:
+    """Escalate (or stop) when a HuggingFace classifier flags the observation.
+
+    Configure with a model and the labels that should trip control flow. With
+    ``candidate_labels`` set it runs zero-shot; without, it runs the model's own
+    text-classification head. The verdict severity is configurable (default
+    ESCALATE) — the deterministic gate, decided by the classifier, never the
+    policy.
+    """
+
+    scope = Scope.PER_OBSERVATION
+
+    def __init__(
+        self,
+        client: HfClient,
+        model: str,
+        *,
+        escalate_on: list[str],
+        candidate_labels: list[str] | None = None,
+        threshold: float = 0.5,
+        severity: Severity = Severity.ESCALATE,
+        name: str = "hf-classifier",
+    ) -> None:
+        self._client = client
+        self._model = model
+        self._escalate_on = {lbl.lower() for lbl in escalate_on}
+        self._candidate_labels = candidate_labels
+        self._threshold = threshold
+        self._severity = severity
+        self.name = name
+
+    def inspect(self, ctx: RunContext) -> Verdict | None:
+        text = _text_of(getattr(ctx, "observation", None))
+        if not text.strip():
+            return None
+        if self._candidate_labels is not None:
+            scored = self._client.zero_shot(text, self._candidate_labels, self._model)
+        else:
+            scored = self._client.text_classification(text, self._model)
+        if not scored:
+            return None
+        top = scored[0]
+        if top["label"].lower() in self._escalate_on and top["score"] >= self._threshold:
+            return Verdict(
+                severity=self._severity,
+                detector=self.name,
+                detail=f"{top['label']} ({top['score']:.2f})",
+            )
+        return None
+
+
+class HfClassifierValidator:
+    """Fail a result on finalise when a HuggingFace classifier flags its value.
+
+    The result's text is classified; if the top label is one of ``fail_on`` over
+    threshold, the validator returns a (default RETRY) verdict — e.g. a toxicity
+    or refusal classifier checking the answer before it ships.
+    """
+
+    def __init__(
+        self,
+        client: HfClient,
+        model: str,
+        *,
+        fail_on: list[str],
+        candidate_labels: list[str] | None = None,
+        threshold: float = 0.5,
+        severity: Severity = Severity.RETRY,
+        value_key: str | None = None,
+        name: str = "hf-classifier-check",
+    ) -> None:
+        self._client = client
+        self._model = model
+        self._fail_on = {lbl.lower() for lbl in fail_on}
+        self._candidate_labels = candidate_labels
+        self._threshold = threshold
+        self._severity = severity
+        self._value_key = value_key
+        self.name = name
+
+    def _result_text(self, result: Result) -> str:
+        if not isinstance(result.value, dict):
+            return ""
+        if self._value_key is not None:
+            v = result.value.get(self._value_key)
+            return v if isinstance(v, str) else ""
+        # join the string leaves of the value
+        return "\n".join(str(v) for v in result.value.values() if isinstance(v, str))
+
+    def check(self, result: Result, ctx: RunContext) -> Verdict | None:
+        text = self._result_text(result)
+        if not text.strip():
+            return None
+        if self._candidate_labels is not None:
+            scored = self._client.zero_shot(text, self._candidate_labels, self._model)
+        else:
+            scored = self._client.text_classification(text, self._model)
+        if not scored:
+            return None
+        top = scored[0]
+        if top["label"].lower() in self._fail_on and top["score"] >= self._threshold:
+            return Verdict(
+                severity=self._severity,
+                detector=self.name,
+                detail=f"{top['label']} ({top['score']:.2f})",
+            )
+        return None

zu_huggingface/supply_chain.py

@@ -0,0 +1,135 @@
+"""Model supply-chain guards (Engineering Design §8.3).
+
+Pulling a model from the Hub is a supply-chain surface under the same rules as
+any downloaded artifact. Two hazards matter:
+
+* **model code that runs on load** — the transformers "trust remote code" path
+  executes arbitrary code from the repo; and
+* **pickle-based checkpoints** — which execute on deserialisation.
+
+Both are the fetch-then-execute anti-pattern the project bans. So, by default:
+pin and hash-verify weights and configs; prefer safetensors and disallow pickle;
+never enable remote model code. (Serving inside the capability envelope is the
+SandboxBackend's job; this module is the *declaration and verification* half.)
+
+Everything here is pure and deterministic — it makes a decision about a model
+reference and a file list, with no network — so it is fully testable at $0 and
+is the gate the HuggingFace tools call before a local pipeline is constructed.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import re
+from pathlib import Path
+
+from pydantic import BaseModel, Field
+
+# A pinned revision is a full 40-hex git commit sha — a moving ref (a branch
+# name, or "main") is exactly what pinning forbids.
+_COMMIT_RE = re.compile(r"^[0-9a-f]{40}$")
+
+# Checkpoint extensions that deserialise via pickle (arbitrary code on load).
+_PICKLE_SUFFIXES = (".bin", ".pt", ".pth", ".ckpt", ".pkl", ".pickle")
+# The safe weights format — no code path on load.
+_SAFE_SUFFIXES = (".safetensors", ".json", ".txt", ".model", ".onnx")
+
+
+class SupplyChainError(ValueError):
+    """A model reference or file set violates the supply-chain policy."""
+
+
+class ModelPin(BaseModel):
+    """A pinned reference to a model on the Hub.
+
+    ``revision`` should be a full commit sha so the artifact can never change
+    under a fixed reference; ``expected_hashes`` maps a filename to its expected
+    sha256 for hash-verification of the downloaded files.
+    """
+
+    repo_id: str
+    revision: str | None = None
+    expected_hashes: dict[str, str] = Field(default_factory=dict)
+
+
+class SupplyChainPolicy(BaseModel):
+    """The default-deny policy. The safe configuration is the default — there is
+    nothing to turn *on* to be safe, only flags to relax for a reviewed case."""
+
+    allow_pickle: bool = False
+    allow_remote_code: bool = False
+    require_pinned_revision: bool = True
+
+
+def verify_model_source(
+    pin: ModelPin,
+    policy: SupplyChainPolicy | None = None,
+    *,
+    files: list[str] | None = None,
+) -> None:
+    """Raise :class:`SupplyChainError` if ``pin`` (and an optional ``files`` list)
+    violates ``policy``. A no-op (returns ``None``) when everything is allowed.
+
+    Checks, cheapest first: the revision is a pinned commit sha (unless relaxed);
+    no pickle-format weights appear in the file list (unless relaxed).
+    """
+    policy = policy or SupplyChainPolicy()
+
+    if policy.require_pinned_revision:
+        if not pin.revision or not _COMMIT_RE.match(pin.revision):
+            raise SupplyChainError(
+                f"{pin.repo_id}: revision must be a pinned 40-hex commit sha "
+                f"(got {pin.revision!r}); a moving ref like 'main' is forbidden"
+            )
+
+    if files and not policy.allow_pickle:
+        offending = sorted(f for f in files if f.lower().endswith(_PICKLE_SUFFIXES))
+        if offending:
+            raise SupplyChainError(
+                f"{pin.repo_id}: pickle-format checkpoints are disallowed "
+                f"(prefer safetensors): {offending}"
+            )
+
+
+def assert_no_remote_code(policy: SupplyChainPolicy | None = None) -> None:
+    """Guard the transformers ``trust_remote_code`` path: raise unless explicitly
+    relaxed. The HuggingFace tools call this before building a local pipeline."""
+    policy = policy or SupplyChainPolicy()
+    if policy.allow_remote_code:
+        raise SupplyChainError(
+            "remote model code is enabled (allow_remote_code=True) — this executes "
+            "arbitrary code from the model repo on load; it must be reviewed, not default"
+        )
+
+
+def safe_pipeline_kwargs(pin: ModelPin, policy: SupplyChainPolicy | None = None) -> dict:
+    """Keyword arguments for ``transformers.pipeline`` that enforce the policy:
+    a pinned revision and ``trust_remote_code=False`` (always — there is no safe
+    default for executing repo code)."""
+    policy = policy or SupplyChainPolicy()
+    assert_no_remote_code(policy)
+    verify_model_source(pin, policy)
+    kwargs: dict = {"model": pin.repo_id, "trust_remote_code": False}
+    if pin.revision:
+        kwargs["revision"] = pin.revision
+    return kwargs
+
+
+def file_sha256(path: str | Path) -> str:
+    """The sha256 of a file, streamed (so a multi-GB checkpoint never loads into
+    memory to be hashed)."""
+    h = hashlib.sha256()
+    with open(path, "rb") as fh:
+        for chunk in iter(lambda: fh.read(1 << 20), b""):
+            h.update(chunk)
+    return h.hexdigest()
+
+
+def verify_file_hash(path: str | Path, expected_sha256: str) -> None:
+    """Raise :class:`SupplyChainError` if the file's sha256 differs from
+    ``expected_sha256`` — hash-verification of a downloaded artifact (§8.3)."""
+    actual = file_sha256(path)
+    if actual != expected_sha256:
+        raise SupplyChainError(
+            f"{path}: sha256 mismatch — expected {expected_sha256}, got {actual}"
+        )

zu_huggingface/tools.py

@@ -0,0 +1,231 @@
+"""HuggingFace task models as typed Zu Tools (Engineering Design §8.5).
+
+Each tool wraps one HuggingFace task behind the standard Tool contract, with the
+typed multimodal :class:`~zu_core.content` Content (Text/Image/Audio) as the
+currency in and out — which is what lets a non-chat model slot into the loop as
+cleanly as a chat one. The same tool works hosted or local because it depends
+only on the :class:`HfClient` seam (``client.py``).
+
+The port is the *role*, assigned per agent (§4.5): these are Tools — verbs the
+policy performs (transcribe, read an image, detect, embed, summarise,
+translate). A classifier wanting to *gate control flow* or *check a result*
+becomes a detector/validator instead — see ``roles.py``.
+
+The envelope is derived from the backend: a hosted client egresses to the HF
+router (CAP_NET + that host); a local pipeline reaches nothing. Media is passed
+as base64 (``data_b64``) or a local ``path`` — the realistic shape when the
+policy carries bytes from a prior observation.
+"""
+
+from __future__ import annotations
+
+import base64
+from pathlib import Path
+from typing import Any
+
+from zu_core.content import Audio, Image, Text
+from zu_core.ports import CAP_NET
+
+from .client import HfClient, InferenceClientBackend
+
+
+def _decode_media(data_b64: str | None, path: str | None) -> bytes:
+    if data_b64:
+        return base64.b64decode(data_b64)
+    if path:
+        return Path(path).read_bytes()
+    raise ValueError("provide media as 'data_b64' (base64) or a local 'path'")
+
+
+class _HfTool:
+    """Shared base: hold a model id + client, and derive the capability envelope
+    from the backend (hosted ⇒ net+router; local ⇒ nothing)."""
+
+    tier = 1  # a specialised model the policy calls — cheap, not an escalation
+
+    def __init__(self, model: str, client: HfClient | None = None) -> None:
+        self.model = model
+        self._client = client
+        backend = client if client is not None else InferenceClientBackend()
+        host = getattr(backend, "egress_host", "")
+        self.capabilities = frozenset({CAP_NET}) if host else frozenset()
+        self.egress = frozenset({host}) if host else frozenset()
+        self._backend = backend
+
+    def _c(self) -> HfClient:
+        return self._client if self._client is not None else self._backend
+
+
+class Transcribe(_HfTool):
+    """ASR — audio → text (a sense). Role: Tool (§8.5 Audio)."""
+
+    name = "hf_transcribe"
+    prompt_fragment = "hf_transcribe(data_b64|path): transcribe speech audio to text."
+    schema = {
+        "name": "hf_transcribe",
+        "description": "Transcribe speech audio to text via a HuggingFace ASR model.",
+        "parameters": {
+            "type": "object",
+            "properties": {
+                "data_b64": {"type": "string", "description": "base64-encoded audio"},
+                "path": {"type": "string", "description": "local audio file path"},
+            },
+        },
+    }
+
+    async def __call__(self, ctx: Any, data_b64: str | None = None, path: str | None = None) -> dict:
+        audio = _decode_media(data_b64, path)
+        _ = Audio(data=audio)  # typed currency in (recorded shape)
+        text = self._c().transcribe(audio, self.model)
+        return {"text": text, "model": self.model}
+
+
+class ImageToText(_HfTool):
+    """Image-to-text / OCR — image → text (a sense). Role: Tool (§8.5 CV/Multimodal)."""
+
+    name = "hf_image_to_text"
+    prompt_fragment = "hf_image_to_text(data_b64|path): read/describe an image as text (OCR or caption)."
+    schema = {
+        "name": "hf_image_to_text",
+        "description": "Extract or describe the text/content of an image via a HuggingFace model.",
+        "parameters": {
+            "type": "object",
+            "properties": {
+                "data_b64": {"type": "string", "description": "base64-encoded image"},
+                "path": {"type": "string", "description": "local image file path"},
+            },
+        },
+    }
+
+    async def __call__(self, ctx: Any, data_b64: str | None = None, path: str | None = None) -> dict:
+        image = _decode_media(data_b64, path)
+        _ = Image(data=image)
+        text = self._c().image_to_text(image, self.model)
+        return {"text": text, "model": self.model}
+
+
+class DetectObjects(_HfTool):
+    """Object detection — image → boxes. Role: Tool (or detector). (§8.5 CV)."""
+
+    name = "hf_detect"
+    prompt_fragment = "hf_detect(data_b64|path): find objects in an image (labelled boxes)."
+    schema = {
+        "name": "hf_detect",
+        "description": "Detect objects in an image via a HuggingFace model; returns labelled boxes.",
+        "parameters": {
+            "type": "object",
+            "properties": {
+                "data_b64": {"type": "string", "description": "base64-encoded image"},
+                "path": {"type": "string", "description": "local image file path"},
+            },
+        },
+    }
+
+    async def __call__(self, ctx: Any, data_b64: str | None = None, path: str | None = None) -> dict:
+        image = _decode_media(data_b64, path)
+        objects = self._c().object_detection(image, self.model)
+        return {"objects": objects, "count": len(objects), "model": self.model}
+
+
+class Embed(_HfTool):
+    """Feature extraction — text → vector. Role: retrieval Tool / grounding (§8.5 NLP)."""
+
+    name = "hf_embed"
+    prompt_fragment = "hf_embed(text): embed text into a vector for search/similarity."
+    schema = {
+        "name": "hf_embed",
+        "description": "Embed text into a dense vector via a HuggingFace embedding model.",
+        "parameters": {
+            "type": "object",
+            "properties": {"text": {"type": "string"}},
+            "required": ["text"],
+        },
+    }
+
+    async def __call__(self, ctx: Any, text: str) -> dict:
+        vec = self._c().embed(text, self.model)
+        return {"embedding": vec, "dim": len(vec), "model": self.model}
+
+
+class Classify(_HfTool):
+    """Text classification — text → labels. Role: Tool (or detector/router) (§8.5 NLP)."""
+
+    name = "hf_classify"
+    prompt_fragment = "hf_classify(text): classify/score text into the model's labels."
+    schema = {
+        "name": "hf_classify",
+        "description": "Classify text via a HuggingFace text-classification model.",
+        "parameters": {
+            "type": "object",
+            "properties": {"text": {"type": "string"}},
+            "required": ["text"],
+        },
+    }
+
+    async def __call__(self, ctx: Any, text: str) -> dict:
+        labels = self._c().text_classification(text, self.model)
+        return {"labels": labels, "top": labels[0]["label"] if labels else None, "model": self.model}
+
+
+class ZeroShotClassify(_HfTool):
+    """Zero-shot classification — text + candidate labels → scores (§8.5 NLP)."""
+
+    name = "hf_zero_shot"
+    prompt_fragment = "hf_zero_shot(text, labels): score text against candidate labels you supply."
+    schema = {
+        "name": "hf_zero_shot",
+        "description": "Zero-shot classify text against candidate labels via a HuggingFace model.",
+        "parameters": {
+            "type": "object",
+            "properties": {
+                "text": {"type": "string"},
+                "labels": {"type": "array", "items": {"type": "string"}},
+            },
+            "required": ["text", "labels"],
+        },
+    }
+
+    async def __call__(self, ctx: Any, text: str, labels: list[str]) -> dict:
+        scored = self._c().zero_shot(text, labels, self.model)
+        return {"labels": scored, "top": scored[0]["label"] if scored else None, "model": self.model}
+
+
+class Summarize(_HfTool):
+    """Summarization — text → text (§8.5 NLP)."""
+
+    name = "hf_summarize"
+    prompt_fragment = "hf_summarize(text): summarise a long text."
+    schema = {
+        "name": "hf_summarize",
+        "description": "Summarise text via a HuggingFace summarization model.",
+        "parameters": {
+            "type": "object",
+            "properties": {"text": {"type": "string"}},
+            "required": ["text"],
+        },
+    }
+
+    async def __call__(self, ctx: Any, text: str) -> dict:
+        out = self._c().summarize(text, self.model)
+        _ = Text(text=out)
+        return {"text": out, "model": self.model}
+
+
+class Translate(_HfTool):
+    """Translation — text → text (§8.5 NLP)."""
+
+    name = "hf_translate"
+    prompt_fragment = "hf_translate(text): translate text (model is pinned to a language pair)."
+    schema = {
+        "name": "hf_translate",
+        "description": "Translate text via a HuggingFace translation model.",
+        "parameters": {
+            "type": "object",
+            "properties": {"text": {"type": "string"}},
+            "required": ["text"],
+        },
+    }
+
+    async def __call__(self, ctx: Any, text: str) -> dict:
+        out = self._c().translate(text, self.model)
+        return {"text": out, "model": self.model}

zu_huggingface-0.2.2.dist-info/METADATA

@@ -0,0 +1,119 @@
+Metadata-Version: 2.4
+Name: zu-huggingface
+Version: 0.2.2
+Summary: Zu HuggingFace adapter: task models as typed tools/detectors/validators, behind the supply-chain guards
+Project-URL: Homepage, https://github.com/k3-mt/zu
+Project-URL: Repository, https://github.com/k3-mt/zu
+License-Expression: Apache-2.0
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: zu-core==0.2.1
+Provides-Extra: hosted
+Requires-Dist: huggingface-hub>=0.24; extra == 'hosted'
+Provides-Extra: local
+Requires-Dist: pillow; extra == 'local'
+Requires-Dist: transformers>=4.40; extra == 'local'
+Description-Content-Type: text/markdown
+
+# zu-huggingface
+
+HuggingFace models behind Zu's typed ports. HuggingFace is not a model — it is
+the largest hub of open models across every modality — so "supporting it" means
+three different things, and this package draws the line cleanly
+(Engineering Design §8.3–8.5).
+
+## Chat / vision-language models as the policy — *no code here*
+
+A chat or vision-language model that is the **brain** speaks the OpenAI chat API
+on all three HuggingFace serving surfaces (the router's `/v1`, a dedicated
+Endpoint's `/v1`, or a local vLLM server). So a HuggingFace model as the policy
+is the existing `openai-compatible` provider pointed at a HuggingFace base URL —
+the OpenRouter story exactly, no new adapter:
+
+```yaml
+# agent.yaml — a HuggingFace multimodal model as the policy
+model:    meta-llama/Llama-Vision-...        # any chat / VLM id on the Hub
+provider: openai-compatible
+options:
+  base_url: https://router.huggingface.co/v1  # or an Endpoint, or local vLLM
+  api_key_env: HF_TOKEN
+```
+
+## Task models as tools, detectors, validators — this package
+
+Most HuggingFace models are **not** chat models (OCR, ASR, detection,
+embeddings, classification, …), so they enter through the non-policy ports by
+their **role** (the port is the role, assigned per agent — §4.5):
+
+| Role | Class | Task |
+|------|-------|------|
+| Tool | `Transcribe` (`hf_transcribe`) | speech → text (ASR) |
+| Tool | `ImageToText` (`hf_image_to_text`) | image → text (OCR / caption) |
+| Tool | `DetectObjects` (`hf_detect`) | image → labelled boxes |
+| Tool | `Embed` (`hf_embed`) | text → vector (retrieval / grounding) |
+| Tool | `Classify` (`hf_classify`) | text → labels |
+| Tool | `ZeroShotClassify` (`hf_zero_shot`) | text + labels → scores |
+| Tool | `Summarize` (`hf_summarize`) | text → text |
+| Tool | `Translate` (`hf_translate`) | text → text |
+| Detector | `HfClassifierDetector` | classify an observation → ESCALATE/stop |
+| Validator | `HfClassifierValidator` | classify the result → fail/RETRY |
+
+Each is **parameterised by a model id** (and the role wrappers by the labels
+that matter), so they are wired *by reference in config* per agent rather than
+as zero-config entry points:
+
+```yaml
+tools:
+  - ref: zu_huggingface.tools:Transcribe
+    args: { model: openai/whisper-large-v3 }
+  - ref: zu_huggingface.tools:Embed
+    args: { model: BAAI/bge-large-en-v1.5 }
+detectors:
+  - ref: zu_huggingface.roles:HfClassifierDetector
+    args: { model: facebook/bart-large-mnli, candidate_labels: ["safe","unsafe"], escalate_on: ["unsafe"] }
+```
+
+The typed multimodal `Content` (`Text`/`Image`/`Audio`) from `zu_core.content`
+is the currency in and out — which is what lets a non-chat model slot into the
+loop as cleanly as a chat one.
+
+### Hosted vs local — one seam
+
+Every tool depends only on the `HfClient` seam, so the same tool works:
+
+- **Hosted** — `InferenceClientBackend` wraps `huggingface_hub.InferenceClient`
+  (the serverless router or a dedicated Endpoint). Egresses to
+  `router.huggingface.co`; `HF_TOKEN` is read from the environment inside the
+  backend. `pip install 'zu-huggingface[hosted]'`.
+- **Local** — `PipelineBackend` wraps `transformers.pipeline` for the
+  air-gapped / on-prem case. Reaches no network. Every pipeline is built through
+  the supply-chain guards. `pip install 'zu-huggingface[local]'` (plus a
+  backend such as `torch`).
+
+## The supply chain — safe by default (§8.3)
+
+Pulling a model from the Hub is a supply-chain surface. `supply_chain.py`
+enforces, by default:
+
+- **Pin + hash.** A `ModelPin` should carry a full commit-sha `revision`;
+  `verify_file_hash` checks a downloaded file's sha256.
+- **safetensors, not pickle.** `verify_model_source` rejects `.bin`/`.pt`/`.ckpt`
+  checkpoints (which execute on deserialisation) unless explicitly allowed.
+- **No remote code.** `safe_pipeline_kwargs` forces `trust_remote_code=False`;
+  `assert_no_remote_code` raises if it is relaxed.
+
+The safe configuration is the default — there is nothing to turn *on* to be
+safe, only flags a reviewed case may relax.
+
+## Tests
+
+Offline, no network, no model download: the tools and role wrappers are
+exercised against a fake `HfClient`, and the supply-chain guards are pure.
+`uv run pytest packages/zu-huggingface`.

zu_huggingface-0.2.2.dist-info/RECORD

@@ -0,0 +1,8 @@
+zu_huggingface/__init__.py,sha256=YJDo9GnPPnyZIirzuuP3fBKUppBTJMXfp27um7IQCak,2261
+zu_huggingface/client.py,sha256=JakMapgYgzKntkQUjb1dEhQIMD3j21bIlK2VvcNOZ_A,8573
+zu_huggingface/roles.py,sha256=yAqM7ItZibCLka9ojLbmdGbnHn9wVGbY7AwZd_hCIgM,5160
+zu_huggingface/supply_chain.py,sha256=yTRxBDaCLlWYfUpz5JKcqUSuUUGyNq6sriv3SoLiMRI,5358
+zu_huggingface/tools.py,sha256=vN1LWcsj8Atmfic-SKh84DwE0KURjK7jVJVMJ2-RSIM,8889
+zu_huggingface-0.2.2.dist-info/METADATA,sha256=jIUj7y_udLid09vW5Gmq7Q5ao154tWy2iqzZL1G26P0,5284
+zu_huggingface-0.2.2.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+zu_huggingface-0.2.2.dist-info/RECORD,,

zu_huggingface-0.2.2.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.30.1
+Root-Is-Purelib: true
+Tag: py3-none-any