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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: sequence-base
-Version: 0.4.33
+Version: 0.5.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.4.33 → sequence_base-0.5.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "sequence-base"
-version = "0.4.33"
+version = "0.5.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.4.33 → sequence_base-0.5.0}/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.5.0/sequence_base/constants/cards.py

@@ -0,0 +1,38 @@
+"""The cards a benchmark machine may run on, defined once here: the SDK refuses any other before a benchmark registers
+(and `seq validate` offline, so the list is a constant, not a read), the gateway at registration and at an eval, and
+the harness at the machine it starts - one list where each kept its own.
+
+
+Both cards have RT cores, video encoders, EGL and Vulkan, so a benchmark only picks cheaper or faster; one that names a
+card simulates on it (registration checks). CPU physics is the author's explicit choice, gpu="cpu": CPU machines, one
+environment per core
+.
+
+A deployment's or a benchmark's driver is named here too, beside its card: DRIVER.
+"""
+import re
+
+BENCHMARK_GPUS = ("L4", "RTX-PRO-6000")
+
+DEFAULT_BENCHMARK_GPU = "L4"
+
+BENCHMARK_CPU = "cpu"
+
+
+
+
+
+
+DRIVER = r"^[1-9][0-9]{2}$"
+
+
+def driver_major(version: str | None) -> str | None:
+    """The major version of a driver as nvidia-smi says it ("580.178.04" -> "580"); None for anything that is not one."""
+    head = (version or "").strip().split(".", 1)[0]
+    return head if re.fullmatch(DRIVER, head) else None
+
+
+def check_driver(driver: str | None, card: str | None) -> None:
+    """A driver is a GPU's: one named beside gpu="cpu" is refused."""
+    if driver is not None and (card or "").strip().lower() == BENCHMARK_CPU:
+        raise ValueError('driver= names a GPU driver: a gpu="cpu" machine has none')

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

@@ -4,7 +4,10 @@
 
 
 
-CONTRACT_VERSION = "0.5.29"
+CONTRACT_VERSION = "0.5.32"
+
+
+
 
 
 

{sequence_base-0.4.33 → sequence_base-0.5.0}/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.0/sequence_base/contract/benchmarks.py

@@ -0,0 +1,194 @@
+"""
+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.
+
+
+"""
+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, VolumeRef
+
+__all__ = [
+    "ReplaySpec",
+    "BenchmarkSpec",
+    "BenchmarkRegisterRequest",
+    "BenchmarkStatusResponse",
+]
+
+
+TASK_NAME = r"^[A-Za-z0-9][A-Za-z0-9._/:-]{0,127}$"
+
+
+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 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."""
+
+    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="SETUP / 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)
+
+    @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":
+        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}")
+        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")
+        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
+    @seq.setup takes beside worlds and policy (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("_") or name in ("worlds", "policy"):
+                raise ValueError(f"setup parameter {name!r} is not a public Python identifier other than worlds and "
+                                 "policy")
+        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

sequence_base-0.5.0/sequence_base/contract/connect.py

@@ -0,0 +1,123 @@
+"""
+Contract 3 — connect / lease (client → gateway; control plane, first call + renewal).
+
+Control plane / data plane split: `connect(model)` goes through the gateway once (admission → acquire →
+ensure worker up) and hands back the *direct* coordinates the client then uses to hit the worker's
+`/act` without the gateway in the hot path (contract 4). The cold-start fallback is a defined wire body,
+not an HTTP header alone — a 503 returns `WarmingError` (contract/errors.py), so `503 + Retry-After`
+and the warming ETA are typed and checkable.
+"""
+from __future__ import annotations
+
+from datetime import datetime
+from typing import Any, Literal
+
+from pydantic import BaseModel, ConfigDict, Field, model_validator
+
+
+from sequence_base.contract.errors import WarmingError
+from sequence_base.contract.own_io import Observations
+from sequence_base.contract.retired import dropped
+from sequence_base.contract.team import check_name
+
+__all__ = ["Lease", "ConnectRequest", "ConnectResponse", "Standby", "WarmingError"]
+
+
+class Lease(BaseModel):
+    """A time-boxed grant of the direct coordinates. Renewed before `expires_at`; `epoch` is the
+    worker/secret generation — a client holding a stale epoch against a new worker gets 401 and must
+    re-connect."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    ttl_s: int
+    expires_at: datetime
+    epoch: int = Field(..., description="Worker/secret generation counter; rolls on worker change")
+
+
+class ConnectRequest(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    model: str = Field(..., description="Deployment name to connect to")
+
+
+
+
+    standby: bool = Field(default=False, description="this SDK keeps a standby connection and switches to it")
+
+
+    switched: bool = Field(default=False, description="this robot just switched to the standby copy it was handed")
+
+
+
+
+    team: str | None = Field(default=None, description="the team this robot joins, by name")
+    group: str | None = Field(default=None, description="its group in that team; None: the default group")
+
+    @model_validator(mode="before")
+    @classmethod
+    def _retired(cls, data: Any) -> Any:
+        return dropped(data, "embodiment")
+
+    @model_validator(mode="after")
+    def _a_group_is_a_teams(self) -> "ConnectRequest":
+        if self.team is not None:
+            check_name(self.team, "team")
+        if self.group is not None:
+            if self.team is None:
+                raise ValueError("a group is a team's: say the team too")
+            check_name(self.group, "group")
+        return self
+
+
+class Standby(BaseModel):
+    """The standby copy a connect hands a robot whose SDK keeps one (ConnectRequest.standby): another worker of the
+    deployment, on another machine, holding a place for it - no seat: its acts go there only once the copy it is on
+    cannot be reached, and its next connect says it switched. Its coordinates as the primary's are: where to send, how to
+    check its certificate (pinned by cert_fingerprint, or "public" for tls_name, masked as the primary's) and the bearer
+    and lease its acts carry."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    worker_url: str = Field(..., description="The standby worker's direct URL")
+
+
+    cert_fingerprint: str | None = Field(..., description="Its certificate's fingerprint the SDK pins; null where "
+                                                       "tls is public")
+    direct_secret: str = Field(..., description="Bearer for its /act; valid within its lease")
+    tls: Literal["pinned", "public"] = Field(default="pinned", description="how its certificate is checked")
+    tls_name: str | None = Field(default=None, description="the name a public certificate is checked for, masked")
+    lease: Lease
+
+
+class ConnectResponse(BaseModel):
+    """200 — the full set of coordinates for a direct worker connection.
+
+    `direct_secret` is a plaintext platform-minted bearer for the worker's `/act`; it is on the
+    allow-list of fields permitted to carry a secret value in the down direction (contract 6 / goal 15)."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    worker_url: str = Field(..., description="Worker static-IP direct URL, e.g. https://<ip>:8080")
+    cert_fingerprint: str = Field(..., description="Self-signed cert fingerprint the SDK pins")
+    direct_secret: str = Field(..., description="Bearer for the worker /act; valid within the lease")
+    lease: Lease
+
+
+    hz: float | None = Field(default=None, gt=0, le=1000)
+    action_chunk_len: int | None = Field(default=None, ge=1, le=100_000)
+    action_chunk_exec_len: int | None = Field(default=None, ge=1, le=100_000)
+
+    io: str | None = None
+
+
+    observations: Observations | None = None
+
+
+    standby: Standby | None = None
+
+    @model_validator(mode="before")
+    @classmethod
+    def _retired(cls, data: Any) -> Any:
+
+        return dropped(data, "embodiment", "feedback", "action", "observation", "actions")