sequence-base 0.4.25__tar.gz → 0.4.27__tar.gz

{sequence_base-0.4.25 → sequence_base-0.4.27}/PKG-INFO

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

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

@@ -21,9 +21,14 @@ from sequence_base.contract import (
     FROZEN_PATH,
     TemplateFiles,
     ImageStepTemplateFiles,
+    Project,
+    ImageStepProject,
     Camera,
     Embodiment,
     ObservationContract,
+    ObserveFrame,
+    ObserveRequest,
+    ObserveResponse,
     MAX_CODE_BUNDLE_BYTES,
     UploadTarget,
     VolumeFile,
@@ -79,6 +84,10 @@ from sequence_base.contract import (
     PolicyConstructor,
     PolicyRegistration,
     PolicySpec,
+    Observations,
+    Stream,
+    Actions,
+    Tensors,
     Proprioception,
     RenderSpec,
     ReplaySpec,
@@ -118,6 +127,9 @@ from sequence_base.errors.transport import (
 )
 
 
+from sequence_base.episode import Episode
+
+
 from sequence_base import auth
 
 
@@ -129,11 +141,13 @@ __all__ = [
 
     "ImageFrame", "Proprioception", "Observation", "ActionSpace", "ActionStep", "ActionChunk",
     "ActRequest", "ActResponse",
+    "ObserveFrame", "ObserveRequest", "ObserveResponse",
 
     "SeqFlags", "ImageStepUvPip", "ImageStepApt", "ImageStepEnv", "ImageStepRun", "AddLocal", "ImageStepAddLocal",
-    "FROZEN_PATH", "TemplateFiles", "ImageStepTemplateFiles", "ImageStep", "ImageSpec",
+    "FROZEN_PATH", "TemplateFiles", "ImageStepTemplateFiles", "Project", "ImageStepProject", "ImageStep", "ImageSpec",
     "VolumeMount", "VolumeRef", "Concurrency", "ActionContract", "Camera", "ObservationContract", "Embodiment",
     "PolicySpec", "PolicyRegistration", "PolicyConstructor",
+    "Observations", "Stream", "Actions", "Tensors",
 
     "MAX_CODE_BUNDLE_BYTES", "CodeBundle",
     "Resources", "Autoscaler", "Timeouts", "DeploymentPolicy", "InferParam", "DeploymentRequest",
@@ -160,6 +174,8 @@ __all__ = [
 
     "TransportUnavailable", "TransportWarming", "TransportRejected", "TransportOverloaded",
 
+    "Episode",
+
     "auth",
 ]
 

{sequence_base-0.4.25 → sequence_base-0.4.27}/sequence_base/constants/limits.py

@@ -28,3 +28,12 @@ TASK_DESCRIPTION_MAX = 300
 METRIC_UNITS_MAX = 64
 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

{sequence_base-0.4.25 → sequence_base-0.4.27}/sequence_base/constants/version.py

@@ -4,7 +4,9 @@
 
 
 
-CONTRACT_VERSION = "0.5.22"
+CONTRACT_VERSION = "0.5.24"
+
+
 
 
 

{sequence_base-0.4.25 → sequence_base-0.4.27}/sequence_base/contract/__init__.py

@@ -15,6 +15,8 @@ from sequence_base.contract.act import (
 
 from sequence_base.contract.wire import ActRequest, ActResponse
 
+from sequence_base.contract.observe import ObserveFrame, ObserveRequest, ObserveResponse
+
 
 from sequence_base.contract.flags import SeqFlags
 from sequence_base.contract.policy import (
@@ -34,6 +36,8 @@ from sequence_base.contract.policy import (
     FROZEN_PATH,
     TemplateFiles,
     ImageStepTemplateFiles,
+    ImageStepProject,
+    Project,
     PolicyConstructor,
     PolicyRegistration,
     PolicySpec,
@@ -42,6 +46,9 @@ from sequence_base.contract.policy import (
 )
 
 
+from sequence_base.contract.own_io import Actions, Observations, Stream, Tensors
+
+
 from sequence_base.contract.deployments import (
     MAX_CODE_BUNDLE_BYTES,
     Autoscaler,
@@ -117,12 +124,14 @@ __all__ = [
 
     "ImageFrame", "Proprioception", "Observation", "ActionSpace", "ActionStep", "ActionChunk",
     "ActRequest", "ActResponse",
+    "ObserveFrame", "ObserveRequest", "ObserveResponse",
 
     "SeqFlags",
     "ImageStepUvPip", "ImageStepApt", "ImageStepEnv", "ImageStepRun", "AddLocal", "ImageStepAddLocal",
-    "TemplateFiles", "ImageStepTemplateFiles", "FROZEN_PATH", "ImageStep", "ImageSpec",
+    "TemplateFiles", "ImageStepTemplateFiles", "Project", "ImageStepProject", "FROZEN_PATH", "ImageStep", "ImageSpec",
     "VolumeMount", "VolumeRef", "Concurrency", "ActionContract", "Camera", "ObservationContract", "Embodiment",
     "PolicySpec", "PolicyRegistration", "PolicyConstructor",
+    "Observations", "Stream", "Actions", "Tensors",
 
     "MAX_CODE_BUNDLE_BYTES", "CodeBundle",
     "Resources", "Autoscaler", "Timeouts", "DeploymentPolicy", "InferParam", "DeploymentRequest",

{sequence_base-0.4.25 → sequence_base-0.4.27}/sequence_base/contract/connect.py

@@ -16,6 +16,7 @@ from pydantic import BaseModel, ConfigDict, Field
 
 from sequence_base.contract.errors import WarmingError
 from sequence_base.contract.io import ActionContract, ObservationContract
+from sequence_base.contract.own_io import Actions, Observations
 
 __all__ = ["Lease", "ConnectRequest", "ConnectResponse", "WarmingError"]
 
@@ -57,3 +58,7 @@ class ConnectResponse(BaseModel):
     embodiment: str | None = None
 
     io: str | None = None
+
+
+    observations: Observations | None = None
+    actions: Actions | None = None

{sequence_base-0.4.25 → sequence_base-0.4.27}/sequence_base/contract/deployments.py

@@ -22,10 +22,12 @@ from pydantic import BaseModel, ConfigDict, Field, field_validator, model_valida
 
 from sequence_base.contract.accounts import SecretRef
 from sequence_base.contract.io import Embodiment, ObservationContract
+from sequence_base.contract.own_io import Actions, Observations, Tensors, check_own_io
 from sequence_base.contract.policy import (
     KIND_NAME,
     ActionContract,
     Concurrency,
+    Episodes,
     ImageSpec,
     VolumeMount,
 )
@@ -105,6 +107,11 @@ class Timeouts(BaseModel):
     startup: int = Field(..., ge=60, le=18000)
 
 
+
+
+    episode_idle: int | None = Field(default=None, ge=10, le=86400)
+
+
 class InferParam(BaseModel):
     """One inference parameter the policy's `@seq.infer` declares — `def infer(self, obs, *, num_steps: int = 10)`
     — with its type and default. An /act or an eval may set it; the worker passes only declared names, cast to
@@ -171,7 +178,12 @@ class DeploymentPolicy(BaseModel):
 
     handler_ref: str
     action: ActionContract | None = None
-    streaming: bool = False
+
+
+    episodes: Episodes | None = None
+
+
+    streaming: bool = Field(default=False, exclude=True)
     secrets: list[SecretRef] = Field(default_factory=list)
 
 
@@ -208,11 +220,29 @@ class DeploymentPolicy(BaseModel):
     own_observations: Literal["latest", "since_last_act"] | None = None
     own_actions: Literal["one", "steps"] | None = None
 
+
+
+    observations: Observations | None = None
+    actions: Actions | None = None
+    tensors: Tensors | None = None
+
+    @model_validator(mode="after")
+    def _episodes_of_streaming(self) -> "DeploymentPolicy":
+
+        if self.streaming and self.episodes not in (None, "own"):
+            raise ValueError(f"streaming is what a record from before contract 0.5.24 says; beside "
+                             f"episodes={self.episodes!r}, leave it out")
+        if self.streaming:
+            self.episodes = "own"
+        self.streaming = self.episodes == "own"
+        return self
+
     @model_validator(mode="after")
     def _own_io(self) -> "DeploymentPolicy":
         if (self.own_observations or self.own_actions) and (self.action or self.observation or self.embodiments):
             raise ValueError("own_observations and own_actions are for a policy of its own inputs and outputs; this one "
                              "declares the robot-arm contract, where observation history and the action chunk say it")
+        check_own_io(self)
         return self
 
     @model_validator(mode="after")

{sequence_base-0.4.25 → sequence_base-0.4.27}/sequence_base/contract/flags.py

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

sequence_base-0.4.27/sequence_base/contract/observe.py

@@ -0,0 +1,65 @@
+"""
+The observation stream: a policy of its own inputs that reads every observation since its last act is sent each one as
+the robot makes it, on a connection of its own (POST /observe), and an act carries only the newest.
+
+In one sentence: the robot's SDK numbers each observation of an episode from 0 → posts them as they come, each post the
+ones that came while the last was on its way (ObserveRequest) → the worker keeps them by episode and answers how far it
+has every one (ObserveResponse.through) → an act carries the newest observation and its number (ActRequest.seq) → the
+worker waits for the ones before it, STREAM_WAIT_S at most, and hands the policy {"observations": [...]}, oldest first,
+the act's own last - what an eval's since_last_act sends in one act today.
+
+WHY: an act was the only upload, so every frame between two acts waited for the next one - 24 frames, 1304 KB and a read
+p50 of 425 ms from a robot at home. Sent as they are made, they
+are on the worker before the act is.
+
+What a policy declares of what it reads (its cameras, how many a second, when its upload falls behind) is plan 87's
+first layer, which waits for the comparison of each part (the user's 69): the stream here is the transport alone, for
+a policy that declares own_observations "since_last_act".
+
+"""
+from __future__ import annotations
+
+from typing import Any
+
+from pydantic import BaseModel, ConfigDict, Field
+
+__all__ = ["FORMAT", "FRAMES_MISSING", "FRAMES_OVER_LIMIT", "ObserveFrame", "ObserveRequest", "ObserveResponse"]
+
+
+
+FORMAT = "x-seq-observe/1"
+
+
+
+
+FRAMES_MISSING = "frames_missing"
+FRAMES_OVER_LIMIT = "frames_over_limit"
+
+
+class ObserveFrame(BaseModel):
+    """One observation of an episode: its number in it, from 0, and the inputs, as the policy's infer() takes one."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    seq: int = Field(..., ge=0, description="The observation's number in its episode, from 0")
+    inputs: Any = Field(..., description="One observation, exactly as the robot's code built it")
+
+
+class ObserveRequest(BaseModel):
+    """POST /observe: the observations of one episode that came since the last post, and the numbers the robot left out
+    on purpose, which the worker then does not wait for."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    episode_id: str = Field(..., min_length=1, max_length=256)
+    frames: list[ObserveFrame] = Field(default_factory=list)
+    skipped: list[int] = Field(default_factory=list, description="Numbers left out on purpose, never to come")
+
+
+class ObserveResponse(BaseModel):
+    """200 from POST /observe: the highest number up to which the worker holds every observation of the episode, or has
+    been told one is skipped (-1: none yet). A number sent again is answered the same, never kept twice."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    through: int = Field(..., ge=-1)

sequence_base-0.4.27/sequence_base/contract/own_io.py

@@ -0,0 +1,179 @@
+"""
+What a policy of its own inputs and outputs declares (contract 0.5.24): which keys of an observation it reads and at
+which steps, a camera's frames as it was trained to see them, which rows of its answer play and how fast, and whether
+its inputs reach it as torch tensors. Each part is optional; a policy that declares none is sent and handed what it is
+today.
+
+In one sentence: `Observations` names the keys a policy reads, each a `Stream` - read at the act's step and the offsets
+in `at` before it (a window the worker keeps), or handed every `every` steps since the last act (fed: the policy keeps
+its own history) - counted in steps or seconds (`unit`) → the robot and the eval send, and a benchmark renders, only
+those steps → infer is handed {"observations": [...], "steps": [...]}, oldest first, the act's own last; `Actions` says
+which field of the answer holds the rows, how many a second they play (`hz`) and how many play before the next act
+(`open_loop_horizon`), so a worker can time a copy's robots by them.
+
+WHY by key and not by kind of input: every policy, benchmark and serving framework read for the user's 69 names its
+inputs and gives each its own schedule - GR00T DROID reads its cameras at t and t-15 and its state at t alone - and what
+breaks a policy is a frame fitted or encoded other than it was trained on, which a kind of input does not say and a
+`Camera` does.
+
+"""
+from __future__ import annotations
+
+import math
+from typing import Any, Literal
+
+from pydantic import BaseModel, ConfigDict, Field, field_validator, model_validator
+
+from sequence_base.presets.robot_arm import Camera
+
+__all__ = ["Actions", "MAX_STREAMS", "MAX_WINDOW", "Observations", "Stream", "Tensors", "check_own_io"]
+
+
+
+MAX_STREAMS = 64
+MAX_WINDOW = 256
+
+
+def _counts(v: Any, what: str) -> None:
+
+    if isinstance(v, bool) or not isinstance(v, (int, float)) or not math.isfinite(v):
+        raise ValueError(f"{what} is a number of steps or seconds, got {v!r}")
+
+
+class Stream(BaseModel):
+    """One key of the observation a policy reads. `at`: the offsets before the act's step it reads at each act, 0 the
+    act's own - a window the worker keeps, so the policy keeps none. `every`: handed every that many steps since its last
+    act, the act's own always among them - fed, the policy keeping its own history. Neither: the act's step alone.
+    `camera`: the key is a camera's frame, read at its width x height - fitted by `resize` and `filter` before it is sent
+    when both are declared, sent as `codec` says (unset: as the robot sent it), decoded in the replica to HWC uint8, or
+    CHW float in 0..1 for layout "chw_float", before the policy's code."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    at: list[int | float] | None = Field(default=None, min_length=1, max_length=MAX_WINDOW,
+                                         description="offsets before the act's step, each 0 or below")
+    every: int | float | None = Field(default=None, gt=0, description="handed every this many steps since the last act")
+    camera: Camera | None = None
+
+    @field_validator("at", mode="before")
+    @classmethod
+    def _offsets_as_given(cls, v: Any) -> Any:
+        for x in v if isinstance(v, list) else ():
+            _counts(x, "an offset in at=")
+        return v
+
+    @field_validator("at")
+    @classmethod
+    def _window(cls, v: list[int | float] | None) -> list[int | float] | None:
+        if v is None:
+            return v
+        if any(x > 0 for x in v):
+            raise ValueError("at= holds offsets before the act's step: each 0 (the act's own) or below")
+        if len(set(v)) != len(v):
+            raise ValueError("at= names each offset once")
+        return sorted(v)
+
+    @field_validator("every", mode="before")
+    @classmethod
+    def _fed(cls, v: Any) -> Any:
+        if v is not None:
+            _counts(v, "every=")
+        return v
+
+    @model_validator(mode="after")
+    def _one_schedule(self) -> "Stream":
+        if self.at is not None and self.every is not None:
+            raise ValueError("a key is read at= offsets of each act (the worker keeps them) or every= so many steps "
+                             "(the policy keeps them), not both")
+        return self
+
+
+class Observations(BaseModel):
+    """What a policy of its own inputs reads of each observation, and when. `streams`: the keys it reads, each a Stream;
+    only these are sent. None: the whole observation, as the robot built it. `every`: the whole observation handed every
+    that many steps since the last act (fed, no keys named). `unit`: what `at` and `every` count - "steps", an episode's
+    control steps from 0 (one action played on a robot, one env step in an eval), or "seconds", taken to steps by the
+    robot's or the benchmark's control rate. `pad`: a window's step before the episode's first reads as its first
+    ("repeat_first") or is left out ("drop"). `when_behind`: what the robot does when its upload falls behind - "wait",
+    losing none, or "drop_oldest". Declared, infer is handed {"observations": [...], "steps": [...]}: each observation
+    the keys read at its step, oldest first, the act's own last."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    streams: dict[str, Stream] | None = Field(default=None, max_length=MAX_STREAMS)
+    every: int | float | None = Field(default=None, gt=0)
+    unit: Literal["steps", "seconds"] = "steps"
+    pad: Literal["repeat_first", "drop"] = "repeat_first"
+    when_behind: Literal["wait", "drop_oldest"] = "wait"
+
+    @field_validator("streams")
+    @classmethod
+    def _keys(cls, v: dict[str, Stream] | None) -> dict[str, Stream] | None:
+        for key in v or {}:
+            if not key or len(key) > 128 or key != key.strip():
+                raise ValueError(f"stream {key!r} is not a key of an observation: 1 to 128 characters, no blanks around")
+        return v
+
+    @field_validator("every", mode="before")
+    @classmethod
+    def _fed(cls, v: Any) -> Any:
+        if v is not None:
+            _counts(v, "every=")
+        return v
+
+    @model_validator(mode="after")
+    def _counted(self) -> "Observations":
+        if self.streams is not None and self.every is not None:
+            raise ValueError("Observations(every=...) hands the whole observation; with keys named, give each key its "
+                             "own Stream(every=...)")
+        if self.unit == "steps":
+            named = [("every=", self.every)]
+            for key, stream in (self.streams or {}).items():
+                named += [(f"{key!r} every=", stream.every)] + [(f"{key!r} at=", x) for x in stream.at or []]
+            for what, x in named:
+                if x is not None and not isinstance(x, int):
+                    raise ValueError(f"unit 'steps' counts whole steps and {what}{x!r} is not one; for a time, write "
+                                     "unit='seconds'")
+        return self
+
+
+class Actions(BaseModel):
+    """Which rows of a policy's answer play. `key`: the answer's field that holds them (None: the answer itself) - a
+    list of rows or a 2-D array, played in order, `hz` rows a second, `open_loop_horizon` of them before the next act
+    (None: all). A shorter answer plays whole and the next act comes sooner; a longer one is cut there. With `hz` a worker
+    knows how long one answer plays (open_loop_horizon / hz) and a control period (1 / hz) and times a copy's robots by
+    them, as a robot-arm chunk's covers_seconds and control_frequency_hz do. Undeclared, an answer plays as the default
+    says: a dict or a 1-D list one action, a 2-D one row by row."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    key: str | None = Field(default=None, min_length=1, max_length=128)
+    hz: float | None = Field(default=None, gt=0, le=1000)
+    open_loop_horizon: int | None = Field(default=None, ge=1, le=100_000)
+
+
+class Tensors(BaseModel):
+    """A policy's inputs reach its code as torch tensors on its device - a batch dimension first when `batch` - and the
+    tensors it answers with go back as arrays; float64 arrays arrive as float32. Converted in the replica, last before
+    the policy's code; how a camera's frame is laid out is its Stream's camera.layout."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    batch: bool = True
+
+
+def check_own_io(spec: Any) -> None:
+    """What PolicySpec and DeploymentPolicy both hold a policy's own-I/O declarations to: none beside the robot-arm
+    contract, which says what it reads and plays its own way, and the 0.5.24 ones (observations / actions / tensors)
+    not beside own_observations / own_actions, which they take over from."""
+    new = [name for name in ("observations", "actions", "tensors") if getattr(spec, name) is not None]
+    if not new:
+        return
+    if spec.action or spec.observation or spec.embodiments:
+        raise ValueError(f"{', '.join(new)} {'is' if len(new) == 1 else 'are'} for a policy of its own inputs and "
+                         "outputs; this one declares the robot-arm contract, where observation history and the action "
+                         "chunk say it")
+    old = [name for name in ("own_observations", "own_actions") if getattr(spec, name)]
+    if old:
+        raise ValueError(f"{', '.join(new)} and {', '.join(old)} say what a policy reads and plays two ways; declare "
+                         "observations= and actions= alone")