boxes-client 0.1.1__py3-none-any.whl

boxes_client/__init__.py

@@ -0,0 +1,40 @@
+"""boxes_client -- a thin client for calling deployed AI "boxes" by IP:port.
+
+A *box* is one of the gRPC services in ``/images/`` built to the shared
+``pipeline.PipelineService.Process(Envelope) -> Envelope`` interface. Point
+this client at any one by address and send an ``Envelope``::
+
+    from boxes_client import Box
+    b = Box("localhost:8061")            # local box   ("10.0.0.5:8061" for remote)
+
+    # any box -- generic, box-agnostic (data + config dicts)
+    res = b.run(data={"sentences": ["hello", "world"]},
+                config={"my_box": {"command": "do_thing"}})
+
+The core (``Box`` / ``Result`` / envelope builders) knows **no box**.  There is
+also an *optional convenience layer* for specific boxes -- e.g. the tapnext
+point-tracking one-liner -- kept separate on purpose::
+
+    from boxes_client import trace                      # optional, tapnext-only
+    res = trace(b, images=["frame.jpg"], grid_size=30)
+
+No registry, no central server: the client connects directly to the box. Local
+and remote boxes are the same call -- just change the address.
+"""
+
+import os as _os
+import sys as _sys
+
+# Vendored generated proto modules import each other and ``aux`` as top-level
+# names; make that directory reachable before they are imported.
+_PB_DIR = _os.path.join(_os.path.dirname(__file__), "_pb")
+if _os.path.isdir(_PB_DIR) and _PB_DIR not in _sys.path:
+    _sys.path.append(_PB_DIR)
+
+from .box import Box
+from .result import Result
+from .envelope import load
+from .conveniences import trace  # optional, convenience layer (not core)
+
+__all__ = ["Box", "Result", "load", "trace"]
+__version__ = "0.1.0"

boxes_client/_pb/__init__.py

@@ -0,0 +1,8 @@
+import os as _os
+import sys as _sys
+
+# The generated modules import `pipeline_pb2`, `aux` as top-level modules,
+# so this directory has to be on sys.path before they are imported.
+_HERE = _os.path.dirname(__file__)
+if _HERE not in _sys.path:
+    _sys.path.append(_HERE)

boxes_client/_pb/aux.py

@@ -0,0 +1,37 @@
+import pipeline_pb2
+
+def wrap_value(obj):
+    """Wrap a Python object into a pipeline.Value"""
+    if isinstance(obj, float):
+        return pipeline_pb2.Value(f=obj)
+    elif isinstance(obj, str):
+        return pipeline_pb2.Value(s=obj)
+    elif isinstance(obj, bytes):
+        return pipeline_pb2.Value(b=obj)
+
+    elif isinstance(obj, list):
+        if all(isinstance(v, float) for v in obj):
+            return pipeline_pb2.Value(ff=pipeline_pb2.FloatList(values=obj))
+        elif all(isinstance(v, str) for v in obj):
+            return pipeline_pb2.Value(ss=pipeline_pb2.StringList(values=obj))
+        elif all(isinstance(v, (bytes, bytearray)) for v in obj):
+            return pipeline_pb2.Value(bb=pipeline_pb2.BytesList(values=obj))
+    raise TypeError(f"Cannot wrap object of type {type(obj)}: {obj}")
+
+
+def unwrap_value(val: pipeline_pb2.Value):
+    """Unwrap a pipeline.Value into a plain Python object"""
+    kind = val.WhichOneof("kind")
+    if kind == "f":
+        return val.f
+    if kind == "s":
+        return val.s
+    if kind == "b":
+        return val.b
+    if kind == "ff":
+        return list(val.ff.values)
+    if kind == "ss":
+        return list(val.ss.values)
+    if kind == "bb":
+        return list(val.bb.values)
+    return None

boxes_client/_pb/pipeline_pb2.py

@@ -0,0 +1,50 @@
+# -*- coding: utf-8 -*-
+# Generated by the protocol buffer compiler.  DO NOT EDIT!
+# NO CHECKED-IN PROTOBUF GENCODE
+# source: pipeline.proto
+# Protobuf Python Version: 7.35.1
+"""Generated protocol buffer code."""
+from google.protobuf import descriptor as _descriptor
+from google.protobuf import descriptor_pool as _descriptor_pool
+from google.protobuf import runtime_version as _runtime_version
+from google.protobuf import symbol_database as _symbol_database
+from google.protobuf.internal import builder as _builder
+_runtime_version.ValidateProtobufRuntimeVersion(
+    _runtime_version.Domain.PUBLIC,
+    7,
+    35,
+    1,
+    '',
+    'pipeline.proto'
+)
+# @@protoc_insertion_point(imports)
+
+_sym_db = _symbol_database.Default()
+
+
+
+
+DESCRIPTOR = _descriptor_pool.Default().AddSerializedFile(b'\n\x0epipeline.proto\x12\x08pipeline\"\x1b\n\tFloatList\x12\x0e\n\x06values\x18\x01 \x03(\x02\"\x1c\n\nStringList\x12\x0e\n\x06values\x18\x01 \x03(\t\"\x1b\n\tBytesList\x12\x0e\n\x06values\x18\x01 \x03(\x0c\"\xa0\x01\n\x05Value\x12\x0b\n\x01\x62\x18\x01 \x01(\x0cH\x00\x12\x0b\n\x01s\x18\x02 \x01(\tH\x00\x12\x0b\n\x01\x66\x18\x05 \x01(\x02H\x00\x12!\n\x02\x62\x62\x18\x06 \x01(\x0b\x32\x13.pipeline.BytesListH\x00\x12\"\n\x02ss\x18\x07 \x01(\x0b\x32\x14.pipeline.StringListH\x00\x12!\n\x02\x66\x66\x18\n \x01(\x0b\x32\x13.pipeline.FloatListH\x00\x42\x06\n\x04kind\"\x89\x01\n\x08\x45nvelope\x12\x13\n\x0b\x63onfig_json\x18\x01 \x01(\t\x12*\n\x04\x64\x61ta\x18\x02 \x03(\x0b\x32\x1c.pipeline.Envelope.DataEntry\x1a<\n\tDataEntry\x12\x0b\n\x03key\x18\x01 \x01(\t\x12\x1e\n\x05value\x18\x02 \x01(\x0b\x32\x0f.pipeline.Value:\x02\x38\x01\x32\x44\n\x0fPipelineService\x12\x31\n\x07Process\x12\x12.pipeline.Envelope\x1a\x12.pipeline.Envelopeb\x06proto3')
+
+_globals = globals()
+_builder.BuildMessageAndEnumDescriptors(DESCRIPTOR, _globals)
+_builder.BuildTopDescriptorsAndMessages(DESCRIPTOR, 'pipeline_pb2', _globals)
+if not _descriptor._USE_C_DESCRIPTORS:
+  DESCRIPTOR._loaded_options = None
+  _globals['_ENVELOPE_DATAENTRY']._loaded_options = None
+  _globals['_ENVELOPE_DATAENTRY']._serialized_options = b'8\001'
+  _globals['_FLOATLIST']._serialized_start=28
+  _globals['_FLOATLIST']._serialized_end=55
+  _globals['_STRINGLIST']._serialized_start=57
+  _globals['_STRINGLIST']._serialized_end=85
+  _globals['_BYTESLIST']._serialized_start=87
+  _globals['_BYTESLIST']._serialized_end=114
+  _globals['_VALUE']._serialized_start=117
+  _globals['_VALUE']._serialized_end=277
+  _globals['_ENVELOPE']._serialized_start=280
+  _globals['_ENVELOPE']._serialized_end=417
+  _globals['_ENVELOPE_DATAENTRY']._serialized_start=357
+  _globals['_ENVELOPE_DATAENTRY']._serialized_end=417
+  _globals['_PIPELINESERVICE']._serialized_start=419
+  _globals['_PIPELINESERVICE']._serialized_end=487
+# @@protoc_insertion_point(module_scope)

boxes_client/_pb/pipeline_pb2_grpc.py

@@ -0,0 +1,100 @@
+# Generated by the gRPC Python protocol compiler plugin. DO NOT EDIT!
+"""Client and server classes corresponding to protobuf-defined services."""
+import grpc
+import warnings
+
+import pipeline_pb2 as pipeline__pb2
+
+GRPC_GENERATED_VERSION = '1.83.0'
+GRPC_VERSION = grpc.__version__
+_version_not_supported = False
+
+try:
+    from grpc._utilities import first_version_is_lower
+    _version_not_supported = first_version_is_lower(GRPC_VERSION, GRPC_GENERATED_VERSION)
+except ImportError:
+    _version_not_supported = True
+
+if _version_not_supported:
+    raise RuntimeError(
+        f'The grpc package installed is at version {GRPC_VERSION},'
+        + ' but the generated code in pipeline_pb2_grpc.py depends on'
+        + f' grpcio>={GRPC_GENERATED_VERSION}.'
+        + f' Please upgrade your grpc module to grpcio>={GRPC_GENERATED_VERSION}'
+        + f' or downgrade your generated code using grpcio-tools<={GRPC_VERSION}.'
+    )
+
+
+class PipelineServiceStub:
+    """Universal service interface
+    """
+
+    def __init__(self, channel):
+        """Constructor.
+
+        Args:
+            channel: A grpc.Channel.
+        """
+        self.Process = channel.unary_unary(
+                '/pipeline.PipelineService/Process',
+                request_serializer=pipeline__pb2.Envelope.SerializeToString,
+                response_deserializer=pipeline__pb2.Envelope.FromString,
+                _registered_method=True)
+
+
+class PipelineServiceServicer:
+    """Universal service interface
+    """
+
+    def Process(self, request, context):
+        """Missing associated documentation comment in .proto file."""
+        context.set_code(grpc.StatusCode.UNIMPLEMENTED)
+        context.set_details('Method not implemented!')
+        raise NotImplementedError('Method not implemented!')
+
+
+def add_PipelineServiceServicer_to_server(servicer, server):
+    rpc_method_handlers = {
+            'Process': grpc.unary_unary_rpc_method_handler(
+                    servicer.Process,
+                    request_deserializer=pipeline__pb2.Envelope.FromString,
+                    response_serializer=pipeline__pb2.Envelope.SerializeToString,
+            ),
+    }
+    generic_handler = grpc.method_handlers_generic_handler(
+            'pipeline.PipelineService', rpc_method_handlers)
+    server.add_generic_rpc_handlers((generic_handler,))
+    server.add_registered_method_handlers('pipeline.PipelineService', rpc_method_handlers)
+
+
+ # This class is part of an EXPERIMENTAL API.
+class PipelineService:
+    """Universal service interface
+    """
+
+    @staticmethod
+    def Process(request,
+            target,
+            options=(),
+            channel_credentials=None,
+            call_credentials=None,
+            insecure=False,
+            compression=None,
+            wait_for_ready=None,
+            timeout=None,
+            metadata=None):
+        return grpc.experimental.unary_unary(
+            request,
+            target,
+            '/pipeline.PipelineService/Process',
+            pipeline__pb2.Envelope.SerializeToString,
+            pipeline__pb2.Envelope.FromString,
+            options,
+            channel_credentials,
+            insecure,
+            call_credentials,
+            compression,
+            wait_for_ready,
+            timeout,
+            metadata,
+            _registered_method=True)

boxes_client/_pb_loader.py

@@ -0,0 +1,18 @@
+"""Loading of the vendored generated proto modules.
+
+``boxes_client._pb.__init__`` puts its own directory on ``sys.path`` so the
+generated modules (which import each other and ``aux`` as top-level) resolve.
+Importing the package first guarantees that, then we grab the top-level modules.
+"""
+
+import importlib
+
+
+def get():
+    """Return ``(pipeline_pb2, pipeline_pb2_grpc, aux)``."""
+    import boxes_client._pb  # noqa: F401  -> runs __init__, fixes sys.path
+
+    pb2 = importlib.import_module("pipeline_pb2")
+    pb2_grpc = importlib.import_module("pipeline_pb2_grpc")
+    aux = importlib.import_module("aux")
+    return pb2, pb2_grpc, aux

boxes_client/box.py

@@ -0,0 +1,211 @@
+"""``Box`` -- a thin client for one deployed box (a box = a gRPC AI service).
+
+Give it an address (``host:port``) and it can send an ``Envelope`` and get a
+decoded ``Result`` back via the shared ``pipeline.PipelineService`` interface.
+
+Local and remote boxes are identical: ``Box("localhost:8061")`` vs
+``Box("10.0.0.5:8061")``. No registry, no central server -- the client dials
+the box directly (boxes are push-style servers), which preserves the
+distributed nature of the fleet.
+
+The core stays **box-agnostic**: it knows how to build and send an ``Envelope``
+and read a ``Result`` back, but it knows no box, field, or model.  Box-specific
+conveniences (one per box, e.g. a point-tracking helper) live in
+:mod:`boxes_client.conveniences`, are built purely on top of :meth:`Box.run`,
+and are never imported by the core.
+
+Core call surface
+-----------------
+:meth:`Box.run`    -- the generic workhorse: ``run(data=..., config=..., method="Process")``.
+                      No assumption about field names or payload types.
+:meth:`Box.reset`  -- clear server-side state (``{"<box>": {"command": "reset"}}``).
+:meth:`Box.call`   -- send an already-built ``Envelope`` via ``Process``.
+:meth:`Box.info`   -- reachability + gRPC-reflection self-description probe.
+"""
+
+
+from typing import Any, Dict, List, Optional, Union
+
+import grpc
+
+from ._pb_loader import get as _get_pb
+from . import envelope as _env
+from .result import Result
+
+_SERVICE = "pipeline.PipelineService"
+_DEFAULT_PORT = 8061
+
+
+class Box:
+    """A client for a single box.
+
+    Parameters
+    ----------
+    address:
+        ``"host:port"`` or just ``"host"`` (defaults to port 8061).
+    port:
+        Optional explicit port (alternative to the ``":"`` in the address).
+    timeout:
+        Per-RPC timeout in seconds (default 600).
+    config_key:
+        Optional name of the box's config section. Needed only by
+        :meth:`reset` (and ``run(reset_first=True)``) so it knows which section
+        to reset. The generic :meth:`run` does not need it -- you pass the full
+        ``config`` dict yourself. Defaults to ``None``: the core assumes no box.
+        Pass e.g. ``config_key="tapnext"`` when you will reset a stateful box.
+    """
+
+    def __init__(
+        self,
+        address: str,
+        port: Optional[int] = None,
+        timeout: float = 600,
+        config_key: Optional[str] = None,
+    ):
+        self.host, self.port = _split_address(address, port)
+        self.timeout = timeout
+        self.config_key = config_key
+
+        self._channel = grpc.insecure_channel(
+            f"{self.host}:{self.port}",
+            options=[
+                ("grpc.max_send_message_length", -1),
+                ("grpc.max_receive_message_length", -1),
+            ],
+        )
+        pb2, pb2_grpc, _aux = _get_pb()
+        self._stub = pb2_grpc.PipelineServiceStub(self._channel)
+
+    # ------------------------------------------------------------------ utils
+    def close(self):
+        try:
+            self._channel.close()
+        except Exception:
+            pass
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, *exc):
+        self.close()
+
+    # ------------------------------------------------------------- discover
+    def info(self, timeout: float = 10) -> Dict[str, Any]:
+        """Ask the box (via gRPC reflection) what it exposes.
+
+        Returns ``{"service", "methods", "reflection", "reachable"}``.
+        ``reflection`` is ``False`` if the box does not serve reflection (the
+        client still works; it just cannot self-describe).
+        """
+        out = {"service": _SERVICE, "methods": [], "reflection": False,
+               "reachable": False}
+        try:
+            grpc.channel_ready_future(self._channel).result(timeout=timeout)
+            out["reachable"] = True
+        except Exception:
+            return out
+
+        try:
+            from grpc_reflection.v1alpha import (
+                reflection_pb2,
+                reflection_pb2_grpc,
+            )
+        except ImportError:
+            return out
+
+        stub = reflection_pb2_grpc.ServerReflectionStub(self._channel)
+        try:
+            # Bidirectional-streaming RPC: one request -> (take the first) response.
+            def _reqs():
+                yield reflection_pb2.ServerReflectionRequest(list_services="*")
+            resp = next(stub.ServerReflectionInfo(iter(_reqs()), timeout=timeout))
+            services = [e.name for e in resp.list_services_response.service]
+            if _SERVICE in services:
+                out["reflection"] = True
+                out["methods"] = ["Process"]
+            else:
+                out["methods"] = services
+        except Exception:
+            out["reflection"] = False
+        return out
+
+    # ---------------------------------------------------------------- internal
+    def _send(self, envelope, method: str) -> Result:
+        """Low-level: send ``envelope`` via the named ``method`` on the box."""
+        fn = getattr(self._stub, method, None)
+        if not callable(fn):
+            known = sorted(n for n in dir(self._stub) if not n.startswith("_"))
+            raise AttributeError(
+                f"Box has no RPC method {method!r}. "
+                f"This stub defines: {known} (only 'Process' is guaranteed; "
+                f"other methods depend on the box's own .proto)."
+            )
+        resp = fn(envelope, timeout=self.timeout)
+        return Result.from_envelope(resp)
+
+    # ------------------------------------------------------------------ calls
+    def run(
+        self,
+        data: Optional[Dict[str, Any]] = None,
+        config: Optional[Dict[str, Any]] = None,
+        method: str = "Process",
+        reset_first: bool = False,
+    ) -> Result:
+        """Generic entry point.
+
+        Parameters
+        ----------
+        data:
+            Mapping of ``field_name -> value`` written into ``Envelope.data``.
+            Values follow :mod:`boxes_client.envelope` coercion rules:
+            ``bytes`` / ``pathlib.Path`` -> bytes; ``str`` -> literal string;
+            ``int`` -> float; lists of those -> ``BytesList`` / ``StringList``
+            / ``FloatList``.
+        config:
+            The box-specific control payload (dict) serialized to
+            ``Envelope.config_json``. Shape depends on the box.
+        method:
+            RPC name to invoke (default ``"Process"``). Boxes may expose extra
+            methods (e.g. opencv's ``similarity_check``, yolo's
+            ``DetectSequence`` / ``TrackSequence`` / ``AllProcessing``).
+        reset_first:
+            If ``True``, send a tapnext-style reset (config-only
+            ``{config_key: {"command": "reset"}}``) on ``Process`` first.
+            Useful for stateful boxes; ignored by stateless ones.
+        """
+        if reset_first:
+            self.reset()
+        return self._send(_env.build(data, config), method)
+
+    def reset(self, config_key: Optional[str] = None) -> Result:
+        """Best-effort clear of server-side state.
+
+        Sends a config-only ``Process`` call with ``{key: {"command": "reset"}}``
+        where ``key`` is ``config_key`` (if given) or the box's ``config_key``
+        from the constructor. Boxes treat it as a hard state reset; boxes that
+        don't recognize the command typically ignore it.
+        """
+        key = config_key or self.config_key
+        if not key:
+            raise ValueError(
+                "Box.reset(): no config_key given. Construct the Box with "
+                "config_key=<box> or call Box.reset(config_key=<box>).")
+        return self._send(_env.reset_envelope(key), "Process")
+
+    # Back-compat alias: low-level "I already built the Envelope" call.
+    def call(self, envelope: Any) -> Result:
+        return self._send(envelope, "Process")
+
+
+def _split_address(address: str, port: Optional[int]) -> tuple:
+    address = (address or "").strip()
+    if ":" not in address:
+        return (address or "localhost"), (int(port) if port is not None else _DEFAULT_PORT)
+    host, _, maybe_port = address.rpartition(":")
+    if not host:
+        host = "localhost"
+    if maybe_port.isdigit():
+        return host, int(maybe_port)
+    if port is not None:
+        return host, int(port)
+    return host, _DEFAULT_PORT

boxes_client/codec.py

@@ -0,0 +1,113 @@
+"""Named payload codecs: the *declared* decoding path (see ``CODECS.md``).
+
+The client is smart about *shape* and dumb about *content*: a box says how
+its payload is encoded by adding an ``"encoding"`` field to its response
+``config_json`` (a codec name for every ``bytes`` field, or a
+``{field_name: codec_name}`` map for mixed responses). The core only knows the
+generic ``encoding`` keyword and this registry of codecs — **never a box
+name**.
+
+Codec vocabulary (all pure ``bytes -> object``):
+
+==================  =========================================================
+name                behavior
+==================  =========================================================
+``identity``        raw bytes, unchanged (the default)
+``json``            UTF-8 JSON document -> ``list``/``dict``/scalar
+``torch``           ``torch.save`` bytes -> the unpickled object
+                    (Tensor or dict of Tensors); needs ``torch``
+``numpy``           raw float32 buffer -> ``np.ndarray``
+``zstd_pickle``     ``zstd.compress(pickle.dumps(obj))`` -> ``obj``;
+                    needs ``zstandard``
+==================  =========================================================
+
+A codec whose library is missing (``torch`` / ``zstandard``) degrades to
+``identity`` (raw bytes) plus a warning — **never raises**: the client always
+returns *something* usable.
+"""
+
+import io
+import json
+import pickle
+import warnings
+
+import numpy as np
+
+__all__ = ["CODECS", "decode_with"]
+
+
+def _decode_identity(buf: bytes) -> bytes:
+    return buf
+
+
+def _decode_json(buf: bytes):
+    """Strict: declared ``json`` fields must parse (or we degrade in
+    ``decode_with``); no "does it look like JSON?" sniffing."""
+    s = buf.decode("utf-8")
+    return json.loads(s)
+
+
+def _decode_torch(buf: bytes):
+    """``torch.save`` blob -> whatever object was saved (Tensor or dict).
+
+    Propagates (rather than hides) decode failures so ``decode_with`` can
+    degrade with a warning instead of silently guessing."""
+    import torch  # noqa: W061  -- ImportError here means the lib is missing
+
+    return torch.load(io.BytesIO(buf), weights_only=False, map_location="cpu")
+
+
+def _decode_numpy(buf: bytes) -> "np.ndarray":
+    """Raw numeric buffer (float32, per the opencv_box ``np_to_bytes``
+    contract)."""
+    return np.frombuffer(buf, dtype=np.float32)
+
+
+def _decode_zstd_pickle(buf: bytes):
+    """``zstandard`` compress + ``pickle`` -> the decoded Python object
+    (normally a list). The lang_segm -> folder_wd cross-box contract."""
+    import zstandard  # noqa: W061  -- ImportError here means the lib is missing
+
+    return pickle.loads(zstandard.ZstdDecompressor().decompress(buf))
+
+
+#: The named registry: generic codec name -> pure ``bytes -> object`` function.
+#: No box name appears here or below; boxes *select* a codec by declaring it.
+CODECS = {
+    "identity": _decode_identity,
+    "json": _decode_json,
+    "torch": _decode_torch,
+    "numpy": _decode_numpy,
+    "zstd_pickle": _decode_zstd_pickle,
+}
+
+
+def decode_with(payload, name):
+    """Apply a *named* codec to ``payload`` (raw ``bytes``/``bytearray``).
+
+    - ``name`` is ``None``/``"identity"`` -> raw bytes, unchanged (the
+      agnostic default).
+    - unknown name, or a codec whose library is missing, or a payload the
+      codec cannot parse -> a warning is emitted and the **raw bytes** are
+      returned. ``decode_with`` never raises.
+    """
+    if name is None or name == "identity":
+        return bytes(payload)
+    fn = CODECS.get(name)
+    if fn is None:
+        warnings.warn(
+            f"codec {name!r} is not a known codec (known: {sorted(CODECS)}); "
+            "returning raw bytes",
+            stacklevel=2,
+        )
+        return bytes(payload)
+    try:
+        return fn(payload)
+    except Exception as e:
+        kind = "library is not installed" if isinstance(e, ImportError) else "decode failed"
+        warnings.warn(
+            f"codec {name!r}: {kind} ({type(e).__name__}: {e}); "
+            "returning raw bytes",
+            stacklevel=2,
+        )
+        return bytes(payload)

boxes_client/conveniences.py

@@ -0,0 +1,102 @@
+"""Box-specific *conveniences* -- NOT part of the agnostic core.
+
+The core of ``boxes_client`` (``box.py`` / ``envelope.py`` / ``result.py`` /
+``decode_util.py``) is deliberately box-agnostic: it only knows *how* to build
+an ``Envelope`` and send it over the shared ``PipelineService`` interface, and
+*how* to read a ``Result`` back. It knows **no box name, field name, or model**.
+
+This module is the opposite, on purpose: it encodes knowledge about a *specific*
+box and only composes the generic ``Box.run`` / ``Box.reset`` primitives.  The
+tapnext point-tracking helper :func:`trace` lives here.
+
+If you add a convenience for another box (``segment``, ``embed``, ``detect``,
+...), put it here or in a sibling ``conveniences/<box>.py`` -- **never** in
+``box.py`` -- so the core stays agnostic and each box's sugar is isolated,
+visible, and easy to delete.
+"""
+
+from typing import Any, List, Sequence, Union
+import pathlib
+
+__all__ = ["trace", "load_images"]
+
+
+def load_images(images: Union[str, bytes, "pathlib.PurePath", Sequence]) -> List[bytes]:
+    """Normalize an ``images`` argument into a list of ``bytes``.
+
+    ``trace`` is the *image-box* convenience, so a bare ``str`` here is treated
+    as a **local file path** to serialize (distinct from the generic ``run``
+    contract where ``str`` means a literal string).  Accepts:
+
+    * a single path (``str``/``pathlib.Path``) or pre-encoded ``bytes``
+    * a list of any of the above
+    """
+    if images is None:
+        return []
+    if isinstance(images, (str, bytes, bytearray, pathlib.PurePath)):
+        images = [images]
+    out: List[bytes] = []
+    for item in images:
+        if isinstance(item, (bytes, bytearray, memoryview)):
+            out.append(bytes(item))
+        elif isinstance(item, (str, pathlib.PurePath)):
+            out.append(pathlib.Path(item).read_bytes())
+        else:
+            raise TypeError(
+                f"Unsupported image element: {type(item)!r}. "
+                "Pass a path (str/pathlib.Path), pre-encoded bytes, or a list of those."
+            )
+    return out
+
+
+def trace(
+    box,
+    images: Union[str, bytes, "pathlib.PurePath", Sequence],
+    *,
+    grid_size: int = None,
+    reset_first: bool = True,
+    config_key: str = "tapnext",
+    **params: Any,
+):
+    """Point-tracking convenience for the **tapnext** box.
+
+    Built purely on the generic core -- it is equivalent to::
+
+        box.run(data={"images": [bytes, ...]},
+                config={config_key: {"command": "track", "parameters": {...}}},
+                method="Process")
+
+    with an optional preceding ``box.reset(config_key)`` (tapnext *accumulates*
+    tracks across sequential requests, so a reset keeps a one-shot clean).
+
+    Parameters
+    ----------
+    box:
+        A :class:`boxes_client.Box` pointed at a tapnext box.
+    images:
+        A single local path / pre-encoded bytes, or a list of either.
+    grid_size:
+        TAPNext grid size (added to ``parameters``).
+    reset_first:
+        Send ``reset`` first (default ``True``).
+    config_key:
+        The box's config section name (default ``"tapnext"``).
+    **params:
+        Extra ``parameters`` (e.g. ``threshold=...``).
+    """
+    images_bytes = load_images(images)
+    if not images_bytes:
+        raise ValueError("trace(): no images provided")
+
+    parameters: Any = dict(params or {})
+    if grid_size is not None:
+        parameters["grid_size"] = int(grid_size)
+
+    if reset_first:
+        box.reset(config_key)
+
+    return box.run(
+        data={"images": images_bytes},
+        config={config_key: {"command": "track", "parameters": parameters}},
+        method="Process",
+    )