sequence-base 0.4.29__tar.gz → 0.4.31__tar.gz

{sequence_base-0.4.29 → sequence_base-0.4.31}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: sequence-base
-Version: 0.4.29
+Version: 0.4.31
 Summary: Shared foundation for the Sequences platform — wire contract, correlation, error taxonomy, constants. Used by the robot SDK, gateway, and container harness.
 Project-URL: Changelog, https://generalsequences.com/docs/changelog/
 Requires-Python: >=3.10
@@ -8,6 +8,10 @@ Requires-Dist: pydantic>=2.0
 Provides-Extra: codec
 Requires-Dist: numpy>=1.26; extra == 'codec'
 Requires-Dist: pillow>=10; extra == 'codec'
+Provides-Extra: observe
+Requires-Dist: av>=17; extra == 'observe'
+Requires-Dist: numpy>=1.26; extra == 'observe'
+Requires-Dist: zstandard>=0.22; extra == 'observe'
 Provides-Extra: test
 Requires-Dist: hypothesis>=6; extra == 'test'
 Requires-Dist: jsonschema>=4; extra == 'test'

{sequence_base-0.4.29 → sequence_base-0.4.31}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "sequence-base"
-version = "0.4.29"
+version = "0.4.31"
 description = "Shared foundation for the Sequences platform — wire contract, correlation, error taxonomy, constants. Used by the robot SDK, gateway, and container harness."
 requires-python = ">=3.10"
 dependencies = ["pydantic>=2.0"]
@@ -10,6 +10,7 @@ Changelog = "https://generalsequences.com/docs/changelog/"
 
 [project.optional-dependencies]
 codec = ["pillow>=10", "numpy>=1.26"]
+observe = ["numpy>=1.26", "av>=17", "zstandard>=0.22"]
 test = ["pytest", "jsonschema>=4", "hypothesis>=6", "pyyaml"]
 
 [build-system]

sequence_base-0.4.31/sequence_base/by_name.py

@@ -0,0 +1,90 @@
+"""
+Which arguments of a method a policy class names (infer=, observe=) an act's inputs fill: the inputs whole, its one
+argument - or, when it takes two or more without a default, each key of the inputs to its argument of that name.
+
+In one sentence: `takes_by_name(parameters, platform)` reads the method's arguments - less *args, **kwargs and the ones
+the platform hands it itself (`platform`: INFER_PLATFORM, OBSERVE_PLATFORM) → two or more of them without a default:
+it takes its inputs by name (ByName), each of its arguments a key - one without a default a key the inputs must hold,
+one with a default a key they may → `ByName.call(inputs, what)` makes what it is called with, refusing inputs that are
+no dict, lack a key it needs, or hold one it takes no argument for (unless it takes **kwargs), each named; fewer than
+two: None, the inputs go to its first argument whole and its others with a default are inference parameters, as before.
+
+WHY by the arguments without a default: a method that needs two or more could never be handed an act's inputs whole -
+the platform refused to deploy one - so binding them by name changes nothing a class deployed today does, and a method
+that takes one beside its inference parameters keeps taking its inputs whole. The SDK reads the rule when a class is
+declared (seq/named.py, registry.infer_params), the worker when it calls the method (harness/handler/loader.py): one
+rule on both sides.
+"""
+from __future__ import annotations
+
+import inspect
+from collections.abc import Iterable, Mapping
+from dataclasses import dataclass
+from typing import Any
+
+__all__ = ["INFER_PLATFORM", "OBSERVE_PLATFORM", "ByName", "takes_by_name"]
+
+
+
+INFER_PLATFORM = frozenset({"seed", "episode_id", "episode", "feedback", "plan", "robot", "embodiment"})
+OBSERVE_PLATFORM = frozenset({"step"})
+
+_VARIADIC = (inspect.Parameter.VAR_POSITIONAL, inspect.Parameter.VAR_KEYWORD)
+
+
+@dataclass(frozen=True)
+class ByName:
+    """A method that takes an act's inputs by name: `names`, the arguments they fill, in order; `required`, those with
+    no default; `positional`, those it takes by position only (before a `/`); `rest`, whether it takes **kwargs - any
+    other key of the inputs going there; `platform`, the names the platform hands it itself."""
+
+    names: tuple[str, ...]
+    required: tuple[str, ...]
+    positional: tuple[str, ...]
+    rest: bool
+    platform: frozenset[str]
+
+    def call(self, inputs: Any, what: str) -> tuple[list, dict]:
+        """(args, kwargs) the method `what` ("Model.predict") is called with for an act's `inputs`; ValueError, in its
+        words, for inputs that are not a dict of its arguments."""
+        takes = ", ".join(n if n in self.required else f"{n} (optional)" for n in self.names)
+        if not isinstance(inputs, Mapping):
+            raise ValueError(f"{what} takes its inputs by name ({takes}): an act's inputs are a dict of them, and "
+                             f"these are a {type(inputs).__name__}")
+        missing = [n for n in self.required if n not in inputs]
+        extra = [k for k in inputs if k not in self.names
+                 and not (self.rest and isinstance(k, str) and k not in self.platform)]
+        if missing or extra:
+            held = f"lack {_keys(missing)}" if missing else ""
+            if extra:
+                held += (" and " if held else "") + f"hold {_keys(extra)}, which it takes no argument for"
+            ours = [k for k in extra if k in self.platform]
+            mine = f" ({_keys(ours)}: the platform's to hand it)" if ours else ""
+            raise ValueError(f"{what} takes its inputs by name ({takes}), and these {held}{mine}")
+        args: list = []
+        for i, name in enumerate(self.positional):
+            if name not in inputs:
+                later = next((n for n in self.positional[i + 1:] if n in inputs), None)
+                if later is not None:
+                    raise ValueError(f"{what} takes {name} and {later} by position only, in that order: these hold "
+                                     f"{later!r} and no {name!r}")
+                break
+            args.append(inputs[name])
+        return args, {k: v for k, v in inputs.items() if k not in self.positional}
+
+
+def takes_by_name(parameters: Iterable[inspect.Parameter], platform: frozenset[str] = frozenset()) -> ByName | None:
+    """How a method of these `parameters` (self left out) takes an act's inputs: by name (ByName) when two or more of
+    its arguments - *args, **kwargs and `platform`'s left out - have no default, else None: whole, as one argument."""
+    every = list(parameters)
+    params = [p for p in every if p.kind not in _VARIADIC and p.name not in platform]
+    required = tuple(p.name for p in params if p.default is inspect.Parameter.empty)
+    if len(required) < 2:
+        return None
+    return ByName(names=tuple(p.name for p in params), required=required,
+                  positional=tuple(p.name for p in params if p.kind is inspect.Parameter.POSITIONAL_ONLY),
+                  rest=any(p.kind is inspect.Parameter.VAR_KEYWORD for p in every), platform=frozenset(platform))
+
+
+def _keys(names: list) -> str:
+    return ", ".join(repr(n) for n in names)

sequence_base-0.4.31/sequence_base/codec/marked.py

@@ -0,0 +1,337 @@
+"""
+Marked observation items: what the observation format puts on the wire. A robot marks items of its own observe data as
+sequence_ai.Video, Depth or Tactile; each marked item travels as the map below and the worker turns it back into the
+array it was, so the policy's observe function reads the data the robot built, item for item.
+
+
+
+In one sentence: the robot's SDK keeps one Encoder per marked item of an episode (its path in the observe data) → each
+observe() puts the map that item's encoder writes in place of the marked value → the worker keeps one Decoder per path
+of each episode (Streams) and puts each map's array back (decode) before the policy's observe function is called.
+
+The three kinds, as the user named them:
+- video - an RGB camera frame, HxWx3 uint8: H.264 for low latency - no B-frames, no lookahead, every frame out of the
+  encoder as it goes in - with a keyframe every second (KEYFRAME_S) and whenever the robot asks for one (force_keyframe:
+  after a reconnect, or after frames it dropped). Lossy (crf VIDEO_CRF).
+- depth - a depth map of any integer or float dtype, in the robot's own unit: lossless. Each frame on its own, every
+  value predicted from its left neighbour (an integer's difference, a float's bits XORed) and the bytes zstd-compressed.
+  640x480 sensor depth comes to about 2.3-2.5 times smaller in about a millisecond each way, as small as anything else
+  measured and the fastest; frames are not predicted from the frame before, because a sensor's noise is new in every
+  frame and that gained nothing.
+- tactile - a tactile reading. Image-like (HxWx3 uint8, what a camera-based sensor gives) is H.264 at high quality
+  (crf TACTILE_CRF); any other array, a pressure grid, travels as it is. Named tactile whatever it travels as.
+
+The map, version 1 (inside the observe body's msgpack; `data` is bin):
+  {"__seq__": "video" | "tactile", "v": 1, "codec": "h264", "w", "h", "n", "kf", "data"}
+      w, h: the frame's size (an odd one is padded to even for the encoder and cut back after); n: the frame's number in
+      its stream, from 0, never reused - a gap in n is frames the robot dropped; kf: a keyframe, which a decoder can
+      start from; data: one H.264 access unit (Annex B, its parameter sets in front of every keyframe).
+  {"__seq__": "depth", "v": 1, "codec": "zstd-delta" | "zstd-xor", "dtype", "shape", "data"}
+      dtype: numpy's string for it ("<u2", "<f4", ...); shape: the array's; data: the predicted values' bytes, byte
+      planes apart, zstd-compressed.
+  {"__seq__": "tactile", "v": 1, "codec": "raw", "value"}
+      value: the array (or whatever was marked), as msgpack carries any array.
+
+WHY a map with a reserved key rather than a msgpack extension type: sequence_base.msgpack_io refuses every extension
+type, so that reading a body runs nothing its sender chose; a map reads as data everywhere.
+WHY the codecs live here: the SDK encodes with the same module the worker decodes with, so the two cannot drift, and one
+round-trip test pins the format (tests/test_marked.py), as codec/image.py does for the frames of the robot-arm preset.
+
+Needs numpy, PyAV (av) and zstandard - `pip install 'sequence-base[observe]'`; each is imported where a codec first
+needs it, so nothing here is needed by a robot that marks nothing.
+
+    enc = encoder("video"); wire = enc.encode(frame); enc.force_keyframe()      # the robot, one per marked item
+    streams = Streams(); value = decode(value, streams)                        # the worker, one Streams per episode
+"""
+from __future__ import annotations
+
+import time
+from fractions import Fraction
+from typing import Any, Callable
+
+__all__ = ["KINDS", "MARK", "VERSION", "Decoder", "Encoder", "MarkedError", "NeedsKeyframe", "Streams", "decode",
+           "decode_one", "encoder", "is_marked"]
+
+MARK = "__seq__"
+VERSION = 1
+KINDS = ("video", "depth", "tactile")
+
+KEYFRAME_S = 1.0
+VIDEO_CRF = 23
+TACTILE_CRF = 12
+_PRESET = "ultrafast"
+_ZSTD_LEVEL = 1
+
+
+class MarkedError(ValueError):
+    """A value a marker cannot carry (encoding), or a map that is not one this reads (decoding)."""
+
+
+class NeedsKeyframe(MarkedError):
+    """A video frame that follows a gap in its stream and is not a keyframe: nothing before it to decode it from. The
+    robot's encoder sends a keyframe after any frame it dropped (force_keyframe), so this is never the robot's data."""
+
+
+def is_marked(value: Any) -> bool:
+    return isinstance(value, dict) and value.get(MARK) in KINDS
+
+
+def _wire(kind: str, **fields: Any) -> dict:
+    """A marked item's map: its kind under MARK, the version, then its codec's fields."""
+    return dict([(MARK, kind), ("v", VERSION), *fields.items()])
+
+
+
+class Encoder:
+    """One marked item's stream: `encode(value)` -> its map for this observe; `force_keyframe()` makes the next video
+    frame a keyframe."""
+
+    kind = ""
+
+    def encode(self, value: Any) -> dict:
+        raise NotImplementedError
+
+    def force_keyframe(self) -> None:
+        """Nothing to do for a kind with no state between frames."""
+
+
+def encoder(kind: str, *, clock: Callable[[], float] = time.monotonic) -> Encoder:
+    """A new stream's encoder for `kind` ("video", "depth" or "tactile")."""
+    if kind == "video":
+        return _VideoEncoder(clock)
+    if kind == "depth":
+        return _DepthEncoder()
+    if kind == "tactile":
+        return _TactileEncoder(clock)
+    raise MarkedError(f"no marker {kind!r}: the kinds are {', '.join(KINDS)}")
+
+
+class _H264:
+    """libx264 for one stream: low latency, every frame out at once, a forced keyframe an IDR the decoder starts from."""
+
+    def __init__(self, crf: int, clock: Callable[[], float]) -> None:
+        self._crf, self._clock = crf, clock
+        self._ctx = None
+        self._size: tuple[int, int] | None = None
+        self._n = 0
+        self._key_at: float | None = None
+        self._force = True
+
+    def force_keyframe(self) -> None:
+        self._force = True
+
+    def encode(self, frame: Any, kind: str) -> dict:
+        import av
+        import numpy as np
+
+        a = np.asarray(frame)
+        if a.dtype != np.uint8 or a.ndim != 3 or a.shape[2] != 3 or a.shape[0] < 2 or a.shape[1] < 2:
+            raise MarkedError(f"a {kind} frame is an RGB image, HxWx3 uint8; got {a.dtype} {tuple(a.shape)} - send other "
+                              "arrays unmarked, or as Depth or Tactile")
+        h, w = int(a.shape[0]), int(a.shape[1])
+        if (h, w) != self._size:
+            self._open(av, h, w)
+        if h % 2 or w % 2:
+            a = np.pad(a, ((0, h % 2), (0, w % 2), (0, 0)), mode="edge")
+        now = self._clock()
+        key = self._force or self._key_at is None or now - self._key_at >= KEYFRAME_S
+        vf = av.VideoFrame.from_ndarray(np.ascontiguousarray(a), format="rgb24").reformat(format="yuv420p")
+        vf.pts = self._n
+        if key:
+            vf.pict_type = av.video.frame.PictureType.I
+        packets = self._ctx.encode(vf)
+        if len(packets) != 1:
+            raise MarkedError(f"the H.264 encoder answered {len(packets)} packets for one frame")
+        data = bytes(packets[0])
+        kf = bool(packets[0].is_keyframe)
+        if kf:
+            self._key_at, self._force = now, False
+        n, self._n = self._n, self._n + 1
+        return _wire(kind, codec="h264", w=w, h=h, n=n, kf=kf, data=data)
+
+    def _open(self, av, h: int, w: int) -> None:
+        ctx = av.CodecContext.create("libx264", "w")
+        ctx.width, ctx.height, ctx.pix_fmt = w + w % 2, h + h % 2, "yuv420p"
+        ctx.time_base = Fraction(1, 30)
+
+        ctx.options = {"preset": _PRESET, "tune": "zerolatency", "crf": str(self._crf), "forced-idr": "1",
+                       "x264-params": "keyint=1000000:min-keyint=1:scenecut=0:bframes=0"}
+        ctx.thread_count = 1
+        ctx.open()
+        self._ctx, self._size, self._force = ctx, (h, w), True
+
+
+class _VideoEncoder(Encoder):
+    kind = "video"
+
+    def __init__(self, clock: Callable[[], float]) -> None:
+        self._h264 = _H264(VIDEO_CRF, clock)
+
+    def encode(self, value: Any) -> dict:
+        return self._h264.encode(value, "video")
+
+    def force_keyframe(self) -> None:
+        self._h264.force_keyframe()
+
+
+class _DepthEncoder(Encoder):
+    kind = "depth"
+
+    def encode(self, value: Any) -> dict:
+        import numpy as np
+
+        a = np.asarray(value)
+        if a.dtype.kind not in "uif" or a.ndim < 1 or a.size == 0:
+            raise MarkedError(f"a depth map is a non-empty array of integers or floats; got {a.dtype} {tuple(a.shape)}")
+        codec, data = _predict(a)
+        return _wire("depth", codec=codec, dtype=a.dtype.str, shape=list(a.shape), data=data)
+
+
+class _TactileEncoder(Encoder):
+    kind = "tactile"
+
+    def __init__(self, clock: Callable[[], float]) -> None:
+        self._h264 = _H264(TACTILE_CRF, clock)
+
+    def encode(self, value: Any) -> dict:
+        import numpy as np
+
+        a = np.asarray(value) if not isinstance(value, (bytes, str, dict)) else None
+        if a is not None and a.dtype == np.uint8 and a.ndim == 3 and a.shape[2] == 3 and min(a.shape[:2]) >= 2:
+            return self._h264.encode(a, "tactile")
+        return _wire("tactile", codec="raw", value=value)
+
+    def force_keyframe(self) -> None:
+        self._h264.force_keyframe()
+
+
+
+def _predict(a) -> tuple[str, bytes]:
+    import numpy as np
+    import zstandard
+
+    le = a.astype(a.dtype.newbyteorder("<"), copy=False)
+    size = le.dtype.itemsize
+    rows = np.ascontiguousarray(le).reshape(-1, le.shape[-1]).view(f"<u{size}")
+    out = rows.copy()
+    if le.dtype.kind == "f":
+        out[:, 1:] = rows[:, 1:] ^ rows[:, :-1]
+        codec = "zstd-xor"
+    else:
+        out[:, 1:] = rows[:, 1:] - rows[:, :-1]
+        signed = out.view(f"<i{size}")
+        out = ((signed << 1) ^ (signed >> (8 * size - 1))).view(f"<u{size}")
+        codec = "zstd-delta"
+    planes = out.view(np.uint8).reshape(-1, size).T.tobytes()
+    return codec, zstandard.ZstdCompressor(level=_ZSTD_LEVEL).compress(planes)
+
+
+def _unpredict(m: dict):
+    import numpy as np
+    import zstandard
+
+    dtype, shape, codec = np.dtype(m["dtype"]), tuple(int(s) for s in m["shape"]), m["codec"]
+    size = dtype.itemsize
+    cols = shape[-1]
+    raw = zstandard.ZstdDecompressor().decompress(m["data"])
+    count = int(np.prod(shape))
+    if len(raw) != count * size or codec not in ("zstd-delta", "zstd-xor"):
+        raise MarkedError(f"a depth map that does not read back: {codec} {m['dtype']} {list(shape)}")
+    rows = np.frombuffer(raw, np.uint8).reshape(size, -1).T.copy().view(f"<u{size}").reshape(-1, cols)
+    if codec == "zstd-xor":
+        values = np.bitwise_xor.accumulate(rows, axis=1)
+    else:
+        signed = rows.view(f"<i{size}")
+        steps = ((rows >> 1).view(f"<i{size}") ^ -(signed & 1)).view(f"<u{size}")
+        values = np.cumsum(steps, axis=1, dtype=f"<u{size}")
+    return values.view(dtype.newbyteorder("<")).reshape(shape).astype(dtype, copy=False)
+
+
+
+class Decoder:
+    """One marked item's stream: `decode(map)` -> the array it carries."""
+
+    def decode(self, m: dict) -> Any:
+        return decode_one(m)
+
+
+class _VideoDecoder(Decoder):
+    """H.264 for one stream, frames in order; after a gap in n it waits for a keyframe (NeedsKeyframe until then)."""
+
+    def __init__(self) -> None:
+        self._ctx = None
+        self._last: int | None = None
+        self._whole = False
+
+    def decode(self, m: dict) -> Any:
+        import av
+
+        n, kf = int(m["n"]), bool(m["kf"])
+        if self._last is not None and n != self._last + 1:
+            self._whole = False
+        self._last = n
+        if kf:
+            self._whole = True
+        if not self._whole:
+            raise NeedsKeyframe(f"{m.get(MARK)} frame {n} follows a gap in its stream and is not a keyframe")
+        if self._ctx is None:
+            self._ctx = av.CodecContext.create("h264", "r")
+            self._ctx.thread_count = 1
+        frames = self._ctx.decode(av.Packet(m["data"]))
+        if not frames:
+            raise MarkedError(f"{m.get(MARK)} frame {n} decoded to nothing")
+        import numpy as np
+
+        rgb = frames[-1].to_ndarray(format="rgb24")
+        h, w = int(m["h"]), int(m["w"])
+        return rgb if rgb.shape[:2] == (h, w) else np.ascontiguousarray(rgb[:h, :w])
+
+
+def decode_one(m: dict) -> Any:
+    """A map with no state between frames - depth, or tactile as it is - back to its value. Video needs its stream's
+    Decoder (Streams)."""
+    if not is_marked(m) or int(m.get("v") or 0) != VERSION:
+        raise MarkedError(f"not a marked item of version {VERSION}: {sorted(m) if isinstance(m, dict) else type(m)}")
+    codec = m.get("codec")
+    if m[MARK] == "depth":
+        return _unpredict(m)
+    if m[MARK] == "tactile" and codec == "raw":
+        return m.get("value")
+    raise MarkedError(f"a {m[MARK]} item in {codec!r} decodes in its stream's order (Streams)")
+
+
+class Streams:
+    """One episode's decoders, by the path of each marked item in its observe data."""
+
+    def __init__(self) -> None:
+        self._decoders: dict[tuple, Decoder] = {}
+
+    def decoder(self, path: tuple, m: dict) -> Decoder:
+        d = self._decoders.get(path)
+        if d is None:
+            d = self._decoders[path] = _VideoDecoder() if m.get("codec") == "h264" else Decoder()
+        return d
+
+
+def decode(value: Any, streams: Streams, path: tuple = ()) -> Any:
+    """`value` with every marked map in it - in dicts and lists, at any depth - replaced by its array; everything else
+    as it was, the same objects. A map that is not marked is walked; one that is decodes with its path's decoder."""
+    if isinstance(value, dict):
+        if is_marked(value):
+            return streams.decoder(path, value).decode(value)
+        if not any(_holds_mark(v) for v in value.values()):
+            return value
+        return {k: decode(v, streams, path + (k,)) for k, v in value.items()}
+    if isinstance(value, list):
+        if not any(_holds_mark(v) for v in value):
+            return value
+        return [decode(v, streams, path + (i,)) for i, v in enumerate(value)]
+    return value
+
+
+def _holds_mark(value: Any) -> bool:
+    if isinstance(value, dict):
+        return is_marked(value) or any(_holds_mark(v) for v in value.values())
+    if isinstance(value, list):
+        return any(_holds_mark(v) for v in value)
+    return False

{sequence_base-0.4.29 → sequence_base-0.4.31}/sequence_base/constants/version.py

@@ -4,7 +4,9 @@
 
 
 
-CONTRACT_VERSION = "0.5.26"
+CONTRACT_VERSION = "0.5.28"
+
+
 
 
 

{sequence_base-0.4.29 → sequence_base-0.4.31}/sequence_base/construct.py

@@ -1,10 +1,12 @@
 """
 How a policy class that names its own methods is built (PolicyRegistration.constructor): its constructor - or the
-factory it names - called with the arguments its decorator was given, once two forms in them are filled in.
+factory it names, a classmethod of it or a module's function - called with the arguments its decorator was given, once
+two forms in them are filled in.
 
 In one sentence: a value {"$config": path, "$set": {...}} becomes the YAML or JSON file at `path` - from the folder of
 the class's file - read where the policy runs, with `$set`'s keys laid over its top level → in every string,
 "{weights}" becomes the weights directory and "{weights.<part>}" a named part's → `cls.<make>(*args, **kwargs)`, or
+`function(*args, **kwargs)` for make="package.module:function" - the module imported where the policy runs - or
 `cls(*args, **kwargs)` without a factory.
 
 WHY a config file is read where the policy runs: it is part of the project (XPolicyLab's deploy.yml beside its
@@ -14,12 +16,14 @@ worker's directory.
 """
 from __future__ import annotations
 
+import importlib
 import json
 import os
 import re
 from typing import Any
 
-__all__ = ["CONFIG_KEY", "SET_KEY", "ConstructError", "build", "config", "expand", "is_config", "read_config"]
+__all__ = ["CONFIG_KEY", "SET_KEY", "ConstructError", "build", "config", "expand", "is_config", "maker",
+           "read_config"]
 
 CONFIG_KEY, SET_KEY = "$config", "$set"
 _WEIGHTS = re.compile(r"\{weights(?:\.([A-Za-z_][A-Za-z0-9_-]*))?\}")
@@ -96,8 +100,25 @@ def _weights_of(part: str | None, weights: Any) -> str:
 
 
 def build(cls: type, constructor: Any, *, base_dir: str, weights: Any) -> Any:
-    """The instance `constructor` (a PolicyConstructor) makes of `cls`: `cls.<make>(*args, **kwargs)` or `cls(...)`."""
+    """The instance `constructor` (a PolicyConstructor) makes of `cls`: `cls.<make>(*args, **kwargs)`, the function
+    make="package.module:function" names called so, or `cls(...)`."""
     args = expand(list(constructor.args), base_dir=base_dir, weights=weights)
     kwargs = expand(dict(constructor.kwargs), base_dir=base_dir, weights=weights)
-    make = getattr(cls, constructor.make) if constructor.make else cls
-    return make(*args, **kwargs)
+    return maker(cls, constructor.make)(*args, **kwargs)
+
+
+def maker(cls: type, make: str | None) -> Any:
+    """What builds the instance: `cls` for no make=, its classmethod or staticmethod `make`, or - make written
+    "package.module:function" - that module's function, the module imported (as the policy's code imports it).
+    """
+    if not make:
+        return cls
+    module, colon, name = make.rpartition(":")
+    if not colon:
+        return getattr(cls, make)
+    found = getattr(importlib.import_module(module), name, None)
+    if found is None:
+        raise ConstructError(f"make={make!r}: {module} has no function {name!r}")
+    if not callable(found):
+        raise ConstructError(f"make={make!r}: {module}.{name} is not callable ({type(found).__name__})")
+    return found

{sequence_base-0.4.29 → sequence_base-0.4.31}/sequence_base/contract/flags.py

@@ -48,6 +48,8 @@ class SeqFlags(IntFlag):
 
 
 
+
+
     SAMPLE = 524288
 
 

{sequence_base-0.4.29 → sequence_base-0.4.31}/sequence_base/contract/policy.py

@@ -482,19 +482,26 @@ def check_weights_parts(weights_name: str | None, extra: dict) -> None:
         raise ValueError(f"at most {MAX_WEIGHTS_PARTS} weights parts")
 
 
+
+_MAKE = r"^(?:[A-Za-z_][A-Za-z0-9_]*(?:\.[A-Za-z_][A-Za-z0-9_]*)*:)?[A-Za-z_][A-Za-z0-9_]*$"
+
+
 class PolicyConstructor(BaseModel):
     """How the worker builds a policy class that names its own methods (`@seq.policy(infer="get_action", ...)`): its
-    own constructor, or the factory it names (`make`, e.g. LeRobot's `from_pretrained`), called with `args` and
-    `kwargs` where `@seq.load` would run - the replica's cold start, the weights on disk. The values are the user's own,
-    as JSON carries them, but for two forms the worker fills in first (sequence_base.construct.expand): a config file's
-    contents, `{"$config": <its path from the class's file>, "$set": {<keys laid over it>}}`, YAML or JSON, and in any
-    string `"{weights}"` (the weights directory) or `"{weights.<part>}"` (a named part's).
+    own constructor, or the factory it names (`make`: a classmethod of it, e.g. LeRobot's `from_pretrained`, or a
+    module's function, "package.module:function", whose return is the instance its methods are called on), called
+    with `args` and `kwargs` where `@seq.load` would run - the replica's cold start, the weights on disk. The values are
+    the user's own, as JSON carries them, but for two forms the worker fills in first (sequence_base.construct.expand):
+    a config file's contents, `{"$config": <its path from the class's file>, "$set": {<keys laid over it>}}`, YAML or
+    JSON, and in any string `"{weights}"` (the weights directory) or `"{weights.<part>}"` (a named part's).
+
 """
 
     model_config = ConfigDict(extra="forbid")
 
-    make: str | None = Field(default=None, pattern=r"^[A-Za-z_][A-Za-z0-9_]*$",
-                             description="a classmethod or staticmethod that returns the instance; None: the class")
+    make: str | None = Field(default=None, max_length=512, pattern=_MAKE,
+                             description="a classmethod or staticmethod that returns the instance, or a module's "
+                                         "function, 'package.module:function' (contract 0.5.27); None: the class")
     args: list[Any] = Field(default_factory=list, description="positional arguments, in order")
     kwargs: dict[str, Any] = Field(default_factory=dict, description="keyword arguments")
 
@@ -509,8 +516,9 @@ class PolicyRegistration(BaseModel):
     act carries, before INFER is called with none), RESET (an episode's first act) and ON_EPISODE (its end).
 
     Any policy may bind SAMPLE (contract 0.5.24, `@seq.policy(sample="<method>")`): the method returning one episode's
-    act inputs, in order, each as an act carries it - what its build check acts with and its worker times its infer on
-    when no contract says what it reads."""
+    calls in order, as a robot makes them - ("observe", x) for its observe(x) and ("act",) for its act(), which carries
+    nothing, every input going through observe - what its build check plays as the robot's own calls go, and its worker
+    times its infer on (the acts) when no contract says what it reads."""
 
     model_config = ConfigDict(extra="forbid")
 

{sequence_base-0.4.29 → sequence_base-0.4.31}/sequence_base/schemas/ActRequest.json

@@ -107,5 +107,5 @@
   ],
   "title": "ActRequest",
   "type": "object",
-  "x-contract-version": "0.5.26"
+  "x-contract-version": "0.5.28"
 }

{sequence_base-0.4.29 → sequence_base-0.4.31}/sequence_base/schemas/ActResponse.json

@@ -89,5 +89,5 @@
   ],
   "title": "ActResponse",
   "type": "object",
-  "x-contract-version": "0.5.26"
+  "x-contract-version": "0.5.28"
 }

{sequence_base-0.4.29 → sequence_base-0.4.31}/sequence_base/schemas/ActionChunk.json

@@ -99,5 +99,5 @@
   ],
   "title": "ActionChunk",
   "type": "object",
-  "x-contract-version": "0.5.26"
+  "x-contract-version": "0.5.28"
 }

{sequence_base-0.4.29 → sequence_base-0.4.31}/sequence_base/schemas/ActionContract.json

@@ -96,5 +96,5 @@
   ],
   "title": "ActionContract",
   "type": "object",
-  "x-contract-version": "0.5.26"
+  "x-contract-version": "0.5.28"
 }

{sequence_base-0.4.29 → sequence_base-0.4.31}/sequence_base/schemas/ActionStep.json

@@ -19,5 +19,5 @@
   ],
   "title": "ActionStep",
   "type": "object",
-  "x-contract-version": "0.5.26"
+  "x-contract-version": "0.5.28"
 }

{sequence_base-0.4.29 → sequence_base-0.4.31}/sequence_base/schemas/Actions.json

@@ -59,5 +59,5 @@
   },
   "title": "Actions",
   "type": "object",
-  "x-contract-version": "0.5.26"
+  "x-contract-version": "0.5.28"
 }

{sequence_base-0.4.29 → sequence_base-0.4.31}/sequence_base/schemas/AdapterPair.json

@@ -17,5 +17,5 @@
   ],
   "title": "AdapterPair",
   "type": "object",
-  "x-contract-version": "0.5.26"
+  "x-contract-version": "0.5.28"
 }

{sequence_base-0.4.29 → sequence_base-0.4.31}/sequence_base/schemas/AddLocal.json

@@ -23,5 +23,5 @@
   ],
   "title": "AddLocal",
   "type": "object",
-  "x-contract-version": "0.5.26"
+  "x-contract-version": "0.5.28"
 }