sequence-base 0.3.0__py3-none-any.whl

sequence_base/__init__.py

@@ -0,0 +1,134 @@
+"""
+sequence-base — the shared foundation for the Sequences platform.
+
+The wire protocol + primitives that the robot SDK, the gateway, and the container harness ALL use,
+defined once so they cannot drift. Import from here; never redefine.
+
+    from sequence_base import Observation, ActionChunk               # contract
+    from sequence_base import log, new_rid, HEADER                   # correlation
+    from sequence_base import TransportWarming, TransportOverloaded  # error taxonomy
+
+Only shared-by-≥2-and-drifts-if-duplicated things live here. Model-specific, provider-specific, and
+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)
+    MAX_CODE_BUNDLE_BYTES,
+    ActionChunk,
+    ActionContract,
+    ActionSpace,
+    ActionStep,
+    AdapterKind,
+    AdapterTransform,
+    Autoscaler,
+    BenchmarkRegisterRequest,
+    BenchmarkSpec,
+    BootstrapResponse,
+    ClampInfo,
+    CodeBundle,
+    Concurrency,
+    Conditions,
+    ConnectRequest,
+    ConnectResponse,
+    DeploymentAccepted,
+    DeploymentPolicy,
+    DeploymentRequest,
+    DeploymentState,
+    DeploymentStatusResponse,
+    ErrorBody,
+    ErrorCode,
+    Estimate,
+    EvalDryRunResponse,
+    EvalReport,
+    EvalRequest,
+    EvalResponse,
+    EvalStatus,
+    ImageFrame,
+    ImageSpec,
+    ImageStep,
+    ImageStepApt,
+    ImageStepEnv,
+    ImageStepRun,
+    ImageStepUvPip,
+    Lease,
+    LossyTransform,
+    MetricAgg,
+    Observation,
+    PolicyRegistration,
+    PolicySpec,
+    Proprioception,
+    RenderSpec,
+    Resources,
+    RolloutResult,
+    SecretCreateRequest,
+    SecretInfo,
+    SecretRef,
+    SeqFlags,
+    Step,
+    SuiteAgg,
+    TaskAgg,
+    Timeouts,
+    UsageReport,
+    Variant,
+    VolumeAttach,
+    VolumeMount,
+    VolumeRef,
+    WarmingError,
+)
+
+# the single schema-level version stamp (embedded in every exported JSON Schema)
+from sequence_base.constants.version import CONTRACT_VERSION
+
+# obs — correlation id + structured logging (all three sides)
+from sequence_base.obs.log import Timer, enabled, log
+from sequence_base.obs.rid import HEADER, clean, new_rid
+
+# errors — shared transport status taxonomy (gateway + container)
+from sequence_base.errors.transport import (
+    TransportOverloaded,
+    TransportRejected,
+    TransportUnavailable,
+    TransportWarming,
+)
+
+# 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:
+#     from sequence_base.codec import encode, decode, ResizeSpec
+
+__all__ = [
+    # contract 4 — /act data plane
+    "ImageFrame", "Proprioception", "Observation", "ActionSpace", "ActionStep", "ActionChunk",
+    # contract 1 — flags + policy registry
+    "SeqFlags", "ImageStepUvPip", "ImageStepApt", "ImageStepEnv", "ImageStepRun", "ImageStep", "ImageSpec",
+    "VolumeMount", "VolumeRef", "Concurrency", "ActionContract", "PolicySpec", "PolicyRegistration",
+    # contract 2 — deployments
+    "MAX_CODE_BUNDLE_BYTES", "CodeBundle",
+    "Resources", "Autoscaler", "Timeouts", "VolumeAttach", "DeploymentPolicy", "DeploymentRequest",
+    "DeploymentAccepted", "DeploymentState", "DeploymentStatusResponse",
+    # contract 3 — connect / lease
+    "Lease", "ConnectRequest", "ConnectResponse",
+    # contract 5 — benchmark + eval
+    "Variant", "Conditions", "RenderSpec", "Step", "BenchmarkSpec", "BenchmarkRegisterRequest",
+    "EvalRequest", "ClampInfo", "Estimate", "EvalResponse", "EvalDryRunResponse", "RolloutResult",
+    "EvalStatus", "SuiteAgg", "TaskAgg", "MetricAgg", "LossyTransform", "EvalReport",
+    "AdapterKind", "AdapterTransform",
+    # contract 6 — accounts / secret / billing
+    "SecretRef", "SecretCreateRequest", "SecretInfo", "BootstrapResponse", "UsageReport",
+    # error bodies + version
+    "ErrorCode", "ErrorBody", "WarmingError", "CONTRACT_VERSION",
+    # obs
+    "HEADER", "new_rid", "clean", "log", "Timer", "enabled",
+    # errors (exception taxonomy)
+    "TransportUnavailable", "TransportWarming", "TransportRejected", "TransportOverloaded",
+    # auth + telemetry
+    "auth", "WorkerLogEvent",
+]
+
+__version__ = "0.3.0"

sequence_base/auth.py

@@ -0,0 +1,35 @@
+"""
+Bearer-token auth helpers — one implementation of the direct-connect / internal secret check.
+
+Three consumers, one rule: the container's inbound guard on a directly-exposed pod's /act, the
+gateway's SEQ_DIRECT_SECRET issuance + its /v1/internal/worker-log secret check, and the worker's
+emit() which builds the outbound header. compare_digest, not `==`, everywhere — a wrong secret must
+not be recoverable from response timing.
+"""
+from __future__ import annotations
+
+import hmac
+
+from sequence_base.constants.headers import AUTH_SCHEME
+
+
+def bearer(secret: str) -> str:
+    """The `Authorization` header value carrying `secret` (`"Bearer <secret>"`)."""
+    return f"{AUTH_SCHEME} {secret}"
+
+
+def verify(header_value: str | None, secret: str) -> bool:
+    """Constant-time check that an incoming `Authorization` header carries `secret`.
+
+    `compare_digest`, not `==`, so a wrong secret cannot be recovered from response timing. A missing
+    header compares against the expected value and fails, without a length-based early-out.
+    """
+    return hmac.compare_digest(header_value or "", bearer(secret))
+
+
+def parse_bearer(header_value: str | None) -> str | None:
+    """The token from a `Bearer <token>` header, or None if the scheme prefix is absent."""
+    prefix = AUTH_SCHEME + " "
+    if header_value and header_value.startswith(prefix):
+        return header_value[len(prefix):]
+    return None

sequence_base/codec/__init__.py

@@ -0,0 +1,25 @@
+"""
+Image codec — the frame <-> wire transform, shared so the SDK (encode) and the worker (decode)
+cannot drift on the wire format, and so the SDK (pre-size) and the gateway (validate geometry) share
+one `resize_with_pad` and one aspect band.
+
+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, ResizeSpec
+"""
+from sequence_base.codec.image import DEFAULT_JPEG_QUALITY, decode, encode
+from sequence_base.codec.resize import (
+    ASPECT_TOLERANCE_PX,
+    MAX_UPLOAD_EDGE,
+    ResizeSpec,
+    ratio_name,
+    refuse_wrong_aspect,
+    resize_with_pad,
+)
+
+__all__ = [
+    "encode", "decode", "DEFAULT_JPEG_QUALITY",
+    "ResizeSpec", "resize_with_pad", "refuse_wrong_aspect", "ratio_name",
+    "MAX_UPLOAD_EDGE", "ASPECT_TOLERANCE_PX",
+]

sequence_base/codec/image.py

@@ -0,0 +1,136 @@
+"""
+The image codec: one camera frame <-> the base64 string the wire carries.
+
+`encode` (frame -> base64 JPEG) is the SDK's client-side path; `decode` (base64 -> uint8 RGB array)
+is the container/worker's server-side path. They live together so the wire format — JPEG, quality
+95, RGB — is defined once and provable by a round-trip test, and so the SDK and the worker cannot
+drift on what they put on and take off the wire.
+
+Pillow is imported lazily inside each function, never at module scope: a caller who only passes
+pre-encoded strings must not need it installed.
+"""
+from __future__ import annotations
+
+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
+# amplitude, q90 0.20%, q85 1.86%, q75 2.86% — 85 and below is where the error jumps by an order of
+# magnitude, that is the line. 95 rather than the empirically-best 90 because the effect is not
+# monotonic in quality on a single frame, and tuning to one frame is fitting noise.
+# {sequences-models models/pi05_droid/handler.py "Q95 MAX|DELTA| 0.0048 0.51% ... Q85 1.86%"}
+DEFAULT_JPEG_QUALITY = 95
+
+
+def encode(frame: Any, spec: ResizeSpec | None = None, *, 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"}
+    """
+    if isinstance(frame, str):
+        return frame
+    if isinstance(frame, (bytes, bytearray)):
+        return base64.b64encode(bytes(frame)).decode()
+
+    try:
+        from PIL import Image
+    except ImportError as e:  # pragma: no cover - depends on the install
+        raise ImportError(
+            "encoding an array or PIL image needs Pillow: pip install 'sequence-base[codec]'. "
+            "Pass an already-encoded base64 str or bytes to avoid it."
+        ) from e
+
+    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:
+        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.
+        img = img.resize((max(1, round(img.width * scale)),
+                          max(1, round(img.height * scale))), Image.LANCZOS)
+
+    buf = io.BytesIO()
+    img.save(buf, format="JPEG", quality=quality)
+    return base64.b64encode(buf.getvalue()).decode()
+
+
+def decode(data: str) -> "Any":
+    """
+    base64 JPEG/PNG -> HxWx3 uint8 RGB array — the worker's server-side inverse of `encode`.
+
+    This is what turns `ImageFrame.data` back into pixels for the model. Send JPEG q95: 16x smaller
+    than a JSON int array, ~0.5% action delta. {sequences-models worker handler decode_image}
+
+    Returns a numpy array; numpy is part of the `[codec]` extra alongside Pillow.
+    """
+    import numpy as np
+    from PIL import Image
+
+    raw = base64.b64decode(data, validate=False)
+    return np.asarray(Image.open(io.BytesIO(raw)).convert("RGB"), dtype=np.uint8)

sequence_base/codec/resize.py

@@ -0,0 +1,147 @@
+"""
+Image resize geometry — the part of the codec that must match the SERVER's own transform, so a
+frame pre-sized by the SDK and one sent raw reach the model as identical pixels.
+
+Extracted verbatim from the SDK's `_core/encode.py`, de-coupled from its `Model` catalogue type:
+`encode` here takes a `ResizeSpec` value object (the geometry three-tuple + a label for errors)
+instead of a `Model`, so the gateway (which validates geometry) and the SDK (which pre-sizes) share
+one implementation of `resize_with_pad` and the aspect band.
+
+Pillow is imported lazily, never at module scope — a caller who only passes pre-encoded strings must
+not need it installed (the SDK's single-dependency promise on a Jetson's pinned environment).
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+
+# The longest edge `encode` uploads when no client_resize is declared. See image.encode for why a
+# cap exists and why this number: 640 is above every served input size (pi05 224x126, GR00T
+# 256x256, cosmos3 640x360/view), so it discards nothing any model reads, and it keeps a phone-sized
+# frame from silently hanging the worker queue (a body over ~2 MB is dropped with no error, no job
+# id). {sequences-models cosmos3_edge_droid/handler.py "A 2.37 MB BODY IS REJECTED BY `/RUN` WITH NO
+#  ERROR AND NO JOB ID; 0.77 MB -> ACCEPTED"} [MEASURED 2026-09-12: capping the long edge at 640
+#  makes cosmos3's three views 0.12 MB vs 1.98 MB native]
+MAX_UPLOAD_EDGE = 640
+
+# How far the letterboxed content block may sit from where training data sits, in pixels along the
+# padded axis. Deliberately the gateway's number, not a looser local one: a frame accepted here and
+# rejected there (or the reverse) is worse than either rule alone.
+# {backend/sequences/api/contract/geometry.py "_TOLERANCE_PX = 5"}
+ASPECT_TOLERANCE_PX = 5
+
+# Wire filter name -> PIL constant. Deliberately small: every entry is a filter some served model's
+# own transform actually uses, so adding one means having read that model's source. `encode` raises
+# on anything not here rather than defaulting -- a silent default is exactly how 0.7.0 shipped
+# LANCZOS against an upstream that uses BILINEAR.
+_FILTERS: dict = {}
+
+
+def filters() -> dict:
+    """Built on first use, because PIL is an optional dependency and this module imports without it."""
+    if not _FILTERS:
+        from PIL import Image
+        _FILTERS.update(bilinear=Image.BILINEAR, bicubic=Image.BICUBIC,
+                        # INTER_AREA's closest PIL equivalent; GR00T uses it, though that model
+                        # declines pre-resizing so this entry is currently unreached.
+                        area=Image.BOX)
+    return _FILTERS
+
+
+@dataclass(frozen=True)
+class ResizeSpec:
+    """The geometry a model declares, de-coupled from any catalogue type. The SDK builds one from its
+    `Model`; the gateway builds one from its `EmbodimentSpec`. Three decisions, made separately:
+
+    - `client_resize`: the target SIZE, in one of two shapes — `{"size": [w, h]}` for a fixed target,
+      or `{"shortest_edge": n}` when the server's step is defined on the short edge. Carries the
+      `"filter"` name too. `None` → fall to MAX_UPLOAD_EDGE.
+    - `input_resize`: the GEOMETRY — `"pad"` (openpi's resize_with_pad, letterbox) or `"stretch"`
+      (unconditional interpolate, cosmos3). `None` treated as `"pad"`.
+    - `aspect_ratio`: the trained aspect. A frame outside it (± ASPECT_TOLERANCE_PX on the content
+      block) is REFUSED, not reshaped. `None` → no aspect check.
+    - `label`: identifies the model in error messages.
+    """
+    client_resize: dict | None = None
+    input_resize: str | None = None
+    aspect_ratio: float | None = None
+    label: str = "model"
+
+
+def refuse_wrong_aspect(img: Any, aspect_ratio: float | None, square: int, label: str) -> None:
+    """
+    Raise if `img`'s ratio would letterbox onto a content block the model never trained on.
+
+    The band is the gateway's, not a new one: the content block may sit within ASPECT_TOLERANCE_PX
+    rows of where training data sits, so a frame is never accepted locally and rejected remotely or
+    the reverse. 16:9 lands at exactly 224/1.7778 = 126 rows; the band admits 848x480 (126.8) and
+    refuses 640x480 (168). {backend/sequences/api/contract/geometry.py `_TOLERANCE_PX = 5`}
+
+    Advice, not just refusal: a narrower true-to-training crop beats a complete out-of-distribution
+    frame — but the caller does the crop, the codec will not do it silently (until 2026-09-16 it
+    centre-cropped every frame, making a 4:3 camera "work" while the model ran on a scene missing
+    12.5% of its height the caller still believed they had sent).
+    """
+    if not aspect_ratio:
+        return
+
+    w, h = img.size
+    ar = w / h
+    # Where the scene lands inside the square, in pixels along the padded axis.
+    extent = square / ar if ar >= 1 else square * ar
+    trained = square / aspect_ratio if aspect_ratio >= 1 else square * aspect_ratio
+    if abs(extent - trained) <= ASPECT_TOLERANCE_PX:
+        return
+
+    axis = "rows" if ar >= 1 else "columns"
+    raise ValueError(
+        f"{label} trained on {aspect_ratio:.4f} ({ratio_name(aspect_ratio)}) frames, and this one "
+        f"is {w}x{h} ({ratio_name(ar)}). Letterboxed it would fill {extent:.0f} {axis} of "
+        f"{square} where training data fills {trained:.0f} — the model would run on a framing it "
+        f"has never seen and return plausible but wrong actions. Crop to "
+        f"{ratio_name(aspect_ratio)} before calling; do not pad to it. The gateway refuses the same "
+        f"frame with HTTP 400, so this is the same rule applied one step earlier."
+    )
+
+
+def ratio_name(ar: float) -> str:
+    """`1.7778` as `16:9`. Falls back to two decimals for ratios with no common name."""
+    for w, h in ((16, 9), (4, 3), (3, 2), (1, 1), (9, 16), (3, 4)):
+        if abs(ar - w / h) / (w / h) < 0.01:
+            return f"{w}:{h}"
+    return f"{ar:.2f}:1"
+
+
+def resize_with_pad(img: Any, width: int, height: int, resample: int) -> Any:
+    """
+    Scale `img` into `width` x `height` keeping its aspect ratio, padding the remainder black.
+
+    This is openpi's `resize_with_pad`, line for line, because the server runs that exact function on
+    whatever arrives. Doing the same operation here means the server's copy hits its own
+    short-circuit (`if images.shape[-3:-1] == (height, width): return images`) and changes nothing,
+    so a frame pre-sized here and a frame sent raw reach the model as the same pixels — by
+    construction, not by coincidence.
+    {openpi packages/openpi-client/src/openpi_client/image_tools.py:44-58 "_RESIZE_WITH_PAD_PIL"}
+
+    Note the truncation: upstream uses `int()`, not `round()`, on both edges. 320x180 into a 224
+    square gives int(180 / (320/224)) = int(126.0) = 126, and reproducing that exactly is the
+    difference between agreeing with the server and being one pixel off.
+    """
+    from PIL import Image
+
+    cur_width, cur_height = img.size
+    if cur_width == width and cur_height == height:
+        return img
+
+    # The long edge decides the scale, so neither axis can overflow the target.
+    ratio = max(cur_width / width, cur_height / height)
+    resized_height = int(cur_height / ratio)
+    resized_width = int(cur_width / ratio)
+    resized = img.resize((resized_width, resized_height), resample=resample)
+
+    # Black, and centred. `max(0, ...)` guards the case where truncation leaves the scaled edge a
+    # pixel longer than the target, which would otherwise paste at a negative offset.
+    canvas = Image.new(resized.mode, (width, height), 0)
+    canvas.paste(resized, (max(0, int((width - resized_width) / 2)),
+                           max(0, int((height - resized_height) / 2))))
+    return canvas

sequence_base/constants/env.py

@@ -0,0 +1,14 @@
+"""SEQ_* environment variable NAMES — a single source. Values live in ~/.config/sequences/, never here."""
+
+DIRECT_SECRET = "SEQ_DIRECT_SECRET"      # inbound /act auth on a public pod
+INTERNAL_SECRET = "SEQ_INTERNAL_SECRET"  # auth for container → gateway telemetry
+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/constants/headers.py

@@ -0,0 +1,5 @@
+"""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/constants/version.py

@@ -0,0 +1,9 @@
+"""Wire protocol version. Bump on a breaking change to contract / codec / telemetry shapes."""
+
+PROTOCOL_VERSION = "1"
+
+# The single version stamped into every exported JSON Schema (as `x-contract-version`), so a consumer
+# 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.1"  # 0.4.0 -> 0.4.1: 契约2 deploy body completed during S3/G4 — DeploymentPolicy.secrets (name-only passthrough), DeploymentRequest.volumes: list[VolumeAttach{uri,mount,create_if_missing}], concurrency default materialized; telemetry events add load_start stage + emitted_at/rid/dedup_key (O4)

sequence_base/contract/__init__.py

@@ -0,0 +1,111 @@
+"""
+The shared wire contract — one definition per shape, imported (never redeclared) by the SDK, gateway,
+and container harness. Grouped by the contract number in docs/platform/contracts.md.
+"""
+# contract 4 — /act data plane (obs/action DATA types)
+from sequence_base.contract.act import (
+    ActionChunk,
+    ActionSpace,
+    ActionStep,
+    ImageFrame,
+    Observation,
+    Proprioception,
+)
+
+# contract 1 — lifecycle flags + policy registry
+from sequence_base.contract.flags import SeqFlags
+from sequence_base.contract.policy import (
+    ActionContract,
+    Concurrency,
+    ImageSpec,
+    ImageStep,
+    ImageStepApt,
+    ImageStepEnv,
+    ImageStepRun,
+    ImageStepUvPip,
+    PolicyRegistration,
+    PolicySpec,
+    VolumeMount,
+    VolumeRef,
+)
+
+# contract 2 — deployments
+from sequence_base.contract.deployments import (
+    MAX_CODE_BUNDLE_BYTES,
+    Autoscaler,
+    CodeBundle,
+    DeploymentAccepted,
+    DeploymentPolicy,
+    DeploymentRequest,
+    DeploymentState,
+    DeploymentStatusResponse,
+    Resources,
+    Timeouts,
+    VolumeAttach,
+)
+
+# contract 3 — connect / lease
+from sequence_base.contract.connect import ConnectRequest, ConnectResponse, Lease
+
+# contract 5 — benchmark registration + eval run / report / adapter
+from sequence_base.contract.benchmarks import (
+    BenchmarkRegisterRequest,
+    BenchmarkSpec,
+    Conditions,
+    RenderSpec,
+    Step,
+    Variant,
+)
+from sequence_base.contract.eval import (
+    AdapterKind,
+    AdapterTransform,
+    ClampInfo,
+    Estimate,
+    EvalDryRunResponse,
+    EvalReport,
+    EvalRequest,
+    EvalResponse,
+    EvalStatus,
+    LossyTransform,
+    MetricAgg,
+    RolloutResult,
+    SuiteAgg,
+    TaskAgg,
+)
+
+# contract 6 — accounts / secret / billing
+from sequence_base.contract.accounts import (
+    BootstrapResponse,
+    SecretCreateRequest,
+    SecretInfo,
+    SecretRef,
+    UsageReport,
+)
+
+# shared error bodies
+from sequence_base.contract.errors import ErrorBody, ErrorCode, WarmingError
+
+__all__ = [
+    # contract 4
+    "ImageFrame", "Proprioception", "Observation", "ActionSpace", "ActionStep", "ActionChunk",
+    # contract 1
+    "SeqFlags",
+    "ImageStepUvPip", "ImageStepApt", "ImageStepEnv", "ImageStepRun", "ImageStep", "ImageSpec",
+    "VolumeMount", "VolumeRef", "Concurrency", "ActionContract",
+    "PolicySpec", "PolicyRegistration",
+    # contract 2
+    "MAX_CODE_BUNDLE_BYTES", "CodeBundle",
+    "Resources", "Autoscaler", "Timeouts", "VolumeAttach", "DeploymentPolicy", "DeploymentRequest",
+    "DeploymentAccepted", "DeploymentState", "DeploymentStatusResponse",
+    # contract 3
+    "Lease", "ConnectRequest", "ConnectResponse",
+    # contract 5
+    "Variant", "Conditions", "RenderSpec", "Step", "BenchmarkSpec", "BenchmarkRegisterRequest",
+    "EvalRequest", "ClampInfo", "Estimate", "EvalResponse", "EvalDryRunResponse", "RolloutResult",
+    "EvalStatus", "SuiteAgg", "TaskAgg", "MetricAgg", "LossyTransform", "EvalReport",
+    "AdapterKind", "AdapterTransform",
+    # contract 6
+    "SecretRef", "SecretCreateRequest", "SecretInfo", "BootstrapResponse", "UsageReport",
+    # errors
+    "ErrorCode", "ErrorBody", "WarmingError",
+]