sequence-base 0.3.16__tar.gz → 0.3.17__tar.gz

{sequence_base-0.3.16 → sequence_base-0.3.17}/PKG-INFO

@@ -1,8 +1,8 @@
 Metadata-Version: 2.5
 Name: sequence-base
-Version: 0.3.16
+Version: 0.3.17
 Summary: Shared foundation for the Sequences platform — wire contract, correlation, error taxonomy, constants. Used by the robot SDK, gateway, and container harness.
-Requires-Python: >=3.11
+Requires-Python: >=3.10
 Requires-Dist: pydantic>=2.0
 Provides-Extra: codec
 Requires-Dist: numpy>=1.26; extra == 'codec'

{sequence_base-0.3.16 → sequence_base-0.3.17}/README.md

@@ -34,5 +34,5 @@ values (per-model client_resize, pricing, licensing) stay out — in container /
 `pip install -e .` (core = pydantic). The image codec pulls PIL/numpy, so it is an optional extra —
 `pip install -e ".[codec]"` — which the gateway (which never encodes/decodes) skips.
 
-Extracted from `general-sequences/backend/sequences/` (`api/schema.py`, `obs.py`,
-`api/handoff/runpod.py`). Renamed from `sequence-contract` once it grew past just the contract.
+Extracted from the original backend's schema and observability modules. Renamed from `sequence-contract` once it
+grew past just the contract.

{sequence_base-0.3.16 → sequence_base-0.3.17}/pyproject.toml

@@ -1,8 +1,10 @@
 [project]
 name = "sequence-base"
-version = "0.3.16"
+version = "0.3.17"
 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.11"
+# 3.10, not 3.11: `seq` (which imports this) must run on ROS 2 Humble's Python 3.10, and nothing here needs 3.11.
+# {2026-10-03 the full suite on CPython 3.10.20: "147 PASSED"; vermin --eval-annotations: "MINIMUM REQUIRED VERSIONS: 3.9"}
+requires-python = ">=3.10"
 dependencies = ["pydantic>=2.0"]
 
 # codec (image encode/decode) is P1 and pulls PIL/numpy — an optional extra so the gateway, which

{sequence_base-0.3.16 → sequence_base-0.3.17}/sequence_base/__init__.py

@@ -14,6 +14,10 @@ catalogue values stay in container / gateway / spec.py.
 # contract — the full shared wire contract (obs/action + registry + deployments + connect + eval +
 # accounts + error bodies). One definition per shape; see sequence_base/contract for the grouping.
 from sequence_base.contract import (  # noqa: F401  (re-export surface)
+    ActRequest,
+    ActResponse,
+    AddLocal,
+    ImageStepAddLocal,
     Camera,
     Embodiment,
     ObservationContract,
@@ -112,8 +116,6 @@ from sequence_base.errors.transport import (
 # auth — Bearer secret helpers (gateway direct-connect / internal; container guard; worker emit)
 from sequence_base import auth
 
-# telemetry — cold-start event schema (worker emits, gateway ingests)
-from sequence_base.telemetry.events import WorkerLogEvent
 
 # NOTE: codec (image encode/decode) is intentionally NOT re-exported here — it needs PIL + numpy
 # (the [codec] extra), and the gateway installs the light core. Import it explicitly where needed:
@@ -122,8 +124,10 @@ from sequence_base.telemetry.events import WorkerLogEvent
 __all__ = [
     # contract 4 — /act data plane
     "ImageFrame", "Proprioception", "Observation", "ActionSpace", "ActionStep", "ActionChunk",
+    "ActRequest", "ActResponse",
     # contract 1 — flags + policy registry
-    "SeqFlags", "ImageStepUvPip", "ImageStepApt", "ImageStepEnv", "ImageStepRun", "ImageStep", "ImageSpec",
+    "SeqFlags", "ImageStepUvPip", "ImageStepApt", "ImageStepEnv", "ImageStepRun", "AddLocal", "ImageStepAddLocal",
+    "ImageStep", "ImageSpec",
     "VolumeMount", "VolumeRef", "Concurrency", "ActionContract", "Camera", "ObservationContract", "Embodiment",
     "PolicySpec", "PolicyRegistration",
     # contract 2 — deployments
@@ -150,7 +154,14 @@ __all__ = [
     # errors (exception taxonomy)
     "TransportUnavailable", "TransportWarming", "TransportRejected", "TransportOverloaded",
     # auth + telemetry
-    "auth", "WorkerLogEvent",
+    "auth",
 ]
 
-__version__ = "0.3.6"
+try:
+    # The installed distribution's own number, so this can never drift from pyproject.toml again (it said 0.3.6
+    # while the package was 0.3.12). A source tree that was never installed reports "dev".
+    from importlib.metadata import PackageNotFoundError, version as _version
+
+    __version__ = _version("sequence-base")
+except PackageNotFoundError:  # pragma: no cover - running from an uninstalled checkout
+    __version__ = "dev"

sequence_base-0.3.17/sequence_base/codec/__init__.py

@@ -0,0 +1,19 @@
+"""
+Image codec — the frame <-> wire transform, shared so the SDK (encode) and the worker (decode) cannot drift
+on the wire format.
+
+Needs Pillow + numpy: `pip install 'sequence-base[codec]'`. The gateway, which neither encodes nor
+decodes, installs the light core and never imports this.
+
+    from sequence_base.codec import encode, decode
+"""
+from sequence_base.codec.image import (
+    DEFAULT_JPEG_QUALITY,
+    MAX_UPLOAD_EDGE,
+    decode,
+    decode_depth,
+    encode,
+    encode_depth,
+)
+
+__all__ = ["encode", "decode", "encode_depth", "decode_depth", "DEFAULT_JPEG_QUALITY", "MAX_UPLOAD_EDGE"]

{sequence_base-0.3.16 → sequence_base-0.3.17}/sequence_base/codec/image.py

@@ -15,7 +15,6 @@ import base64
 import io
 from typing import Any
 
-from .resize import MAX_UPLOAD_EDGE, ResizeSpec, filters, refuse_wrong_aspect, resize_with_pad
 
 # Quality 95, and the number is measured rather than chosen for looking safe. On a real DROID frame
 # with the sampling noise pinned, the encoding moves the resulting action by: q95 0.51% of action
@@ -25,20 +24,22 @@ from .resize import MAX_UPLOAD_EDGE, ResizeSpec, filters, refuse_wrong_aspect, r
 # {sequences-models models/pi05_droid/handler.py "Q95 MAX|DELTA| 0.0048 0.51% ... Q85 1.86%"}
 DEFAULT_JPEG_QUALITY = 95
 
+# The longest edge `encode` uploads. Every policy resizes a frame to its own input size anyway, so pixels above
+# that only cost transport — and past a point they do not cost, they fail: a body over ~2 MB was dropped by a
+# worker queue with no error and no job id, surfacing as a hang. 640 is above every input size in use (pi0.5's
+# 224), so it discards nothing a policy reads. [MEASURED 2026-09-12: capping the long edge at 640 took a
+# three-view observation from 1.98 MB to 0.12 MB]
+MAX_UPLOAD_EDGE = 640
 
-def encode(frame: Any, spec: ResizeSpec | None = None, *, quality: int = DEFAULT_JPEG_QUALITY) -> str:
+
+def encode(frame: Any, *, quality: int = DEFAULT_JPEG_QUALITY) -> str:
     """
     One camera frame to the base64 image that `ImageFrame.data` carries.
 
     `frame` may be a numpy array, a PIL image, raw `bytes` already encoded, or a `str` already base64
     — the last two pass through untouched, so a caller with their own pipeline is not forced through
-    this one.
-
-    `spec` (a `ResizeSpec`) carries the model's geometry. When it declares a training aspect ratio, a
-    frame outside it is REFUSED — see `refuse_wrong_aspect`, not quietly reshaped. With no spec (or no
-    `client_resize`) the frame falls to `MAX_UPLOAD_EDGE`. Codec is JPEG at `quality`, unconditionally
-    — every served handler asks for JPEG in as many words, so there is no size probe and no second
-    encode. {handlers pi05_droid/cosmos3/groot all "SEND BASE64 JPEG"}
+    this one. A frame whose long edge is over `MAX_UPLOAD_EDGE` is scaled down to it first. Codec is
+    JPEG at `quality`, unconditionally.
     """
     if isinstance(frame, str):
         return frame
@@ -56,59 +57,7 @@ def encode(frame: Any, spec: ResizeSpec | None = None, *, quality: int = DEFAULT
     img = frame if hasattr(frame, "save") else Image.fromarray(frame)
     if img.mode != "RGB":
         img = img.convert("RGB")
-
-    # Downscale before encoding. Every model resizes the frame to its own input size anyway, so pixels
-    # above that only cost transport — and past a point they do not cost, they fail (a body over ~2 MB
-    # is dropped by the worker queue with no error and no job id, surfacing as a hang). The target and
-    # the filter both come from the spec; neither is derived here. `client_resize=None` means the
-    # model declined pre-resizing and is not a gap: it falls to the cap below, as an unknown model
-    # does. HOW the frame reaches that size comes from `input_resize` ("pad" = the server's own
-    # resize_with_pad, "stretch" = unconditional interpolate).
-    want = None
-    cr = spec.client_resize if spec else None
-    if cr:
-        # `shortest_edge` scales the short side to n and lets the ratio follow — the only way to
-        # express a server step defined as "SmallestMaxSize(256)" (1280x720 and 1920x1080 both to
-        # 455x256), which no fixed [w, h] covers. round(), matching albumentations. `size` is a fixed
-        # target.
-        if "shortest_edge" in cr:
-            # Shrink only. SmallestMaxSize also UPSCALES a frame whose short edge is under the target,
-            # and reproducing that here is strictly worse: the payload grows and the upscale happens
-            # in PIL when the server was going to do it in cv2 anyway. Leaving a small frame alone
-            # hands the whole operation to the server, where it is exact.
-            n = int(cr["shortest_edge"])
-            if min(img.size) > n:
-                scale = n / min(img.size)
-                want = (max(1, round(img.width * scale)), max(1, round(img.height * scale)))
-            else:
-                want = img.size
-        else:
-            want = (int(cr["size"][0]), int(cr["size"][1]))
-        if img.size != want:
-            # The filter is named by the server, not chosen here: this resize stands in for one the
-            # model's own transform would otherwise run, so it has to be the SAME operation. An
-            # unrecognised name raises rather than falling back — a silent default is how the LANCZOS
-            # bug shipped. {MEASURED: BILINEAR to pi05's content block is 0.000/255, LANCZOS 0.779/15}
-            try:
-                resample = filters()[cr["filter"]]
-            except KeyError:
-                raise ValueError(
-                    f"{spec.label} asks for resize filter {cr['filter']!r}, which this version of "
-                    f"sequence-base does not implement (has: {sorted(filters())}). Upgrade, or pass "
-                    f"an already-encoded frame to bypass this step."
-                ) from None
-            # Refused before either branch, not inside "pad": a stretch model distorts a wrong ratio
-            # instead of letterboxing it, which is worse rather than exempt.
-            refuse_wrong_aspect(img, spec.aspect_ratio, max(want), spec.label)
-            if "shortest_edge" in cr:
-                # Already proportional, so nothing to letterbox — and letterboxing would actively
-                # damage it (a spurious black row the server carries into its crop as if it were scene).
-                img = img.resize(want, resample)
-            elif (spec.input_resize or "pad") == "pad":
-                img = resize_with_pad(img, want[0], want[1], resample)
-            else:
-                img = img.resize(want, resample)
-    elif max(img.size) > MAX_UPLOAD_EDGE:
+    if max(img.size) > MAX_UPLOAD_EDGE:
         scale = MAX_UPLOAD_EDGE / max(img.size)
         # round() not int(): int() truncates a 640.9 on one axis and 359.9 on the other, drifting the
         # aspect ratio by up to half a percent for no reason.

{sequence_base-0.3.16 → sequence_base-0.3.17}/sequence_base/constants/env.py

@@ -5,10 +5,3 @@ INTERNAL_SECRET = "SEQ_INTERNAL_SECRET"  # auth for container → gateway teleme
 GATEWAY_URL = "SEQ_GATEWAY_URL"          # where the container sends telemetry
 VOLUME_ROOT = "SEQ_VOLUME_ROOT"          # where fetched weights land
 MANIFEST = "SEQ_MANIFEST"                # the policy manifest a container serves
-
-# Weight store (Cloudflare R2).
-DIST_ENDPOINT = "SEQ_DIST_ENDPOINT"
-DIST_BUCKET = "SEQ_DIST_BUCKET"
-DIST_KEY = "SEQ_DIST_KEY"
-DIST_SECRET = "SEQ_DIST_SECRET"
-DIST_REGION = "SEQ_DIST_REGION"

{sequence_base-0.3.16 → sequence_base-0.3.17}/sequence_base/constants/headers.py

@@ -1,5 +1,4 @@
 """HTTP header names — one source, so sdk / gateway / container never spell them differently."""
 
 REQUEST_ID = "X-Seq-Request-Id"   # correlation id; == sequence_base.obs.rid.HEADER
-MODEL = "X-Seq-Model"             # gateway → worker model routing
 AUTH_SCHEME = "Bearer"            # scheme for SEQ_DIRECT_SECRET on the direct-connect path

{sequence_base-0.3.16 → sequence_base-0.3.17}/sequence_base/constants/version.py

@@ -4,7 +4,8 @@
 # across deployments / repos can tell which version of a shape it is validating against. MUST change
 # whenever any shared wire shape changes (a field added / removed / retyped) — that is what makes
 # contract evolution mechanically detectable instead of eyeballed. Bump on any shape change.
-CONTRACT_VERSION = "0.4.13"  # 0.4.12 -> 0.4.13: template://<name>[@v<n>] — official template weights (parse_template); gs:// / s3:// / https:// still accepted until their removal
+CONTRACT_VERSION = "0.4.14"  # 0.4.13 -> 0.4.14: the /act wire is opaque (ActRequest.inputs / ActResponse.outputs); action / observation contracts optional + DeploymentPolicy/PolicySpec/ConnectResponse .io; the robot-arm types live in sequence_base.presets.robot_arm (contract.act / contract.io re-export them); ImageStepAddLocal (seq.Image.add_local_*); ActionSpace.JOINT_VELOCITY (pi0.5 DROID's joint velocities + gripper position)
+# previous: 0.4.13  # 0.4.12 -> 0.4.13: template://<name>[@v<n>] — official template weights (parse_template); gs:// / s3:// / https:// still accepted until their removal
 # previous: 0.4.12  # 0.4.11 -> 0.4.12: one error definition — ErrorBody is every non-2xx body (detail, code, retryable, retry_after_s, request_id, hint, details), ErrorCode covers every case, ERRORS / ErrorCodes.json give each code its status, retryability, SDK class and CLI exit code
 # previous: 0.4.11  # 0.4.10 -> 0.4.11: weights in named parts (weights_name, extra_weights)
 # previous: 0.4.8  # 0.4.7 -> 0.4.8: ImageSpec.python, ImageStepRun.secrets, Resources.region, DeploymentRequest/BenchmarkRegisterRequest.image_context

{sequence_base-0.3.16 → sequence_base-0.3.17}/sequence_base/contract/__init__.py

@@ -12,6 +12,9 @@ from sequence_base.contract.act import (
     Proprioception,
 )
 
+# contract 4, version 2 — the opaque /act envelope (inputs in, outputs out)
+from sequence_base.contract.wire import ActRequest, ActResponse
+
 # contract 1 — lifecycle flags + policy registry
 from sequence_base.contract.flags import SeqFlags
 from sequence_base.contract.policy import (
@@ -26,6 +29,8 @@ from sequence_base.contract.policy import (
     ImageStepEnv,
     ImageStepRun,
     ImageStepUvPip,
+    AddLocal,
+    ImageStepAddLocal,
     PolicyRegistration,
     PolicySpec,
     VolumeMount,
@@ -110,9 +115,11 @@ from sequence_base.contract.errors import ERRORS, ErrorBody, ErrorCode, ErrorSpe
 __all__ = [
     # contract 4
     "ImageFrame", "Proprioception", "Observation", "ActionSpace", "ActionStep", "ActionChunk",
+    "ActRequest", "ActResponse",
     # contract 1
     "SeqFlags",
-    "ImageStepUvPip", "ImageStepApt", "ImageStepEnv", "ImageStepRun", "ImageStep", "ImageSpec",
+    "ImageStepUvPip", "ImageStepApt", "ImageStepEnv", "ImageStepRun", "AddLocal", "ImageStepAddLocal", "ImageStep",
+    "ImageSpec",
     "VolumeMount", "VolumeRef", "Concurrency", "ActionContract", "Camera", "ObservationContract", "Embodiment",
     "PolicySpec", "PolicyRegistration",
     # contract 2

sequence_base-0.3.17/sequence_base/contract/act.py

@@ -0,0 +1,17 @@
+"""
+The robot-arm /act data types, re-exported from their home in `sequence_base.presets.robot_arm`.
+
+They are no longer the platform's wire: since contract 0.4.14 the worker passes a policy's `inputs` through untouched
+(`sequence_base.contract.wire`). This module keeps `from sequence_base.contract.act import Observation` resolving to the
+same classes for the gateway, harness and SDK code that still uses the preset.
+"""
+from sequence_base.presets.robot_arm import (  # noqa: F401 — re-exports
+    ActionChunk,
+    ActionSpace,
+    ActionStep,
+    ImageFrame,
+    Observation,
+    Proprioception,
+)
+
+__all__ = ["ImageFrame", "Proprioception", "Observation", "ActionSpace", "ActionStep", "ActionChunk"]

{sequence_base-0.3.16 → sequence_base-0.3.17}/sequence_base/contract/connect.py

@@ -57,3 +57,5 @@ class ConnectResponse(BaseModel):
     action: ActionContract | None = None
     observation: ObservationContract | None = None
     embodiment: str | None = None
+    # The deployment's own description of its inputs and outputs (DeploymentPolicy.io), when the author wrote one.
+    io: str | None = None

{sequence_base-0.3.16 → sequence_base-0.3.17}/sequence_base/contract/deployments.py

@@ -1,8 +1,8 @@
 """
 契约 2 — `POST /v1/deployments` (SDK `seq deploy` → gateway) and its responses.
 
-The request is the normalized wire form of a PolicySpec: one big body (à la Modal's single `Function`
-message — new config adds a field, never a new endpoint) whose sub-shapes reuse contract 1's types
+The request is the normalized wire form of a PolicySpec: one big body (new config adds a field, never a
+new endpoint) whose sub-shapes reuse contract 1's types
 (ImageSpec, VolumeMount, Concurrency, ActionContract). Field names align with the PolicySpec side —
 `gpu` is normalized to list[str] here, the memory field is `memory_gb` (goal 7).
 
@@ -47,7 +47,7 @@ __all__ = [
 
 
 class Resources(BaseModel):
-    """= Modal Resources + GPUConfig. `gpu` is list[str] (the PolicySpec `str | list[str]` normalized)."""
+    """The hardware a worker runs on. `gpu` is list[str] (the PolicySpec `str | list[str]` normalized)."""
 
     model_config = ConfigDict(extra="forbid")
 
@@ -60,7 +60,7 @@ class Resources(BaseModel):
 
 
 class Autoscaler(BaseModel):
-    """= Modal AutoscalerSettings. Defaults mirror PolicySpec so an omitted block scale-to-zeroes."""
+    """How the deployment scales. Defaults mirror PolicySpec so an omitted block scales to zero."""
 
     model_config = ConfigDict(extra="forbid")
 
@@ -104,8 +104,9 @@ class InferParam(BaseModel):
 
 
 class DeploymentPolicy(BaseModel):
-    """The policy block of the deployments body. `handler_ref` and `action` are required; `action` is the
-    fixed obs→ActionChunk contract, not a bare dict.
+    """The policy block of the deployments body. Only `handler_ref` is required. The robot-arm preset's contracts
+    (`action`, `observation`, `embodiments`) are optional since contract 0.4.14: a deployment that declares none is held
+    to nothing and its inputs / outputs pass through the worker untouched.
 
     `secrets` carries the policy's declared secret BUNDLES BY NAME ONLY (list[SecretRef]) — the gateway
     validates each name exists and belongs to the deployer at submit time (accounts ⑦ / S3 goal 14), and the
@@ -116,7 +117,7 @@ class DeploymentPolicy(BaseModel):
     model_config = ConfigDict(extra="forbid")
 
     handler_ref: str
-    action: ActionContract
+    action: ActionContract | None = None
     streaming: bool = False
     frames_per_chunk: int | None = None
     secrets: list[SecretRef] = Field(default_factory=list)
@@ -124,11 +125,14 @@ class DeploymentPolicy(BaseModel):
     # contracts for a multi-embodiment policy — the worker picks one by the session's embodiment.
     observation: ObservationContract | None = None
     embodiments: dict[str, Embodiment] | None = None
-    # Did the author declare `action=` (or embodiments)? `action` is required on the wire, so an SDK that had
-    # nothing declared sends a placeholder; only a declared contract is enforced on the worker and handed to the
-    # robot. None (an older SDK) is treated as undeclared, so an older policy is never refused for the
-    # placeholder it never chose. {io-contract.md "旧 SDK 写的 POLICY 照样能 BUILD"}
+    # Did the author declare `action=` (or embodiments)? SDKs before contract 0.4.14 always sent an `action` (a
+    # placeholder when none was declared); only a declared contract is enforced on the worker and handed to the robot.
+    # None (an older SDK) is treated as undeclared, so an older policy is never refused for the placeholder it never
+    # chose. A current SDK sends `action` only when declared. {io-contract.md "旧 SDK 写的 POLICY 照样能 BUILD"}
     action_declared: bool | None = None
+    # The author's own description of what infer() takes and returns; stored, handed to the robot at connect, never
+    # interpreted by the platform.
+    io: str | None = Field(default=None, max_length=4000)
     # The inference parameters @seq.infer takes beyond the observation (name -> type, default). None: an older
     # SDK that did not look; {}: the policy declares none.
     params: dict[str, InferParam] | None = Field(default=None, max_length=32)
@@ -149,7 +153,7 @@ request limit (base64 adds a third)."""
 
 class CodeBundle(BaseModel):
     """The policy's own source, shipped with the deploy so the worker can import `policy.handler_ref`
-    (what Modal's automount does for the entrypoint module). A gzip'd tar of the handler's top-level module
+    — the entrypoint module, mounted for it. A gzip'd tar of the handler's top-level module
     or package, base64 on the wire, with the sha256 of the decoded bytes so a truncated or altered upload
     is refused at the edge instead of failing as an ImportError on a GPU."""
 
@@ -203,7 +207,7 @@ class DeploymentRequest(BaseModel):
     autoscaler: Autoscaler = Field(default_factory=Autoscaler)
     # An omitted @seq.concurrent must NOT send null: the gateway would then have no concurrency to scale by.
     # Materialize the spec default — contracts.md §2's example {"max_inputs": 1, "target_inputs": 1}, i.e.
-    # one input per container (Modal's no-`@modal.concurrent` semantics) — same discipline as `autoscaler`
+    # one input per container — same discipline as `autoscaler`
     # (goal 13).
     concurrency: Concurrency = Field(default_factory=lambda: Concurrency(max_inputs=1, target_inputs=1))
     timeouts: Timeouts | None = None

{sequence_base-0.3.16 → sequence_base-0.3.17}/sequence_base/contract/flags.py

@@ -3,10 +3,8 @@
 reads back. One IntFlag, so a registration can carry several lifecycle entrypoints in one integer and
 the harness recovers each by testing a bit.
 
-Modeled on Modal's `_PartialFunctionFlags` (one IntFlag, one bit per lifecycle hook)
-{modal _partial_function.py:29}. Four members map bit-for-bit onto Modal's flags so the harness can be
-a thin adaptation of Modal's loader; the rest are platform-only lifecycle hooks Modal has no analogue
-for (a warm-up hook, a plan step, and the benchmark SETUP / RESET / CHECK / SCORE quartet).
+One bit per lifecycle hook: load, infer, an episode boundary and shutdown for a policy; a warm-up hook and a
+plan step; and the benchmark SETUP / RESET / CHECK / SCORE quartet.
 
 eval-raw revision: the platform provides the reset→step→check loop as a tool; the user defines the goal
 through four hooks — SETUP (load sim + assets), RESET (build one episode's env), CHECK (per-step: read raw
@@ -14,10 +12,10 @@ env state → done + user-named metrics), SCORE (cross-episode aggregate). RESET
 the new hook bits. The old single-hook `ROLLOUT` is DEPRECATED: bit 8192 stays reserved (never reused for
 another member) but appears in NO bindings — the setup/reset/check/score model replaces it.
 
-The exact bit values are the contract — see `MODAL_MAPPING` / `PLATFORM_ONLY` for the authoritative
-"member → bit value → Modal counterpart" list. A member taking the wrong value, WARMUP collapsing back
-into LOAD, RESET/CHECK overlapping an existing bit, or ROLLOUT being re-bound is caught bit-by-bit (see
-tests), not waved away with "an IntFlag is naturally bit-composable".
+The exact bit values are the contract: a registration serialized by one version must decode the same in
+another. A member taking the wrong value, WARMUP collapsing back into LOAD, RESET/CHECK overlapping an
+existing bit, or ROLLOUT being re-bound is caught bit-by-bit (see tests), not waved away with "an IntFlag
+is naturally bit-composable".
 """
 from __future__ import annotations
 
@@ -25,18 +23,18 @@ from enum import IntFlag
 
 
 class SeqFlags(IntFlag):
-    # ── mapped bit-for-bit onto Modal `_PartialFunctionFlags` ────────────────────────────────────
-    LOAD = 2            # Modal ENTER — load weights into VRAM (one-shot; no snapshot bisection)
-    SHUTDOWN = 8        # Modal EXIT — teardown / release the container
-    INFER = 16          # Modal CALLABLE_INTERFACE — the obs→ActionChunk call
-    ON_EPISODE = 1024   # Modal ~SESSIONED — sticky / session boundary for stateful policies
+    # ── a policy's lifecycle ────────────────────────────────────────────────────────────────────────
+    LOAD = 2            # load weights into VRAM (one-shot; no snapshot bisection)
+    SHUTDOWN = 8        # teardown / release the container
+    INFER = 16          # the obs→ActionChunk call
+    ON_EPISODE = 1024   # sticky / session boundary for stateful policies
 
-    # ── platform-only: no Modal counterpart; each an independent, disjoint bit ────────────────────
+    # ── each an independent bit, disjoint from the four above ──────────────────────────────────────
     # WARMUP is its OWN bit, NOT an alias of LOAD (S1.yaml goal 5 — "WARMUP=1(独立 bit,明确不并入
     # LOAD)"). A policy may bind @seq.load and @seq.warmup to two different methods → two independent
     # bindings, so the bit must be distinct from LOAD. Value 1 is bit 0, unused by any mapped flag.
-    WARMUP = 1          # JIT warm-up hook (ours; Modal folded warm-up into ENTER, we keep it separate)
-    PLAN = 4            # a policy planning step (ours; Modal has none) — bit 2, unused by Modal
+    WARMUP = 1          # JIT warm-up hook, kept separate from LOAD
+    PLAN = 4            # a policy planning step — bit 2
     # benchmark lifecycle (eval-raw: platform provides the loop tool, user hooks the goal in) — each an
     # independent, disjoint bit, disjoint too from every mapped bit:
     SETUP = 4096        # load sim + assets, once (≈ @seq.load)
@@ -49,21 +47,6 @@ class SeqFlags(IntFlag):
     ROLLOUT = 8192
 
 
-# Authoritative "member → Modal counterpart" list. Anything here must equal the bit above; anything in
-# PLATFORM_ONLY must be disjoint from every mapped bit and from each other.
-MODAL_MAPPING: dict[str, str] = {
-    "LOAD": "ENTER",
-    "SHUTDOWN": "EXIT",
-    "INFER": "CALLABLE_INTERFACE",
-    "ON_EPISODE": "~SESSIONED",
-}
-
-# Platform-only members Modal has no flag for. ROLLOUT is included: it is still a real (if deprecated)
-# member and its bit must stay disjoint from every other, so the disjointness check must cover it.
-PLATFORM_ONLY: frozenset[str] = frozenset(
-    {"WARMUP", "PLAN", "SETUP", "SCORE", "RESET", "CHECK", "ROLLOUT"}
-)
-
 # The benchmark lifecycle bits a live registration may bind (eval-raw): SETUP / RESET / CHECK / SCORE.
 # ROLLOUT is deliberately absent — deprecated, never bound.
 BENCHMARK_BINDABLE: frozenset[SeqFlags] = frozenset(

sequence_base-0.3.17/sequence_base/contract/io.py

@@ -0,0 +1,17 @@
+"""
+The robot-arm I/O contracts (`action=`, `observation=`, `embodiments=`), re-exported from
+`sequence_base.presets.robot_arm`.
+
+Declaring one is optional since contract 0.4.14: a deployment that declares none is held to nothing, and its
+`inputs` / `outputs` pass through the worker untouched. A declared contract is still enforced by the worker and
+handed to the robot at connect. {gs-plans/custom-io/README.md "2. worker:原样交给用户代码"}
+"""
+from sequence_base.presets.robot_arm import (  # noqa: F401 — re-exports
+    PROPRIO_FIELDS,
+    ActionContract,
+    Camera,
+    Embodiment,
+    ObservationContract,
+)
+
+__all__ = ["ActionContract", "PROPRIO_FIELDS", "Camera", "ObservationContract", "Embodiment"]

{sequence_base-0.3.16 → sequence_base-0.3.17}/sequence_base/contract/policy.py

@@ -30,6 +30,8 @@ __all__ = [
     "ImageStepApt",
     "ImageStepEnv",
     "ImageStepRun",
+    "AddLocal",
+    "ImageStepAddLocal",
     "ImageStep",
     "ImageSpec",
     "VolumeMount",
@@ -41,7 +43,7 @@ __all__ = [
 ]
 
 
-# ── ImageSpec — a discriminated union of exactly four step variants ───────────────────────────────
+# ── ImageSpec — a discriminated union of exactly five step variants ───────────────────────────────
 # Each variant carries exactly one key; extra="forbid" makes a dict that names two keys (or an unknown
 # key) match NONE of them, so every step matches exactly one variant (goal 4). `run_commands` is its own
 # variant (SDK contract S2 goal 5) so an arbitrary build command is an ordered step in the chain, never
@@ -69,11 +71,41 @@ class ImageStepRun(BaseModel):
     secrets: list[SecretRef] | None = None
 
 
-ImageStep = ImageStepUvPip | ImageStepApt | ImageStepEnv | ImageStepRun
+class AddLocal(BaseModel):
+    """One local file or directory the author declared (`seq.Image.add_local_file / add_local_dir`): shipped inside the
+    deploy's code bundle at `src` and placed at `dst` in the image when it builds. Only the entry file (or its package)
+    is shipped otherwise. {gs-plans/custom-io/sdk-dx.md}"""
+
+    model_config = ConfigDict(extra="forbid")
+
+    src: str = Field(..., min_length=1, max_length=512, description="Path inside the code bundle (relative)")
+    dst: str = Field(..., min_length=2, max_length=512, description="Absolute path in the image")
+
+    @field_validator("src")
+    @classmethod
+    def _src_inside_bundle(cls, v: str) -> str:
+        if v.startswith("/") or "\\" in v or ".." in v.split("/"):
+            raise ValueError(f"add_local src {v!r} must be a relative path inside the code bundle, without '..'")
+        return v
+
+    @field_validator("dst")
+    @classmethod
+    def _dst_absolute(cls, v: str) -> str:
+        if not v.startswith("/") or ".." in v.split("/"):
+            raise ValueError(f"add_local dst {v!r} must be an absolute path in the image, without '..'")
+        return v
+
+
+class ImageStepAddLocal(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+    add_local: AddLocal
+
+
+ImageStep = ImageStepUvPip | ImageStepApt | ImageStepEnv | ImageStepRun | ImageStepAddLocal
 
 
 class ImageSpec(BaseModel):
-    """Declarative image (gateway builds it via Cloud Build) — = Modal `Image` message. Exactly one of
+    """Declarative image, built by the platform. Exactly one of
     `base` (a pullable registry ref) or `dockerfile` (inline Dockerfile source) is set — the Dockerfile
     is its OWN component, never smuggled into the `base` string (S2 goal 4), so the gateway can tell a
     registry build from a Dockerfile build. `steps` is an ordered list of the four-variant union above
@@ -121,7 +153,7 @@ class VolumeRef(BaseModel):
 
 
 class Concurrency(BaseModel):
-    """= Modal max/target_concurrent_inputs. Both required."""
+    """How many inputs one container serves at once: the most it takes, and the level it scales to hold. Both required."""
 
     model_config = ConfigDict(extra="forbid")
 
@@ -130,8 +162,9 @@ class Concurrency(BaseModel):
 
 
 class PolicySpec(BaseModel):
-    """What `@seq.policy(...)` accrues — a policy's complete infra declaration, losslessly. `action` is
-    required (no default): a policy without an obs→ActionChunk contract is not deployable."""
+    """What `@seq.policy(...)` accrues — a policy's complete infra declaration, losslessly. `action` /
+    `observation` / `embodiments` are optional (contract 0.4.14): a policy that declares none defines its I/O in its own
+    code, and the platform passes it through. {gs-plans/custom-io/README.md "2. worker:原样交给用户代码"}"""
 
     model_config = ConfigDict(extra="forbid")
 
@@ -149,7 +182,8 @@ class PolicySpec(BaseModel):
     concurrency: Concurrency | None = None
     streaming: bool = False
     frames_per_chunk: int | None = None
-    action: ActionContract
+    # The robot-arm preset's contracts, all optional: declared ones are enforced by the worker and handed to the robot.
+    action: ActionContract | None = None
     # What the policy reads (None: undeclared — an older SDK); per-robot contracts when one model drives several.
     observation: ObservationContract | None = None
     embodiments: dict[str, Embodiment] | None = None
@@ -158,6 +192,9 @@ class PolicySpec(BaseModel):
     # {name: directory}. Both None: one weights path, as before. {gs-plans/customization/options.md "多份权重文件"}
     weights_name: str | None = None
     extra_weights: dict[str, str] | None = None
+    # The author's own description of what infer() takes and returns. Stored and shown (connect hands it to the
+    # robot); the platform never interprets it.
+    io: str | None = Field(default=None, max_length=4000)
 
     @field_validator("weights")
     @classmethod

sequence_base-0.3.17/sequence_base/contract/wire.py

@@ -0,0 +1,53 @@
+"""
+The /act wire, version 2 — opaque. The platform carries a policy's inputs and outputs; it never reads them.
+
+In one sentence: the robot's own code (a template's `client.py`) preprocesses raw sensor data into `inputs` → the SDK
+posts them to the worker's /act unchanged → the worker hands them to the policy's `infer()` unchanged → whatever
+`infer()` returns comes back as `outputs`, unchanged. What `inputs` and `outputs` hold is agreed between the two halves
+of the user's own code, never by the platform. {gs-plans/custom-io/README.md "1. 线上格式:不透明"}
+
+Alongside the payload the envelope carries only what the platform itself acts on: a seed (determinism), the episode
+(per-episode state and `/act/episode_end`), the declared inference parameters, and — for a robot-arm preset policy with
+several bodies — the embodiment chosen at connect.
+
+Compatibility: a worker also accepts the version-1 body (`observation` instead of `inputs`), and a policy written
+against the robot-arm preset (`infer(self, obs: Observation) -> ActionChunk`) also answers `action_chunk`, so older SDKs
+and older deployments keep working in both directions.
+"""
+from __future__ import annotations
+
+from typing import Any
+
+from pydantic import BaseModel, ConfigDict, Field
+
+__all__ = ["ActRequest", "ActResponse"]
+
+
+class ActRequest(BaseModel):
+    """POST /act, version 2. `inputs` is any JSON value; the worker does not inspect it."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    inputs: Any = Field(..., description="Whatever the policy's infer() takes, exactly as the robot's code built it")
+    seed: int | None = Field(default=None, description="Sampling seed, passed to infer() for a reproducible answer")
+    episode_id: str | None = Field(default=None, description="The episode this call belongs to (per-episode state)")
+    params: dict[str, Any] | None = Field(default=None,
+                                          description="Values for the inference parameters the policy declares")
+    embodiment: str | None = Field(default=None,
+                                   description="Robot-arm preset only: which declared embodiment this session drives")
+
+
+class ActResponse(BaseModel):
+    """200 from /act, version 2. `outputs` is infer()'s return value, unchanged; the rest is platform metadata."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    outputs: Any = Field(..., description="infer()'s return value, exactly as the policy returned it")
+    perf: dict[str, Any] | None = Field(default=None, description="Per-phase timings of this call")
+    usage: dict[str, Any] | None = Field(default=None, description="What this call counted towards the account")
+    warnings: list[str] = Field(default_factory=list, description="Non-fatal notes, e.g. actions clipped into bounds")
+    request_id: str | None = Field(default=None, description="This call's id; quote it when reporting a problem")
+    # The robot-arm preset's chunk under its version-1 key, so an SDK that predates version 2 still finds it. Present
+    # only when the policy answers with the preset's ActionChunk; then it equals `outputs`.
+    action_chunk: dict[str, Any] | None = Field(default=None,
+                                                description="Version-1 key for a robot-arm preset chunk (= outputs)")