tensorplate-python 0.1.3__py3-none-any.whl

tensorplate/__init__.py

@@ -0,0 +1,71 @@
+"""TensorPlate Python SDK.
+
+Client-side SDK for calling already-deployed TensorPlate detection and
+vision serving models over the v0.1 ``/infer`` HTTP envelope. The public
+surface is re-exported here; see the individual module docstrings for
+details.
+"""
+
+from __future__ import annotations
+
+from importlib.metadata import PackageNotFoundError, version
+
+from tensorplate.client import (
+    LOOPBACK_DEFAULT,
+    ResolvedEndpoint,
+    canonicalize_serving_url,
+    resolve_serving_url,
+)
+from tensorplate.conventions import YOLO_V8_SINGLE_OUTPUT, detections
+from tensorplate.errors import (
+    EndpointResolutionError,
+    ErrorCode,
+    ProtocolError,
+    RequestTimeoutError,
+    ServingError,
+    TensorPlateError,
+    TransportError,
+    UnsupportedSchemaVersionError,
+)
+from tensorplate.postprocess import Detection, decode_detections
+from tensorplate.preprocess import LetterboxTransform, PreprocessConfig, preprocess
+from tensorplate.serving import HealthSnapshot, InferResult, ServingClient, Timing
+from tensorplate.tensors import DType, Layout, TensorInput, TensorOutput
+from tensorplate.vision import VisionClient
+
+try:
+    __version__ = version("tensorplate-python")
+except PackageNotFoundError:  # pragma: no cover - only hit outside an installed package
+    __version__ = "0.0.0+unknown"
+
+__all__ = [
+    "LOOPBACK_DEFAULT",
+    "YOLO_V8_SINGLE_OUTPUT",
+    "DType",
+    "Detection",
+    "EndpointResolutionError",
+    "ErrorCode",
+    "HealthSnapshot",
+    "InferResult",
+    "Layout",
+    "LetterboxTransform",
+    "PreprocessConfig",
+    "ProtocolError",
+    "RequestTimeoutError",
+    "ResolvedEndpoint",
+    "ServingClient",
+    "ServingError",
+    "TensorInput",
+    "TensorOutput",
+    "TensorPlateError",
+    "Timing",
+    "TransportError",
+    "UnsupportedSchemaVersionError",
+    "VisionClient",
+    "__version__",
+    "canonicalize_serving_url",
+    "decode_detections",
+    "detections",
+    "preprocess",
+    "resolve_serving_url",
+]

tensorplate/client.py

@@ -0,0 +1,278 @@
+"""Serving endpoint resolution and the low-level HTTP transport.
+
+Resolution mirrors ``tensorplate infer`` so the SDK reaches the same
+worker the CLI would: an explicit URL wins, then the active CLI profile's
+``serving_url``, then a read-only agent-status discovery, then the
+loopback default. URL canonicalization matches the CLI's exactly. The
+HTTP transport is hand-rolled over the standard library so the core SDK
+has no third-party dependency.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import socket
+import urllib.error
+import urllib.request
+from dataclasses import dataclass
+from pathlib import Path
+
+from tensorplate.errors import (
+    EndpointResolutionError,
+    RequestTimeoutError,
+    TransportError,
+)
+
+#: Loopback serving endpoint used when nothing else resolves. Mirrors the
+#: CLI's hard-coded v0.1 default.
+LOOPBACK_DEFAULT = "http://127.0.0.1:18080"
+
+#: Default local agent control socket. Mirrors the CLI/packaging default.
+DEFAULT_AGENT_SOCKET = "/var/run/tensorplate/agent.sock"
+
+#: Environment variable naming the CLI config file. Mirrors the CLI's
+#: discovery: explicit path, then this variable, then built-in defaults —
+#: no arbitrary filesystem search.
+CLI_CONFIG_ENV = "TENSORPLATE_CLI_CONFIG"
+
+#: Default request timeout in seconds.
+DEFAULT_TIMEOUT_S = 30.0
+
+
+@dataclass(frozen=True)
+class ResolvedEndpoint:
+    """A canonicalized serving endpoint and how it was resolved."""
+
+    url: str
+    host: str
+    port: int
+    path: str
+    source: str
+
+    @property
+    def origin(self) -> str:
+        """The ``http://host:port`` origin, without the inference path."""
+        return f"http://{self.host}:{self.port}"
+
+
+def canonicalize_serving_url(value: str, source: str) -> ResolvedEndpoint:
+    """Canonicalize a serving URL exactly as ``tensorplate infer`` does.
+
+    A bare ``http://host:port`` gets the ``/infer`` path appended; a full
+    URL with a path keeps that path. Only ``http://`` is accepted (v0.1
+    serving is loopback HTTP).
+    """
+    if not value.startswith("http://"):
+        raise EndpointResolutionError(
+            f"serving url {value!r} must start with 'http://' (v0.1 serving is loopback http)"
+        )
+    rest = value[len("http://") :]
+    authority, separator, tail = rest.partition("/")
+    raw_path = (tail or "infer") if separator else "infer"
+    if ":" in authority:
+        host, _, port_text = authority.rpartition(":")
+        try:
+            port = int(port_text)
+        except ValueError:
+            raise EndpointResolutionError(f"serving url {value!r} has a non-numeric port") from None
+    else:
+        host, port = authority, 80
+    if not host:
+        raise EndpointResolutionError(f"serving url {value!r} has an empty host")
+    if not 0 <= port <= 65535:
+        raise EndpointResolutionError(f"serving url {value!r} has an out-of-range port: {port}")
+    path = raw_path if raw_path.startswith("/") else f"/{raw_path}"
+    return ResolvedEndpoint(
+        url=f"http://{host}:{port}{path}", host=host, port=port, path=path, source=source
+    )
+
+
+def http_request(
+    method: str,
+    url: str,
+    *,
+    body: bytes | None = None,
+    headers: dict[str, str] | None = None,
+    timeout: float = DEFAULT_TIMEOUT_S,
+) -> tuple[int, bytes]:
+    """Perform a single HTTP request, returning ``(status_code, body)``.
+
+    Non-2xx responses are returned (not raised) so callers can read a
+    typed failure envelope or a ``/health`` degraded body. Only genuine
+    transport failures raise :class:`TransportError` /
+    :class:`RequestTimeoutError`.
+    """
+    request = urllib.request.Request(url, data=body, method=method)
+    request.add_header("Accept", "application/json")
+    if body is not None:
+        request.add_header("Content-Type", "application/json")
+    for key, value in (headers or {}).items():
+        request.add_header(key, value)
+    try:
+        with urllib.request.urlopen(request, timeout=timeout) as response:
+            data: bytes = response.read()
+            return int(response.status), data
+    except urllib.error.HTTPError as exc:
+        return int(exc.code), exc.read()
+    except TimeoutError as exc:
+        raise RequestTimeoutError(f"request to {url!r} timed out after {timeout}s") from exc
+    except urllib.error.URLError as exc:
+        if isinstance(exc.reason, TimeoutError):
+            raise RequestTimeoutError(f"request to {url!r} timed out after {timeout}s") from exc
+        raise TransportError(f"failed to reach {url!r}: {exc.reason}") from exc
+    except OSError as exc:
+        raise TransportError(f"failed to reach {url!r}: {exc}") from exc
+
+
+@dataclass(frozen=True)
+class _AgentTransport:
+    kind: str  # "unix" | "tcp"
+    socket_path: str | None = None
+    host: str | None = None
+    port: int | None = None
+
+
+def resolve_serving_url(
+    explicit: str | None = None,
+    *,
+    profile: str | None = None,
+    config_path: str | None = None,
+    timeout: float = DEFAULT_TIMEOUT_S,
+    discover: bool = True,
+) -> ResolvedEndpoint:
+    """Resolve the serving endpoint with CLI-parity precedence.
+
+    Order: explicit URL, then the chosen CLI profile's ``serving_url``,
+    then read-only agent-status discovery, then the loopback default. When
+    ``discover`` is false the agent tier is skipped. Discovery is
+    best-effort: an unreachable agent falls through to the loopback
+    default rather than raising.
+    """
+    if explicit is not None:
+        return canonicalize_serving_url(explicit, "explicit")
+    config = _load_cli_config(config_path)
+    serving_url, transport = _select_profile(config, profile)
+    if serving_url is not None:
+        return canonicalize_serving_url(serving_url, "profile")
+    if discover and transport is not None:
+        discovered = _discover_via_agent(transport, timeout)
+        if discovered is not None:
+            return canonicalize_serving_url(discovered, "agent-discovered")
+    return canonicalize_serving_url(LOOPBACK_DEFAULT, "loopback")
+
+
+def _load_cli_config(config_path: str | None) -> dict[str, object]:
+    path: Path | None = None
+    if config_path is not None:
+        path = Path(config_path)
+    else:
+        env_path = os.environ.get(CLI_CONFIG_ENV)
+        if env_path:
+            path = Path(env_path)
+    if path is None:
+        return {}
+    try:
+        text = path.read_text(encoding="utf-8")
+    except OSError as exc:
+        raise EndpointResolutionError(f"failed to read CLI config {str(path)!r}: {exc}") from exc
+    try:
+        parsed = json.loads(text)
+    except ValueError as exc:
+        raise EndpointResolutionError(f"CLI config {str(path)!r} is not valid JSON: {exc}") from exc
+    if not isinstance(parsed, dict):
+        raise EndpointResolutionError(f"CLI config {str(path)!r} must be a JSON object")
+    return parsed
+
+
+def _select_profile(
+    config: dict[str, object], profile: str | None
+) -> tuple[str | None, _AgentTransport | None]:
+    profiles_obj = config.get("profiles")
+    profiles = profiles_obj if isinstance(profiles_obj, dict) else {}
+    default_obj = config.get("default_profile")
+    default_name = default_obj if isinstance(default_obj, str) else None
+    name = profile or default_name or "local"
+    spec = profiles.get(name)
+    if not isinstance(spec, dict):
+        if name == "local":
+            return None, _AgentTransport(kind="unix", socket_path=DEFAULT_AGENT_SOCKET)
+        raise EndpointResolutionError(f"profile {name!r} is not declared in the CLI config")
+    serving_obj = spec.get("serving_url")
+    serving_url = serving_obj if isinstance(serving_obj, str) else None
+    return serving_url, _transport_for_spec(spec)
+
+
+def _transport_for_spec(spec: dict[str, object]) -> _AgentTransport | None:
+    mode = spec.get("mode")
+    if mode == "url":
+        agent_url = spec.get("agent_url")
+        if not isinstance(agent_url, str) or ":" not in agent_url:
+            return None
+        host, _, port_text = agent_url.rpartition(":")
+        try:
+            port = int(port_text)
+        except ValueError:
+            return None
+        if not host:
+            return None
+        return _AgentTransport(kind="tcp", host=host, port=port)
+    if mode in (None, "local"):
+        socket_obj = spec.get("socket_path")
+        socket_path = socket_obj if isinstance(socket_obj, str) else DEFAULT_AGENT_SOCKET
+        return _AgentTransport(kind="unix", socket_path=socket_path)
+    # Reserved modes (ssh_tunnel/overlay/relay): the SDK does not attempt
+    # discovery against them, mirroring the CLI's "unsupported" stance.
+    return None
+
+
+def _discover_via_agent(transport: _AgentTransport, timeout: float) -> str | None:
+    """Query the agent's read-only ``status`` op for the active serving URL.
+
+    Best-effort: any transport, decode, or shape problem returns ``None``
+    so resolution falls through to the loopback default.
+    """
+    try:
+        raw = _agent_status_roundtrip(transport, timeout)
+    except OSError:
+        return None
+    try:
+        parsed = json.loads(raw)
+    except (ValueError, UnicodeDecodeError):
+        return None
+    if not isinstance(parsed, dict) or parsed.get("status") != "ok":
+        return None
+    agent_status = parsed.get("agent_status")
+    if not isinstance(agent_status, dict):
+        return None
+    active = agent_status.get("active")
+    if not isinstance(active, dict):
+        return None
+    serving_url = active.get("serving_url")
+    return serving_url if isinstance(serving_url, str) and serving_url else None
+
+
+def _agent_status_roundtrip(transport: _AgentTransport, timeout: float) -> bytes:
+    request = json.dumps({"schema_version": "0.1", "op": "status"}).encode("utf-8") + b"\n"
+    if transport.kind == "unix":
+        path = transport.socket_path
+        if path is None or not hasattr(socket, "AF_UNIX"):
+            raise OSError("unix-socket agent transport is unavailable")
+        sock = socket.socket(socket.AF_UNIX, socket.SOCK_STREAM)
+        sock.settimeout(timeout)
+        sock.connect(path)
+    else:
+        if transport.host is None or transport.port is None:
+            raise OSError("tcp agent transport is missing host/port")
+        sock = socket.create_connection((transport.host, transport.port), timeout=timeout)
+    chunks: list[bytes] = []
+    with sock:
+        sock.sendall(request)
+        while True:
+            chunk = sock.recv(65536)
+            if not chunk:
+                break
+            chunks.append(chunk)
+            if b"\n" in chunk:
+                break
+    return b"".join(chunks)

tensorplate/conventions.py

@@ -0,0 +1,29 @@
+"""Detector output-decoding conventions and supported output contracts.
+
+These names and identifiers are pure constants (no numpy) so the core
+package imports without the optional vision dependencies.
+"""
+
+from __future__ import annotations
+
+
+class detections:
+    """Semantic-tag names for opportunistic detector-output decode.
+
+    A serving worker that tags its output tensors with these names lets
+    the SDK select the boxes/scores/classes tensors without the caller
+    supplying explicit output-name mapping. Tag emission is best-effort;
+    explicit mapping remains the primary, documented path.
+    """
+
+    boxes = "detections.boxes"
+    scores = "detections.scores"
+    classes = "detections.classes"
+
+
+#: Supported built-in detector output contract: a single tensor shaped
+#: ``[1, 4 + C, N]`` (YOLOv8-style; 4 box coords + C class scores over N
+#: anchors), or its transpose ``[1, N, 4 + C]`` when the caller declares
+#: it. Other heads (YOLOv5 objectness, exporter-side NMS, masks,
+#: keypoints) remain application-side postprocessing in v0.1.3.
+YOLO_V8_SINGLE_OUTPUT = "yolo_v8_single_output"

tensorplate/errors.py

@@ -0,0 +1,87 @@
+"""Typed exceptions and error codes raised by the TensorPlate SDK."""
+
+from __future__ import annotations
+
+from enum import Enum
+
+
+class ErrorCode(str, Enum):
+    """Stable serving error codes shared with the runtime, agent, and CLI.
+
+    Mirrors the ``code`` enum in the v0.1 serving and error schemas. The
+    string values are the wire form; the numeric C++ enum is not part of
+    the protocol.
+    """
+
+    CONFIG_INVALID = "config_invalid"
+    LOAD_FAILED = "load_failed"
+    NOT_READY = "not_ready"
+    SHAPE_MISMATCH = "shape_mismatch"
+    UNSUPPORTED = "unsupported"
+    OOM_ERROR = "oom_error"
+    TIMEOUT = "timeout"
+    INFERENCE_FAILED = "inference_failed"
+    INTERNAL = "internal"
+
+
+class TensorPlateError(Exception):
+    """Base class for every error raised by the TensorPlate SDK.
+
+    Transport, protocol, and serving-failure subtypes derive from this
+    base so callers can catch the entire SDK error surface with a single
+    ``except`` clause.
+    """
+
+
+class EndpointResolutionError(TensorPlateError):
+    """Raised when the serving endpoint cannot be resolved or canonicalized."""
+
+
+class TransportError(TensorPlateError):
+    """Raised when the serving endpoint cannot be reached or the HTTP exchange fails."""
+
+
+class RequestTimeoutError(TransportError):
+    """Raised when a request to the serving endpoint exceeds its timeout."""
+
+
+class ProtocolError(TensorPlateError):
+    """Raised when a response is not valid JSON or violates the serving envelope."""
+
+
+class UnsupportedSchemaVersionError(ProtocolError):
+    """Raised when a response declares a ``schema_version`` the SDK does not support."""
+
+    def __init__(self, received: str | None, supported: str) -> None:
+        self.received = received
+        self.supported = supported
+        got = received if received is not None else "<missing>"
+        super().__init__(
+            f"unsupported serving schema_version {got!r}; this SDK supports {supported!r}"
+        )
+
+
+class ServingError(TensorPlateError):
+    """Raised when the serving worker returns a typed ``failure`` envelope.
+
+    Carries the wire ``code``, human-readable ``message``, optional
+    ``context``, and the ``request_id`` the worker echoed so failures can
+    be correlated with serving logs.
+    """
+
+    def __init__(
+        self,
+        code: ErrorCode,
+        message: str,
+        *,
+        context: str | None = None,
+        request_id: str | None = None,
+    ) -> None:
+        self.code = code
+        self.message = message
+        self.context = context
+        self.request_id = request_id
+        detail = f"[{code.value}] {message}"
+        if context:
+            detail = f"{detail} (context: {context})"
+        super().__init__(detail)

tensorplate/postprocess.py

@@ -0,0 +1,142 @@
+"""YOLO-style detector output decoding, NMS, and the ``Detection`` type.
+
+``Detection`` and the module's imports are numpy-free so the core package
+imports without the vision extras; the decode/NMS routines import numpy
+lazily.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+from dataclasses import dataclass
+from typing import TYPE_CHECKING
+
+from tensorplate.conventions import YOLO_V8_SINGLE_OUTPUT
+from tensorplate.errors import ProtocolError
+from tensorplate.tensors import TensorOutput
+
+if TYPE_CHECKING:
+    import numpy as np
+
+    from tensorplate.preprocess import LetterboxTransform
+
+
+@dataclass(frozen=True)
+class Detection:
+    """A single object detection in source-image pixel space."""
+
+    class_id: int
+    score: float
+    box: tuple[float, float, float, float]  # (x1, y1, x2, y2)
+    label: str | None = None
+
+
+def decode_detections(
+    output: TensorOutput,
+    transform: LetterboxTransform,
+    *,
+    score_threshold: float = 0.25,
+    nms_threshold: float = 0.45,
+    labels: Sequence[str] | None = None,
+    transposed: bool = False,
+    contract: str = YOLO_V8_SINGLE_OUTPUT,
+) -> list[Detection]:
+    """Decode a YOLOv8-style single-output tensor into source-pixel detections.
+
+    Expects ``[1, 4 + C, N]`` (or ``[1, N, 4 + C]`` when ``transposed``): 4
+    box coordinates (center-x, center-y, width, height in model-input
+    pixels) followed by C per-class scores. Applies score thresholding and
+    class-aware NMS, then maps boxes back to source pixels via ``transform``.
+    """
+    if contract != YOLO_V8_SINGLE_OUTPUT:
+        raise ValueError(
+            f"unsupported output contract {contract!r}; only {YOLO_V8_SINGLE_OUTPUT!r} is built in"
+        )
+    import numpy as np
+
+    array = output.to_numpy().astype("float32")
+    if array.ndim != 3 or array.shape[0] != 1:
+        raise ProtocolError(
+            f"detector output must be [1, *, *] for {contract!r}, got shape {tuple(array.shape)}"
+        )
+    if _looks_like_wrong_layout(array, transposed):
+        expected = "[1, N, 4 + C]" if transposed else "[1, 4 + C, N]"
+        hint = "remove transposed=True" if transposed else "pass transposed=True"
+        raise ProtocolError(
+            f"detector output shape {tuple(array.shape)} does not match declared layout "
+            f"{expected}; {hint} if the tensor uses the opposite layout"
+        )
+    grid = array[0].T if transposed else array[0]
+    if grid.shape[0] < 5:
+        raise ProtocolError(
+            f"detector output has {int(grid.shape[0])} channels; need 4 box + >=1 class score "
+            "(is the layout transposed? pass transposed=True)"
+        )
+
+    boxes = grid[:4, :]
+    class_scores = grid[4:, :]
+    scores = class_scores.max(axis=0)
+    class_ids = class_scores.argmax(axis=0)
+    keep = scores >= score_threshold
+    if not bool(keep.any()):
+        return []
+
+    cx, cy, w, h = boxes[0, keep], boxes[1, keep], boxes[2, keep], boxes[3, keep]
+    xyxy = np.stack([cx - w / 2, cy - h / 2, cx + w / 2, cy + h / 2], axis=1)
+    kept_scores = scores[keep]
+    kept_classes = class_ids[keep]
+
+    detections: list[Detection] = []
+    for idx in _class_aware_nms(xyxy, kept_scores, kept_classes, nms_threshold):
+        box = transform.map_box_to_source(
+            float(xyxy[idx, 0]), float(xyxy[idx, 1]), float(xyxy[idx, 2]), float(xyxy[idx, 3])
+        )
+        class_id = int(kept_classes[idx])
+        label = labels[class_id] if labels is not None and 0 <= class_id < len(labels) else None
+        detections.append(
+            Detection(class_id=class_id, score=float(kept_scores[idx]), box=box, label=label)
+        )
+    return detections
+
+
+def _looks_like_wrong_layout(array: np.ndarray, transposed: bool) -> bool:
+    """Return true for the common unambiguous YOLO transpose mismatch."""
+    rows = int(array.shape[1])
+    cols = int(array.shape[2])
+    if transposed:
+        return cols > rows and rows >= 5
+    return rows > cols and cols >= 5
+
+
+def _class_aware_nms(
+    boxes: np.ndarray, scores: np.ndarray, class_ids: np.ndarray, threshold: float
+) -> list[int]:
+    import numpy as np
+
+    selected: list[int] = []
+    for cls in np.unique(class_ids):
+        members = np.nonzero(class_ids == cls)[0]
+        order = members[np.argsort(scores[members])[::-1]]
+        while order.size > 0:
+            best = int(order[0])
+            selected.append(best)
+            if order.size == 1:
+                break
+            rest = order[1:]
+            order = rest[_iou(boxes[best], boxes[rest]) <= threshold]
+    return selected
+
+
+def _iou(box: np.ndarray, others: np.ndarray) -> np.ndarray:
+    import numpy as np
+
+    x1 = np.maximum(box[0], others[:, 0])
+    y1 = np.maximum(box[1], others[:, 1])
+    x2 = np.minimum(box[2], others[:, 2])
+    y2 = np.minimum(box[3], others[:, 3])
+    inter = np.clip(x2 - x1, 0.0, None) * np.clip(y2 - y1, 0.0, None)
+    area_box = max(0.0, float(box[2] - box[0])) * max(0.0, float(box[3] - box[1]))
+    area_others = np.clip(others[:, 2] - others[:, 0], 0.0, None) * np.clip(
+        others[:, 3] - others[:, 1], 0.0, None
+    )
+    return np.asarray(inter / np.maximum(area_box + area_others - inter, 1e-9))