sequence-base 0.4.34__tar.gz → 0.5.1__tar.gz

{sequence_base-0.4.34 → sequence_base-0.5.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: sequence-base
-Version: 0.4.34
+Version: 0.5.1
 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.4.34 → sequence_base-0.5.1}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "sequence-base"
-version = "0.4.34"
+version = "0.5.1"
 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.4.34 → sequence_base-0.5.1}/sequence_base/__init__.py

@@ -37,6 +37,11 @@ from sequence_base.contract import (
     parse_vol,
     TEMPLATE_SCHEME,
     parse_template,
+    SETTINGS,
+    Setting,
+    SettingsChange,
+    SettingsView,
+    SettingsChanged,
     AdapterPair,
     parse_pairs,
     ActionChunk,
@@ -44,14 +49,12 @@ from sequence_base.contract import (
     ActionSpace,
     ActionStep,
     Autoscaler,
-    BenchmarkConditionSpec,
     BenchmarkRegisterRequest,
     BenchmarkStatusResponse,
     BenchmarkSpec,
     BootstrapResponse,
     CodeBundle,
     Concurrency,
-    Conditions,
     ConnectRequest,
     ConnectResponse,
     DeploymentAccepted,
@@ -85,10 +88,8 @@ from sequence_base.contract import (
     PolicySpec,
     Observations,
     Stream,
-    Actions,
     Tensors,
     Proprioception,
-    RenderSpec,
     ReplaySpec,
     Resources,
     RolloutResult,
@@ -96,10 +97,8 @@ from sequence_base.contract import (
     SecretInfo,
     SecretRef,
     SeqFlags,
-    Step,
     TaskAgg,
     Timeouts,
-    Variant,
     VolumeMount,
     VolumeRef,
     WarmingError,
@@ -146,7 +145,7 @@ __all__ = [
     "FROZEN_PATH", "TemplateFiles", "ImageStepTemplateFiles", "Project", "ImageStepProject", "ImageStep", "ImageSpec",
     "VolumeMount", "VolumeRef", "Concurrency", "ActionContract", "Camera", "ObservationContract",
     "PolicySpec", "PolicyRegistration", "PolicyConstructor",
-    "Observations", "Stream", "Actions", "Tensors",
+    "Observations", "Stream", "Tensors",
 
     "MAX_CODE_BUNDLE_BYTES", "CodeBundle",
     "Resources", "Autoscaler", "Timeouts", "DeploymentPolicy", "InferParam", "DeploymentRequest",
@@ -154,7 +153,7 @@ __all__ = [
 
     "Lease", "ConnectRequest", "ConnectResponse",
 
-    "Variant", "Conditions", "RenderSpec", "ReplaySpec", "Step", "BenchmarkSpec", "BenchmarkConditionSpec", "BenchmarkRegisterRequest", "BenchmarkStatusResponse",
+    "ReplaySpec", "BenchmarkSpec", "BenchmarkRegisterRequest", "BenchmarkStatusResponse",
     "EvalRequest", "Estimate", "EvalResponse", "EvalDryRunResponse", "RolloutResult",
     "EvalStatus", "TaskAgg", "MetricAgg", "EvalReport",
 
@@ -162,6 +161,8 @@ __all__ = [
 
     "VolumeFile", "VolumeUploadRequest", "UploadTarget", "VolumeUploadResponse", "VolumeInfo", "parse_vol",
 
+    "SETTINGS", "Setting", "SettingsChange", "SettingsView", "SettingsChanged",
+
     "TEMPLATE_SCHEME", "parse_template",
 
     "AdapterPair", "parse_pairs",

{sequence_base-0.4.34 → sequence_base-0.5.1}/sequence_base/constants/version.py

@@ -4,7 +4,10 @@
 
 
 
-CONTRACT_VERSION = "0.5.30"
+CONTRACT_VERSION = "0.5.33"
+
+
+
 
 
 

sequence_base-0.5.1/sequence_base/construct.py

@@ -0,0 +1,173 @@
+"""
+How a class built by its constructor is built - a policy's or a team'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.4.34 → sequence_base-0.5.1}/sequence_base/contract/__init__.py

@@ -45,7 +45,7 @@ from sequence_base.contract.policy import (
 )
 
 
-from sequence_base.contract.own_io import Actions, Observations, Stream, Tensors
+from sequence_base.contract.own_io import Observations, Stream, Tensors
 
 
 from sequence_base.contract.deployments import (
@@ -63,19 +63,14 @@ from sequence_base.contract.deployments import (
 )
 
 
-from sequence_base.contract.connect import ConnectRequest, ConnectResponse, Lease
+from sequence_base.contract.connect import ConnectRequest, ConnectResponse, Lease, Standby
 
 
 from sequence_base.contract.benchmarks import (
-    BenchmarkConditionSpec,
     BenchmarkRegisterRequest,
     BenchmarkStatusResponse,
     BenchmarkSpec,
-    Conditions,
-    RenderSpec,
     ReplaySpec,
-    Step,
-    Variant,
 )
 from sequence_base.contract.eval import (
     Estimate,
@@ -117,6 +112,35 @@ from sequence_base.contract.volumes import (
 )
 
 
+from sequence_base.contract.settings import (
+    SETTINGS,
+    Applied,
+    Setting,
+    SettingChanged,
+    SettingState,
+    SettingsChange,
+    SettingsChanged,
+    SettingsView,
+)
+
+
+from sequence_base.contract.team import (
+    TEAM_DEFAULT_GROUP,
+    GroupObservation,
+    GroupObserve,
+    GroupObserved,
+    PlanAppend,
+    PlanAppended,
+    TeamGroup,
+    TeamGroups,
+    TeamGroupsRequest,
+    TeamMember,
+    TeamPlans,
+    TeamPlansWritten,
+    TeamSpec,
+)
+
+
 from sequence_base.contract.errors import ERRORS, ErrorBody, ErrorCode, ErrorSpec, WarmingError, code_for_status
 
 __all__ = [
@@ -130,15 +154,15 @@ __all__ = [
     "TemplateFiles", "ImageStepTemplateFiles", "Project", "ImageStepProject", "FROZEN_PATH", "ImageStep", "ImageSpec",
     "VolumeMount", "VolumeRef", "Concurrency", "ActionContract", "Camera", "ObservationContract",
     "PolicySpec", "PolicyRegistration", "PolicyConstructor",
-    "Observations", "Stream", "Actions", "Tensors",
+    "Observations", "Stream", "Tensors",
 
     "MAX_CODE_BUNDLE_BYTES", "CodeBundle",
     "Resources", "Autoscaler", "Timeouts", "DeploymentPolicy", "InferParam", "DeploymentRequest",
     "DeploymentAccepted", "DeploymentState", "DeploymentStatusResponse",
 
-    "Lease", "ConnectRequest", "ConnectResponse",
+    "Lease", "ConnectRequest", "ConnectResponse", "Standby",
 
-    "Variant", "Conditions", "RenderSpec", "ReplaySpec", "Step", "BenchmarkSpec", "BenchmarkConditionSpec", "BenchmarkRegisterRequest", "BenchmarkStatusResponse",
+    "ReplaySpec", "BenchmarkSpec", "BenchmarkRegisterRequest", "BenchmarkStatusResponse",
     "EvalRequest", "Estimate", "EvalResponse", "EvalDryRunResponse", "RolloutResult",
     "EvalStatus", "TaskAgg", "MetricAgg", "EvalReport",
 
@@ -147,6 +171,12 @@ __all__ = [
     "MAX_FILES", "MAX_UPLOAD_BYTES", "VolumeFile", "VolumeUploadRequest", "UploadTarget", "VolumeUploadResponse",
     "VolumeInfo", "check_volume_name", "parse_vol",
 
+    "SETTINGS", "Setting", "SettingsChange", "Applied", "SettingState", "SettingsView", "SettingChanged",
+    "SettingsChanged",
+
+    "TEAM_DEFAULT_GROUP", "TeamSpec", "TeamGroupsRequest", "GroupObservation", "TeamMember", "TeamGroup", "TeamGroups",
+    "TeamPlans", "TeamPlansWritten", "PlanAppend", "PlanAppended", "GroupObserve", "GroupObserved",
+
     "TEMPLATE_SCHEME", "parse_template",
 
     "AdapterPair", "parse_pairs",

sequence_base-0.5.1/sequence_base/contract/benchmarks.py

@@ -0,0 +1,223 @@
+"""
+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.
+
+
+"""
+from __future__ import annotations
+
+from typing import Literal
+
+from pydantic import BaseModel, ConfigDict, Field, model_validator
+
+from sequence_base.constants.cards import DRIVER, check_driver
+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, PolicyConstructor, VolumeRef
+from sequence_base.construct import FORMS
+
+__all__ = [
+    "ReplaySpec",
+    "BenchmarkSpec",
+    "BenchmarkRegisterRequest",
+    "BenchmarkStatusResponse",
+]
+
+
+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
+
+    if not tasks:
+        raise ValueError("tasks names at least one task: {name: description}")
+    for name, text in tasks.items():
+        if not _re.match(TASK_NAME, name):
+            raise ValueError(f"task {name!r}: 1-128 letters, digits, '.', '_', '/', ':' or '-', starting with a letter "
+                             "or digit")
+        if len(text or "") > TASK_DESCRIPTION_MAX:
+            raise ValueError(f"tasks[{name!r}] is {len(text)} characters: at most {TASK_DESCRIPTION_MAX}")
+    if not seeds:
+        raise ValueError("seeds names at least one seed")
+    if len(set(seeds)) != len(seeds):
+        raise ValueError("seeds names each seed once")
+    limits = max_seconds if isinstance(max_seconds, dict) else {"": max_seconds}
+    for task, limit in limits.items():
+        if task and task not in tasks:
+            raise ValueError(f"max_seconds names {task!r}, which is not one of its tasks")
+        if not limit > 0:
+            raise ValueError(f"max_seconds{'[' + repr(task) + ']' if task else ''} must be above 0 s, not {limit!r}")
+
+
+class ReplaySpec(BaseModel):
+    """a.k.a. `seq.Replay` — declares that the platform records the eval's 3D replay: each step every node's world
+    transform, drawn in the owner's browser after the eval. `engine` picks the platform's
+    adapter that reads the simulation's state ("mujoco", "sapien", "isaac"); "own" means the benchmark hands the frames itself
+    (`seq.replay.scene` / `seq.replay.frame`); None takes the benchmark's own `engine`. `state` names the benchmark
+    method an adapter calls for the engine's state of an env (or of a batched benchmark's slots), `looks` the one that
+    says what the adapter cannot read - a colour or a visibility each episode sets. Whether an eval records it is the
+    eval's `replay` ("3d" by default, "none")."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    engine: Literal["mujoco", "sapien", "isaac", "own"] | None = Field(
+        None, description="The adapter that reads the simulation: 'mujoco' (incl. MuJoCo Warp), 'sapien', 'isaac', or "
+                          "'own' (the benchmark hands frames itself); None: the benchmark's engine")
+    state: str | None = Field(None, pattern=r"^[A-Za-z_][A-Za-z0-9_]*$",
+                              description="The benchmark method an adapter calls for an env's (or slots') engine state")
+    looks: str | None = Field(None, pattern=r"^[A-Za-z_][A-Za-z0-9_]*$",
+                              description="The benchmark method that says each episode's colours or visibility")
+
+
+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; `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")
+
+    name: str
+    image: ImageSpec
+    tasks: dict[str, str] = Field(..., description="Each task's name and what it asks of the robot, shown beside it")
+    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="RESET / STEP -> method name")
+
+
+    worlds: int | None = Field(default=None, ge=1, le=MAX_ENVS)
+
+    gpu: str | None = None
+
+    driver: str | None = Field(default=None, pattern=DRIVER)
+    assets: list[VolumeRef] = Field(default_factory=list)
+
+    replay: ReplaySpec | None = None
+    cpu: int | None = None
+    memory_gb: int | None = None
+    secrets: list[SecretRef] = Field(default_factory=list)
+
+    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)
+        return self
+
+    @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.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 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")
+    def _driver_of_a_card(self) -> "BenchmarkSpec":
+        check_driver(self.driver, self.gpu)
+        return self
+
+
+class BenchmarkRegisterRequest(BaseModel):
+    """POST /v1/benchmarks - what `seq benchmark register` sends: the declaration, the code, and the parameters its
+    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")
+
+    name: str
+    image: ImageSpec
+    tasks: dict[str, str]
+    seeds: list[int]
+    max_seconds: float | dict[str, float]
+    handler_ref: str
+    worlds: int | None = Field(default=None, ge=1, le=MAX_ENVS)
+    assets: list[VolumeRef] = Field(default_factory=list)
+    replay: ReplaySpec | None = None
+    cpu: int | None = None
+    memory_gb: int | None = None
+
+    code: CodeBundle | None = None
+
+    freeze: bool | None = None
+    secrets: list[SecretRef] = Field(default_factory=list)
+    gpu: str | None = Field(default=None, max_length=32)
+
+
+    driver: str | None = Field(default=None, pattern=DRIVER,
+                               description='The NVIDIA driver its card must have, by major version: "580"')
+
+
+    params: dict[str, InferParam] | None = Field(default=None, max_length=32)
+
+    image_context: CodeBundle | None = None
+    engine: str | None = Field(default=None, pattern=KIND_NAME)
+
+    @model_validator(mode="after")
+    def _tasks(self) -> "BenchmarkRegisterRequest":
+        _check_tasks(self.tasks, self.seeds, self.max_seconds)
+        return self
+
+    @model_validator(mode="after")
+    def _param_names(self) -> "BenchmarkRegisterRequest":
+        for name in self.params or {}:
+            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")
+    def _driver_of_a_card(self) -> "BenchmarkRegisterRequest":
+        check_driver(self.driver, self.gpu)
+        return self
+
+
+class BenchmarkStatusResponse(BaseModel):
+    """GET /v1/benchmarks/{name} — the build state of a registered benchmark (same lifecycle as a deployment:
+    building → ready | failed), with the failure reason when failed."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    name: str
+    status: DeploymentState
+    error: str | None = None