sequence-base 0.5.0__tar.gz → 0.6.0__tar.gz

{sequence_base-0.5.0 → sequence_base-0.6.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: sequence-base
-Version: 0.5.0
+Version: 0.6.0
 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

{sequence_base-0.5.0 → sequence_base-0.6.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "sequence-base"
-version = "0.5.0"
+version = "0.6.0"
 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"]

{sequence_base-0.5.0 → sequence_base-0.6.0}/sequence_base/__init__.py

@@ -86,8 +86,6 @@ from sequence_base.contract import (
     PolicyConstructor,
     PolicyRegistration,
     PolicySpec,
-    Observations,
-    Stream,
     Tensors,
     Proprioception,
     ReplaySpec,
@@ -145,7 +143,7 @@ __all__ = [
     "FROZEN_PATH", "TemplateFiles", "ImageStepTemplateFiles", "Project", "ImageStepProject", "ImageStep", "ImageSpec",
     "VolumeMount", "VolumeRef", "Concurrency", "ActionContract", "Camera", "ObservationContract",
     "PolicySpec", "PolicyRegistration", "PolicyConstructor",
-    "Observations", "Stream", "Tensors",
+    "Tensors",
 
     "MAX_CODE_BUNDLE_BYTES", "CodeBundle",
     "Resources", "Autoscaler", "Timeouts", "DeploymentPolicy", "InferParam", "DeploymentRequest",

sequence_base-0.6.0/sequence_base/codec/compressed.py

@@ -0,0 +1,174 @@
+"""
+Compressed observe items: what a robot's SDK puts in place of a large array or bytes of its observe data when sending it
+compressed saves more upload time than compressing it costs, and what a worker turns back - losslessly, so every reader
+after the worker is handed the bytes the robot built.
+
+
+
+In one sentence: the robot's SDK compresses an unmarked numpy array or bytes of 16 KiB or more with zstd level 1 (zlib
+level 1 where it has no zstd) and puts the map below in its place → the worker names contract.observe.ZSTD_FORMAT, so
+only it is sent such maps → as a post comes, before anything keeps it, expand() turns every map back into the array or
+bytes it was (np.frombuffer: read-only, as msgpack_io reads an array) and says how many bytes that added.
+
+The map, version 1 (inside the observe body's msgpack; `data` is bin):
+  {"__seq__": "compressed", "v": 1, "codec": "zstd" | "zlib", "n": <bytes before>, "data": <compressed>}
+      bytes as they were
+  ... and "type": numpy's string for its dtype, "shape": the array's - an array, its data C-ordered
+`n` is checked against the bytes the data turns back into, and against the most one item may hold (the bytes of an
+episode's observations a worker keeps): a map that says less than it holds is refused rather than decompressed past it.
+
+WHY the observation format's reserved key: marked items (codec/marked.py) already take a map with "__seq__", so one key
+is reserved in observe data, not two; a compressed item is never inside a marked one - the SDK compresses after encoding
+its markers and leaves their maps as they are - and expand() does not look inside one.
+WHY decompressed as the post comes, at the parent: the stream, Field data and the standby's saves all read a post's
+frames as it comes, and each must keep the robot's data, not the wire's.
+
+    wire = compress(frame, "zstd")                       # a reference encoder (the SDK has its own, with its rule)
+    value, grew = expand(post_inputs, limit=64 << 20)    # the worker, as a post comes
+"""
+from __future__ import annotations
+
+import zlib
+from typing import Any
+
+from sequence_base.codec.marked import MARK, is_marked
+
+__all__ = ["CODECS", "KIND", "VERSION", "CompressedError", "compress", "expand", "holds", "is_compressed"]
+
+KIND = "compressed"
+VERSION = 1
+CODECS = ("zstd", "zlib")
+_LEVEL = 1
+
+
+class CompressedError(ValueError):
+    """A compressed item that does not read: an unknown codec, data that does not turn back into the `n` bytes it says,
+    an `n` past the limit, or an array's type or shape that does not fit them."""
+
+
+def is_compressed(value: Any) -> bool:
+    return isinstance(value, dict) and value.get(MARK) == KIND
+
+
+def _zstd():
+    """zstd's (compress, decompress) - zstandard's, else Python 3.14's compression.zstd. The decompress takes the bytes
+    the item says it holds and refuses a frame whose header says other: a header is what sizes the buffer."""
+    try:
+        import zstandard
+
+        def unzstd(b: bytes, n: int) -> bytes:
+            said = zstandard.frame_content_size(b)
+            if said not in (-1, n):
+                raise CompressedError(f"a zstd item whose frame says {said} bytes and whose map says {n}")
+            return zstandard.ZstdDecompressor().decompress(b, max_output_size=n)
+
+        return (lambda b: zstandard.ZstdCompressor(level=_LEVEL).compress(b), unzstd)
+    except ImportError:
+        from compression import zstd
+
+        def unzstd(b: bytes, n: int) -> bytes:
+            said = zstd.get_frame_info(b).decompressed_size
+            if said not in (None, n):
+                raise CompressedError(f"a zstd item whose frame says {said} bytes and whose map says {n}")
+            d = zstd.ZstdDecompressor()
+            raw = d.decompress(b, max_length=n)
+            if not d.eof:
+                raise CompressedError(f"a zstd item that holds more than the {n} bytes it says")
+            return raw
+
+        return (lambda b: zstd.compress(b, level=_LEVEL), unzstd)
+
+
+def compress(value: Any, codec: str = "zstd") -> dict:
+    """`value` - a numpy array or bytes - as its compressed item: a reference encoder, for tests and the platform's own
+    senders; the robot's SDK decides by its own rule what to compress."""
+    import numpy as np
+
+    if isinstance(value, np.ndarray):
+        raw = np.ascontiguousarray(value).tobytes()
+        extra = {"type": value.dtype.str, "shape": list(value.shape)}
+    else:
+        raw, extra = bytes(value), {}
+    if codec == "zstd":
+        data = _zstd()[0](raw)
+    elif codec == "zlib":
+        data = zlib.compress(raw, _LEVEL)
+    else:
+        raise CompressedError(f"no codec {codec!r}: {', '.join(CODECS)}")
+    return dict([(MARK, KIND), ("v", VERSION), ("codec", codec), ("n", len(raw)), *extra.items(), ("data", data)])
+
+
+def _raw(item: dict, limit: int) -> bytes:
+    codec, n, data = item.get("codec"), item.get("n"), item.get("data")
+    if codec not in CODECS:
+        raise CompressedError(f"a compressed item of codec {codec!r}: {', '.join(CODECS)} are read")
+    if isinstance(n, bool) or not isinstance(n, int) or not 0 <= n <= limit:
+        raise CompressedError(f"a compressed item of {n!r} bytes: at most {limit} are taken")
+    if not isinstance(data, (bytes, bytearray)):
+        raise CompressedError("a compressed item whose data is not bytes")
+    try:
+        if codec == "zstd":
+            raw = _zstd()[1](bytes(data), n)
+        else:
+            d = zlib.decompressobj()
+            raw = d.decompress(bytes(data), n)
+            if d.unconsumed_tail or not d.eof:
+                raise CompressedError(f"a zlib item that holds more than the {n} bytes it says")
+    except CompressedError:
+        raise
+    except Exception as exc:
+        raise CompressedError(f"a {codec} item that does not read: {exc}") from None
+    if len(raw) != n:
+        raise CompressedError(f"a {codec} item of {len(raw)} bytes that says it holds {n}")
+    return raw
+
+
+def _value(item: dict, limit: int) -> Any:
+    raw = _raw(item, limit)
+    if "type" not in item and "shape" not in item:
+        return raw
+    import numpy as np
+
+    from sequence_base.msgpack_io import MsgpackError, _dtype
+
+    shape = item.get("shape")
+    if not isinstance(shape, list) or not all(isinstance(d, int) and not isinstance(d, bool) and d >= 0 for d in shape):
+        raise CompressedError("a compressed array whose shape is not a list of non-negative ints")
+    try:
+        dtype = _dtype(item.get("type"))
+    except MsgpackError as exc:
+        raise CompressedError(f"a compressed array: {exc}") from None
+    if dtype.itemsize * int(np.prod(shape, dtype=np.int64)) != len(raw):
+        raise CompressedError(f"a compressed {dtype} array of shape {shape} that holds {len(raw)} bytes")
+    return np.frombuffer(raw, dtype=dtype).reshape(shape)
+
+
+def expand(value: Any, *, limit: int) -> "tuple[Any, int]":
+    """`value` with every compressed item in it - in dicts and lists at any depth, never inside a marked item - turned
+    back into the array or bytes it was, the same objects where none is; and how many bytes that added. `limit`: the
+    most bytes one item may turn back into. CompressedError for an item that does not read."""
+    grew = [0]
+
+    def walk(v: Any) -> Any:
+        if isinstance(v, dict):
+            if is_compressed(v):
+                out = _value(v, limit)
+                grew[0] += max(0, int(v["n"]) - len(v["data"]))
+                return out
+            if is_marked(v) or not holds(v):
+                return v
+            return {k: walk(x) for k, x in v.items()}
+        if isinstance(v, list):
+            return [walk(x) for x in v] if holds(v) else v
+        return v
+
+    return walk(value), grew[0]
+
+
+def holds(value: Any) -> bool:
+    """Whether `value` holds a compressed item - in dicts and lists at any depth, not inside a marked item."""
+    if isinstance(value, dict):
+        return is_compressed(value) or (not is_marked(value) and any(holds(v) for v in value.values()))
+    if isinstance(value, list):
+        return any(holds(v) for v in value)
+    return False

{sequence_base-0.5.0 → sequence_base-0.6.0}/sequence_base/constants/limits.py

@@ -36,4 +36,4 @@ METRIC_UNIT_MAX = 16
 MAX_STREAM_FRAMES = 1024
 MAX_STREAM_BYTES = 64 * 1024 * 1024
 MAX_WORKER_STREAM_BYTES = 1024 * 1024 * 1024
-STREAM_WAIT_S = 10.0
+STREAM_WAIT_S = 3.0

{sequence_base-0.5.0 → sequence_base-0.6.0}/sequence_base/constants/version.py

@@ -4,7 +4,9 @@
 
 
 
-CONTRACT_VERSION = "0.5.32"
+CONTRACT_VERSION = "0.5.34"
+
+
 
 
 

sequence_base-0.6.0/sequence_base/construct.py

@@ -0,0 +1,173 @@
+"""
+How a class built by its constructor is built - a policy's or a planner's (PolicyRegistration.constructor), a benchmark's
+(BenchmarkSpec.constructor): its constructor - or the factory it names, a classmethod of it or a module's function -
+called with the arguments its decorator was given (init=), once the 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 class runs, with `$set`'s keys laid over its top level → in every string, a policy's
+"{weights}" becomes the weights directory and "{weights.<part>}" a named part's, a benchmark's "{num_worlds}" how many
+worlds this eval builds and "{policy.<field>}" what the evaluated policy declares (POLICY_FIELDS) - a string that is one
+form alone becomes its value as it is, an int or None, one among other text its value as text → `cls.<make>(*args,
+**kwargs)`, or `function(*args, **kwargs)` for make="package.module:function" - the module imported where the class
+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
+model.py) and goes up with it, so one copy - the one the policy runs with - is read, and "{weights}" in it means the
+worker's directory.
+
+WHY a benchmark's too: its worlds are built after the machine's snapshot by the class's own constructor - a repository's
+env as it is, handed how many worlds and the policy's rate where its own code takes them - where a method of the
+platform's (@seq.setup) built them before.
+
+"""
+from __future__ import annotations
+
+import importlib
+import json
+import os
+import re
+from typing import Any
+
+__all__ = ["CONFIG_KEY", "FORMS", "POLICY_FIELDS", "SET_KEY", "ConstructError", "build", "config", "expand",
+           "is_config", "maker", "read_config"]
+
+CONFIG_KEY, SET_KEY = "$config", "$set"
+
+
+
+POLICY_FIELDS = ("hz", "action_chunk_len", "action_chunk_exec_len")
+
+
+FORMS = re.compile(r"\{(?:weights(?:\.(?P<part>[A-Za-z_][A-Za-z0-9_-]*))?|(?P<worlds>num_worlds)"
+                   r"|policy\.(?P<field>[A-Za-z_][A-Za-z0-9_]*))\}")
+
+
+class ConstructError(ValueError):
+    """Arguments that cannot be filled in: a config file missing, unreadable or of another kind, a weights placeholder
+    with no weights - or no such part - to fill it, "{num_worlds}" where no worlds are built, or a policy field no policy
+    declares."""
+
+
+def config(path: str, **overrides: Any) -> dict:
+    """A config file's contents with `overrides` laid over its top level, as the worker reads it (`seq.config`)."""
+    if not isinstance(path, str) or not path:
+        raise ConstructError("a config file is a path, from the folder of the class's file")
+    if os.path.isabs(path):
+        raise ConstructError(f"{path}: give a config file's path from the folder of the class's file - the policy runs "
+                             "it where the upload puts it")
+    return {CONFIG_KEY: path, SET_KEY: dict(overrides)}
+
+
+def is_config(value: Any) -> bool:
+    return isinstance(value, dict) and set(value) == {CONFIG_KEY, SET_KEY} and isinstance(value[CONFIG_KEY], str)
+
+
+def read_config(path: str) -> Any:
+    """The YAML (.yml, .yaml) or JSON (.json) file at `path`."""
+    kind = os.path.splitext(path)[1].lower()
+    if kind not in (".json", ".yml", ".yaml"):
+        raise ConstructError(f"{path}: a config file is .json, .yml or .yaml")
+    if not os.path.isfile(path):
+        raise ConstructError(f"{path}: no such config file")
+    with open(path, encoding="utf-8") as f:
+        if kind == ".json":
+            return json.load(f)
+        try:
+            import yaml
+        except ImportError:
+            raise ConstructError(f"{path}: reading YAML needs pyyaml") from None
+        return yaml.safe_load(f)
+
+
+def expand(value: Any, *, base_dir: str, weights: Any = None, worlds: int | None = None, policy: Any = None) -> Any:
+    """`value` with its config files read (from `base_dir`) and its forms filled: a policy's from `weights` - the
+    weights directory, or {part: directory} for named parts, or None for a policy without weights - a benchmark's from
+    `worlds`, how many worlds this eval builds, and `policy`, what the evaluated policy declares ({field: value}, or an
+    object with them; None where none is evaluated, each field None). A string that is one form alone becomes its value
+    as it is; one form among other text, its value as text."""
+    forms = {"base_dir": base_dir, "weights": weights, "worlds": worlds, "policy": policy}
+    if is_config(value):
+        loaded = read_config(os.path.join(base_dir, value[CONFIG_KEY]))
+        if value[SET_KEY] and not isinstance(loaded, dict):
+            raise ConstructError(f"{value[CONFIG_KEY]} holds a {type(loaded).__name__}, which has no keys to set")
+        merged = {**loaded, **value[SET_KEY]} if isinstance(loaded, dict) else loaded
+        return expand(merged, **forms)
+    if isinstance(value, dict):
+        return {k: expand(v, **forms) for k, v in value.items()}
+    if isinstance(value, (list, tuple)):
+        return [expand(v, **forms) for v in value]
+    if isinstance(value, str):
+        alone = FORMS.fullmatch(value)
+        if alone:
+            return _filled(alone, weights, worlds, policy)
+        return FORMS.sub(lambda m: str(_filled(m, weights, worlds, policy)), value)
+    return value
+
+
+def _filled(form: re.Match, weights: Any, worlds: int | None, policy: Any) -> Any:
+    if form.group("worlds"):
+        if worlds is None:
+            raise ConstructError("{num_worlds} is how many worlds this eval builds, and none is handed: a benchmark of one "
+                                 "world an instance takes none")
+        return worlds
+    field = form.group("field")
+    if field is not None:
+        if field not in POLICY_FIELDS:
+            raise ConstructError(f"{{policy.{field}}}: a policy declares {', '.join(POLICY_FIELDS)}")
+        if policy is None:
+            return None
+        return policy.get(field) if isinstance(policy, dict) else getattr(policy, field, None)
+    return _weights_of(form.group("part"), weights)
+
+
+def _weights_of(part: str | None, weights: Any) -> str:
+    if weights is None:
+        raise ConstructError("{weights} names the weights directory, and this policy declares no weights=")
+    if isinstance(weights, dict):
+        if part is None:
+            raise ConstructError(f"its weights come in named parts ({', '.join(sorted(weights))}): name one, "
+                                 f"{{weights.<part>}}")
+        if part not in weights:
+            raise ConstructError(f"{{weights.{part}}}: its weights have no part {part!r} "
+                                 f"({', '.join(sorted(weights))})")
+        return str(weights[part])
+    if part is not None:
+        raise ConstructError(f"{{weights.{part}}} names a part, and its weights come whole: {{weights}}")
+    return str(weights)
+
+
+def build(cls: type, constructor: Any, *, base_dir: str, weights: Any = None, worlds: int | None = None,
+          policy: Any = None, params: dict | None = None) -> Any:
+    """The instance `constructor` (a PolicyConstructor) makes of `cls`: `cls.<make>(*args, **kwargs)`, the function
+    make="package.module:function" names called so, or `cls(...)` - its arguments filled (expand), and `params`, what
+    an eval set of the constructor's other arguments (--param benchmark.NAME=VALUE), laid over them. A keyword argument
+    that is "{policy.<field>}" alone is left out while that field is None - no policy evaluated, at a registration
+    check, or one that declares none - so the constructor's own default holds, as a benchmark's own code did with what
+    @seq.setup was handed before."""
+    forms = {"base_dir": base_dir, "weights": weights, "worlds": worlds, "policy": policy}
+    args = expand(list(constructor.args), **forms)
+    kwargs = {}
+    for name, value in dict(constructor.kwargs).items():
+        filled = expand(value, **forms)
+        alone = FORMS.fullmatch(value) if isinstance(value, str) else None
+        if filled is None and alone is not None and alone.group("field") is not None:
+            continue
+        kwargs[name] = filled
+    return maker(cls, constructor.make)(*args, **{**kwargs, **(params or {})})
+
+
+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.5.0 → sequence_base-0.6.0}/sequence_base/contract/__init__.py

@@ -45,7 +45,7 @@ from sequence_base.contract.policy import (
 )
 
 
-from sequence_base.contract.own_io import Observations, Stream, Tensors
+from sequence_base.contract.own_io import OBSERVATIONS_GONE, Tensors
 
 
 from sequence_base.contract.deployments import (
@@ -124,20 +124,30 @@ from sequence_base.contract.settings import (
 )
 
 
-from sequence_base.contract.team import (
-    TEAM_DEFAULT_GROUP,
-    GroupObservation,
-    GroupObserve,
-    GroupObserved,
+
+from sequence_base.contract.planner import (
+    KEPT,
+    MOST_LAYERS,
+    PLANS_MOST,
+    STATE_MOST,
+    PLAN_ON_A_POLICY,
+    PLANNER_ID,
+    POLICY_ID,
+    ROBOT_ID,
+    TEAM_GONE,
     PlanAppend,
     PlanAppended,
-    TeamGroup,
-    TeamGroups,
-    TeamGroupsRequest,
-    TeamMember,
-    TeamPlans,
-    TeamPlansWritten,
-    TeamSpec,
+    PlannerMember,
+    PlannerObservation,
+    PlannerObserve,
+    PlannerObserved,
+    PlannerPlanIn,
+    PlannerPlans,
+    PlannerPlansWritten,
+    PlannerRobot,
+    PlannerRound,
+    PlannerRoundRequest,
+    PlannerSpec,
 )
 
 
@@ -154,7 +164,7 @@ __all__ = [
     "TemplateFiles", "ImageStepTemplateFiles", "Project", "ImageStepProject", "FROZEN_PATH", "ImageStep", "ImageSpec",
     "VolumeMount", "VolumeRef", "Concurrency", "ActionContract", "Camera", "ObservationContract",
     "PolicySpec", "PolicyRegistration", "PolicyConstructor",
-    "Observations", "Stream", "Tensors",
+    "OBSERVATIONS_GONE", "Tensors",
 
     "MAX_CODE_BUNDLE_BYTES", "CodeBundle",
     "Resources", "Autoscaler", "Timeouts", "DeploymentPolicy", "InferParam", "DeploymentRequest",
@@ -174,8 +184,9 @@ __all__ = [
     "SETTINGS", "Setting", "SettingsChange", "Applied", "SettingState", "SettingsView", "SettingChanged",
     "SettingsChanged",
 
-    "TEAM_DEFAULT_GROUP", "TeamSpec", "TeamGroupsRequest", "GroupObservation", "TeamMember", "TeamGroup", "TeamGroups",
-    "TeamPlans", "TeamPlansWritten", "PlanAppend", "PlanAppended", "GroupObserve", "GroupObserved",
+    "KEPT", "MOST_LAYERS", "PLANS_MOST", "STATE_MOST", "PLAN_ON_A_POLICY", "PLANNER_ID", "POLICY_ID", "ROBOT_ID", "TEAM_GONE", "PlannerSpec",
+    "PlannerRoundRequest", "PlannerRobot", "PlannerMember", "PlannerObservation", "PlannerPlanIn", "PlannerRound",
+    "PlannerPlans", "PlannerPlansWritten", "PlanAppend", "PlanAppended", "PlannerObserve", "PlannerObserved",
 
     "TEMPLATE_SCHEME", "parse_template",
 

{sequence_base-0.5.0 → sequence_base-0.6.0}/sequence_base/contract/benchmarks.py

@@ -1,9 +1,10 @@
 """
-Contract 5 (registration half) - a benchmark is the env you already have, run as it is: a short class of yours marks
-three methods - @seq.setup builds this eval's worlds after the machine's snapshot, @seq.reset starts an episode of a task
-at a seed, @seq.step plays one action and says what came of it - and declares its tasks, its seeds and how long an episode
-may run. The platform reads none of its observations or actions: they go to the policy, and come from it, as a robot's
-do. The eval *run* wire types (RolloutResult, EvalReport, ...) live in contract/eval.py.
+Contract 5 (registration half) - a benchmark is the env you already have, run as it is: its class is built by its own
+constructor after the machine's snapshot (init= its arguments, "{num_worlds}" and "{policy.<field>}" filled), a short class
+of yours marks two methods - @seq.reset starts an episode of a task at a seed, @seq.step plays one action and says what
+came of it - and declares its tasks, its seeds and how long an episode may run. The platform reads none of its
+observations or actions: they go to the policy, and come from it, as a robot's do. The eval *run* wire types
+(RolloutResult, EvalReport, ...) live in contract/eval.py.
 
 
 """
@@ -18,7 +19,8 @@ from sequence_base.constants.limits import MAX_ENVS, TASK_DESCRIPTION_MAX
 from sequence_base.contract.accounts import SecretRef
 from sequence_base.contract.deployments import CodeBundle, DeploymentState, InferParam
 from sequence_base.contract.flags import BENCHMARK_BINDABLE, SeqFlags
-from sequence_base.contract.policy import KIND_NAME, ImageSpec, VolumeRef
+from sequence_base.contract.policy import KIND_NAME, ImageSpec, PolicyConstructor, VolumeRef
+from sequence_base.construct import FORMS
 
 __all__ = [
     "ReplaySpec",
@@ -31,6 +33,27 @@ __all__ = [
 TASK_NAME = r"^[A-Za-z0-9][A-Za-z0-9._/:-]{0,127}$"
 
 
+
+SETUP_GONE = ("@seq.setup is gone: a benchmark builds its worlds in its constructor, after the machine's snapshot - "
+              'init= its arguments, "{num_worlds}" how many worlds this eval builds and "{policy.<field>}" what the '
+              "evaluated policy declares; a benchmark registered with @seq.setup is registered again with sequence-ai "
+              "0.51.1 or later (seq deploy)")
+
+
+def _names_worlds(constructor: PolicyConstructor | None) -> bool:
+    """Whether init= hands the constructor "{num_worlds}" anywhere - in a string, at any depth."""
+    def walk(value) -> bool:
+        if isinstance(value, str):
+            return any(m.group("worlds") for m in FORMS.finditer(value))
+        if isinstance(value, dict):
+            return any(walk(v) for v in value.values())
+        if isinstance(value, (list, tuple)):
+            return any(walk(v) for v in value)
+        return False
+
+    return constructor is not None and walk([constructor.args, constructor.kwargs])
+
+
 def _check_tasks(tasks: dict, seeds: list, max_seconds) -> None:
     import re as _re
 
@@ -75,11 +98,11 @@ class ReplaySpec(BaseModel):
 
 
 class BenchmarkSpec(BaseModel):
-    """What `@seq.benchmark(...)` and its marked methods add up to, as an eval runs it. `bindings` names the methods:
-    RESET and STEP always, SETUP when it builds its worlds after the machine's snapshot - which a vectorized env, one
-    stepping `worlds` worlds a call (@seq.concurrent(sizes=[N]) on its step), always does. `max_seconds` is an episode's
-    time on the robot's clock, the same for every task or {task: seconds}; `assets` are versioned scene volumes mounted
-    at /assets; `secrets` by name."""
+    """What `@seq.benchmark(...)` and its marked methods add up to, as an eval runs it. `bindings` names the methods,
+    RESET and STEP; `constructor` the arguments its class is built with after the machine's snapshot (init=) - which a
+    vectorized env, one stepping `worlds` worlds a call (@seq.concurrent(sizes=[N]) on its step), hands how many,
+    "{num_worlds}". `max_seconds` is an episode's time on the robot's clock, the same for every task or {task: seconds};
+    `assets` are versioned scene volumes mounted at /assets; `secrets` by name."""
 
     model_config = ConfigDict(extra="forbid")
 
@@ -89,7 +112,7 @@ class BenchmarkSpec(BaseModel):
     seeds: list[int] = Field(..., description="The seeds an episode starts at; trial k of a task runs seeds[k % len]")
     max_seconds: float | dict[str, float] = Field(..., description="An episode's time limit, or {task: seconds}")
     handler_ref: str
-    bindings: dict[SeqFlags, str] = Field(..., description="SETUP / RESET / STEP -> method name")
+    bindings: dict[SeqFlags, str] = Field(..., description="RESET / STEP -> method name")
 
 
     worlds: int | None = Field(default=None, ge=1, le=MAX_ENVS)
@@ -106,6 +129,10 @@ class BenchmarkSpec(BaseModel):
 
     engine: str | None = Field(default=None, pattern=KIND_NAME)
 
+
+
+    constructor: PolicyConstructor | None = None
+
     @model_validator(mode="after")
     def _tasks(self) -> "BenchmarkSpec":
         _check_tasks(self.tasks, self.seeds, self.max_seconds)
@@ -113,15 +140,18 @@ class BenchmarkSpec(BaseModel):
 
     @model_validator(mode="after")
     def _bindings(self) -> "BenchmarkSpec":
+        if SeqFlags.SETUP in self.bindings:
+            raise ValueError(SETUP_GONE)
         bad = set(self.bindings) - set(BENCHMARK_BINDABLE)
         if bad:
             names = ", ".join(sorted(f.name or str(f.value) for f in bad))
-            raise ValueError(f"a benchmark marks @seq.setup, @seq.reset and @seq.step only; got {names}")
+            raise ValueError(f"a benchmark marks @seq.reset and @seq.step only; got {names}")
         missing = [f.name for f in (SeqFlags.RESET, SeqFlags.STEP) if f not in self.bindings]
         if missing:
             raise ValueError(f"a benchmark marks @seq.reset and @seq.step; {', '.join(missing).lower()} is missing")
-        if self.worlds is not None and SeqFlags.SETUP not in self.bindings:
-            raise ValueError("a vectorized benchmark (@seq.concurrent on its step) builds its worlds in @seq.setup")
+        if self.worlds is not None and not _names_worlds(self.constructor):
+            raise ValueError("a vectorized benchmark (@seq.concurrent on its step) builds its worlds in its "
+                             'constructor, handed how many by init= - init={"worlds": "{num_worlds}"}')
         return self
 
     @model_validator(mode="after")
@@ -132,7 +162,7 @@ class BenchmarkSpec(BaseModel):
 
 class BenchmarkRegisterRequest(BaseModel):
     """POST /v1/benchmarks - what `seq benchmark register` sends: the declaration, the code, and the parameters its
-    @seq.setup takes beside worlds and policy (each settable by an eval's --param, with its type)."""
+    constructor takes with a default beside what init= hands it (each settable by an eval's --param, with its type)."""
 
     model_config = ConfigDict(extra="forbid")
 
@@ -172,9 +202,8 @@ class BenchmarkRegisterRequest(BaseModel):
     @model_validator(mode="after")
     def _param_names(self) -> "BenchmarkRegisterRequest":
         for name in self.params or {}:
-            if not name.isidentifier() or name.startswith("_") or name in ("worlds", "policy"):
-                raise ValueError(f"setup parameter {name!r} is not a public Python identifier other than worlds and "
-                                 "policy")
+            if not name.isidentifier() or name.startswith("_"):
+                raise ValueError(f"parameter {name!r} is not a public Python identifier")
         return self
 
     @model_validator(mode="after")