sequence-base 0.4.26__tar.gz → 0.4.28__tar.gz

{sequence_base-0.4.26 → sequence_base-0.4.28}/PKG-INFO

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

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

@@ -26,6 +26,9 @@ from sequence_base.contract import (
     Camera,
     Embodiment,
     ObservationContract,
+    ObserveFrame,
+    ObserveRequest,
+    ObserveResponse,
     MAX_CODE_BUNDLE_BYTES,
     UploadTarget,
     VolumeFile,
@@ -81,6 +84,10 @@ from sequence_base.contract import (
     PolicyConstructor,
     PolicyRegistration,
     PolicySpec,
+    Observations,
+    Stream,
+    Actions,
+    Tensors,
     Proprioception,
     RenderSpec,
     ReplaySpec,
@@ -120,6 +127,9 @@ from sequence_base.errors.transport import (
 )
 
 
+from sequence_base.episode import Episode
+
+
 from sequence_base import auth
 
 
@@ -131,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", "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",
@@ -162,6 +174,8 @@ __all__ = [
 
     "TransportUnavailable", "TransportWarming", "TransportRejected", "TransportOverloaded",
 
+    "Episode",
+
     "auth",
 ]
 

{sequence_base-0.4.26 → sequence_base-0.4.28}/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.26 → sequence_base-0.4.28}/sequence_base/constants/version.py

@@ -4,7 +4,10 @@
 
 
 
-CONTRACT_VERSION = "0.5.23"
+CONTRACT_VERSION = "0.5.25"
+
+
+
 
 
 

{sequence_base-0.4.26 → sequence_base-0.4.28}/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 (
@@ -44,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,
@@ -119,12 +124,14 @@ __all__ = [
 
     "ImageFrame", "Proprioception", "Observation", "ActionSpace", "ActionStep", "ActionChunk",
     "ActRequest", "ActResponse",
+    "ObserveFrame", "ObserveRequest", "ObserveResponse",
 
     "SeqFlags",
     "ImageStepUvPip", "ImageStepApt", "ImageStepEnv", "ImageStepRun", "AddLocal", "ImageStepAddLocal",
     "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.26 → sequence_base-0.4.28}/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.26 → sequence_base-0.4.28}/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)
 
 
@@ -204,15 +216,24 @@ class DeploymentPolicy(BaseModel):
 
 
 
+    observations: Observations | None = None
+    actions: Actions | None = None
+    tensors: Tensors | None = None
 
-    own_observations: Literal["latest", "since_last_act"] | None = None
-    own_actions: Literal["one", "steps"] | 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.26 → sequence_base-0.4.28}/sequence_base/contract/flags.py

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

sequence_base-0.4.28/sequence_base/contract/obs_schedule.py

@@ -0,0 +1,170 @@
+"""
+Which steps of an episode a policy of its own inputs is handed at an act, and which keys of each: its Observations
+(contract.own_io) read for one act - the one rule a worker hands a robot's streamed frames by
+, an eval hands its benchmark's by (obs_history), and a robot's SDK uploads by.
+
+In one sentence: an act at step t, the act before it at t_prev (-1: none yet) → each key's steps - its `at` offsets
+t + off (a window: the worker keeps the frames), every k steps of (t_prev, t] counting back from t (fed: the policy keeps
+them), else t alone; Observations(every=k) the whole observation so → a step before the episode's first reads as its
+first (pad "repeat_first") or goes ("drop") → oldest first, each with the keys read at it, the act's own last:
+{"observations": [...], "steps": [...]}. unit "seconds" counts seconds, taken to steps by the control rate of whoever
+steps the episode - the robot's, the benchmark's - which its caller passes.
+
+WHY one rule in one place: the worker, an eval and the SDK each act on the same declaration - which frames to keep,
+which to render, which to upload - and a step one of them reads differently is a frame a policy is handed that it never
+asked for, or never handed one it did. A robot's SDK restates it (it never imports sequence_base); its tests hold it to
+this.
+
+    sched = obs_schedule.of(observations, rate=10.0)        # None: nothing declared - the act's own, as always
+    obs_schedule.picks(sched, t=20, t_prev=12)              # [(5, ("cam",)), (20, ("cam", "state"))]
+    obs_schedule.envelope(picked, frames={5: {...}}, own={...}, t=20)
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+
+__all__ = ["Schedule", "envelope", "keeps_from", "needed", "of", "picks", "reads_past", "wanted"]
+
+Keys = tuple[str, ...] | None
+
+
+@dataclass(frozen=True)
+class Schedule:
+    """An Observations declaration in steps. `windows`: key -> its offsets (each 0 or below, oldest first); `fed`:
+    key -> every how many steps; `alone`: keys read at the act's step alone; `every`: the whole observation fed every
+    so many steps (no keys named); `whole`: no keys named - the whole observation; `pad`: "repeat_first" or "drop"."""
+
+    windows: dict
+    fed: dict
+    alone: tuple
+    every: int | None
+    whole: bool
+    pad: str
+
+
+def _get(d: Any, name: str) -> Any:
+    return d.get(name) if isinstance(d, dict) else getattr(d, name, None)
+
+
+def of(observations: Any, rate: float | None = None) -> Schedule | None:
+    """The schedule an Observations declaration - the model, or its JSON - reads by; None when there is none (the act's
+    own observation, as before). `rate`: the control steps a second of whoever steps the episode, for unit "seconds"
+    alone. Raises ValueError for unit "seconds" without it."""
+    if observations is None:
+        return None
+    unit = _get(observations, "unit") or "steps"
+
+    def steps(x: Any) -> int:
+        if unit != "seconds":
+            return int(x)
+        if not rate:
+            raise ValueError("this policy counts its observations in seconds (unit='seconds'): the control rate of the "
+                             "robot or benchmark stepping the episode takes them to steps, and none was given")
+        return int(round(float(x) * float(rate)))
+
+    windows, fed, alone = {}, {}, []
+    streams = _get(observations, "streams")
+    for key, stream in (streams or {}).items():
+        at, every = _get(stream, "at"), _get(stream, "every")
+        if at is not None:
+            windows[key] = tuple(sorted({min(0, steps(x)) for x in at}))
+        elif every is not None:
+            fed[key] = max(1, steps(every))
+        else:
+            alone.append(key)
+    every = _get(observations, "every")
+    return Schedule(windows=windows, fed=fed, alone=tuple(alone), every=max(1, steps(every)) if every is not None else
+                    None, whole=streams is None, pad=_get(observations, "pad") or "repeat_first")
+
+
+def reads_past(declared: Any) -> bool:
+    """Whether an act reads a step before its own - a window reaching back, a fed key, the whole observation fed -
+    whose frames must reach the worker before the act does (its observation stream, POST /observe). `declared`: a
+    Schedule, or the Observations declaration itself (the model or its JSON) - read with no control rate, which only
+    scales a count in seconds."""
+    if declared is None:
+        return False
+    if isinstance(declared, Schedule):
+        return (any(off < 0 for offsets in declared.windows.values() for off in offsets) or bool(declared.fed)
+                or (declared.whole and declared.every is not None))
+    if _get(declared, "every") is not None:
+        return True
+    for stream in (_get(declared, "streams") or {}).values():
+        if _get(stream, "every") is not None or any(x < 0 for x in _get(stream, "at") or ()):
+            return True
+    return False
+
+
+def picks(sched: Schedule | None, t: int, t_prev: int = -1) -> list[tuple[int, Keys]]:
+    """(step, keys) of each observation the act at step `t` is handed, oldest first, the act's own last - keys None for
+    the whole observation. A step before the episode's first is its first (step 0) under pad "repeat_first", once for
+    each such step asked, and is left out under "drop". `t_prev`: the act before it (-1: the episode's first)."""
+    if sched is None:
+        return [(t, None)]
+    asked: dict[int, set] = {}
+    whole: set[int] = set()
+    for key, offsets in sched.windows.items():
+        for off in offsets:
+            asked.setdefault(t + off, set()).add(key)
+    for key, k in sched.fed.items():
+        for s in range(t, t_prev, -k):
+            asked.setdefault(s, set()).add(key)
+    for key in sched.alone:
+        asked.setdefault(t, set()).add(key)
+    if sched.whole:
+        whole.update(range(t, t_prev, -sched.every) if sched.every else (t,))
+    out: list[tuple[int, Keys]] = []
+    for s in sorted(set(asked) | whole):
+        if s < 0 and sched.pad == "drop":
+            continue
+        out.append((max(0, s), None if s in whole else tuple(sorted(asked[s]))))
+    return out
+
+
+def needed(sched: Schedule | None, t: int, t_prev: int = -1) -> set[int]:
+    """The steps the act at `t` reads but does not carry itself: their frames come before it (the stream)."""
+    return {s for s, _ in picks(sched, t, t_prev) if s != t}
+
+
+def keeps_from(sched: Schedule | None, t: int) -> int:
+    """The earliest step an act after the one at `t` may read: a window reaches back its furthest offset from an act
+    one step on at the soonest; a fed key, the whole observation and a key read alone, nothing at or before `t`."""
+    reach = min((offsets[0] for offsets in (sched.windows.values() if sched else ())), default=0)
+    return max(0, t + 1 + min(0, reach))
+
+
+def _merge(into: dict, step: int, keys: Keys) -> None:
+    if keys is None or into.get(step, ()) is None:
+        into[step] = None
+    else:
+        into[step] = tuple(sorted({*into.get(step, ()), *keys}))
+
+
+def wanted(sched: Schedule | None, t: int, t_next: int) -> dict[int, Keys]:
+    """{step: keys} to read - an eval's benchmark - or upload - a robot's SDK - among the steps after the act at `t` and
+    before the next at `t_next` (t_next itself is that act's own, carried by it): those the act at t_next reads, and
+    those a later act may - an act after t_next reads a window key at any step from t_next + 1 + its furthest offset,
+    which a window longer than one act's turn reaches back into."""
+    out: dict[int, Keys] = {}
+    for s, keys in picks(sched, t_next, t):
+        if t < s < t_next:
+            _merge(out, s, keys)
+    for key, offsets in (sched.windows.items() if sched else ()):
+        for s in range(max(t + 1, t_next + 1 + offsets[0]), t_next):
+            _merge(out, s, (key,))
+    return dict(sorted(out.items()))
+
+
+def envelope(picked: list[tuple[int, Keys]], frames: dict, own: Any, t: int) -> dict:
+    """{"observations": [...], "steps": [...]}: each picked observation - `own`, the act's, at `t`, else `frames[step]`
+    - with only the keys read at it (a key it lacks is left out), oldest first. Raises KeyError for a step not in
+    `frames`."""
+    observations, steps = [], []
+    for step, keys in picked:
+        obs = own if step == t else frames[step]
+        if keys is not None and isinstance(obs, dict):
+            obs = {k: obs[k] for k in keys if k in obs}
+        observations.append(obs)
+        steps.append(step)
+    return {"observations": observations, "steps": steps}

sequence_base-0.4.28/sequence_base/contract/observe.py

@@ -0,0 +1,66 @@
+"""
+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 fed every observation since its last act (Observations(every=1); own_observations "since_last_act" until
+contract 0.5.25).
+
+"""
+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)