sequence-base 0.3.3__tar.gz → 0.3.4__tar.gz

{sequence_base-0.3.3 → sequence_base-0.3.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: sequence-base
-Version: 0.3.3
+Version: 0.3.4
 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-Dist: pydantic>=2.0

{sequence_base-0.3.3 → sequence_base-0.3.4}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "sequence-base"
-version = "0.3.3"
+version = "0.3.4"
 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"
 dependencies = ["pydantic>=2.0"]

{sequence_base-0.3.3 → sequence_base-0.3.4}/sequence_base/__init__.py

@@ -14,6 +14,9 @@ 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)
+    Camera,
+    Embodiment,
+    ObservationContract,
     MAX_CODE_BUNDLE_BYTES,
     UploadTarget,
     VolumeFile,
@@ -114,7 +117,8 @@ __all__ = [
     "ImageFrame", "Proprioception", "Observation", "ActionSpace", "ActionStep", "ActionChunk",
     # contract 1 — flags + policy registry
     "SeqFlags", "ImageStepUvPip", "ImageStepApt", "ImageStepEnv", "ImageStepRun", "ImageStep", "ImageSpec",
-    "VolumeMount", "VolumeRef", "Concurrency", "ActionContract", "PolicySpec", "PolicyRegistration",
+    "VolumeMount", "VolumeRef", "Concurrency", "ActionContract", "Camera", "ObservationContract", "Embodiment",
+    "PolicySpec", "PolicyRegistration",
     # contract 2 — deployments
     "MAX_CODE_BUNDLE_BYTES", "CodeBundle",
     "Resources", "Autoscaler", "Timeouts", "VolumeAttach", "DeploymentPolicy", "DeploymentRequest",
@@ -140,4 +144,4 @@ __all__ = [
     "auth", "WorkerLogEvent",
 ]
 
-__version__ = "0.3.3"
+__version__ = "0.3.4"

{sequence_base-0.3.3 → sequence_base-0.3.4}/sequence_base/constants/version.py

@@ -6,5 +6,6 @@ PROTOCOL_VERSION = "1"
 # 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.2"  # 0.4.1 -> 0.4.2: 契约7 volumes (uploads: VolumeFile/VolumeUploadRequest/UploadTarget/VolumeUploadResponse/VolumeInfo), weights accept vol://<name>[@v<n>]; DeploymentRequest name is a slug and weights need an origin
+CONTRACT_VERSION = "0.4.3"  # 0.4.2 -> 0.4.3: I/O contract — ObservationContract/Camera/Embodiment on PolicySpec + DeploymentPolicy, Observation.state, ConnectRequest.embodiment, ConnectResponse.action/observation/embodiment
+# previous: 0.4.2  # 0.4.1 -> 0.4.2: 契约7 volumes (uploads: VolumeFile/VolumeUploadRequest/UploadTarget/VolumeUploadResponse/VolumeInfo), weights accept vol://<name>[@v<n>]; DeploymentRequest name is a slug and weights need an origin
 # previous: 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-0.3.3 → sequence_base-0.3.4}/sequence_base/contract/__init__.py

@@ -15,6 +15,9 @@ from sequence_base.contract.act import (
 # contract 1 — lifecycle flags + policy registry
 from sequence_base.contract.flags import SeqFlags
 from sequence_base.contract.policy import (
+    Camera,
+    Embodiment,
+    ObservationContract,
     ActionContract,
     Concurrency,
     ImageSpec,
@@ -105,7 +108,7 @@ __all__ = [
     # contract 1
     "SeqFlags",
     "ImageStepUvPip", "ImageStepApt", "ImageStepEnv", "ImageStepRun", "ImageStep", "ImageSpec",
-    "VolumeMount", "VolumeRef", "Concurrency", "ActionContract",
+    "VolumeMount", "VolumeRef", "Concurrency", "ActionContract", "Camera", "ObservationContract", "Embodiment",
     "PolicySpec", "PolicyRegistration",
     # contract 2
     "MAX_CODE_BUNDLE_BYTES", "CodeBundle",

{sequence_base-0.3.3 → sequence_base-0.3.4}/sequence_base/contract/act.py

@@ -50,6 +50,9 @@ class Observation(BaseModel):
     images: list[ImageFrame] = Field(..., min_length=1, max_length=256)
     proprioception: Proprioception
     instruction: str
+    # Named state vectors that are not joints — an end-effector axis-angle, an object pose — so they need not
+    # be smuggled into joint_positions. Absent when the policy declares none. {io-contract.md "Observation.state"}
+    state: dict[str, list[float]] | None = None
 
 
 class ActionSpace(str, Enum):

{sequence_base-0.3.3 → sequence_base-0.3.4}/sequence_base/contract/connect.py

@@ -15,6 +15,7 @@ from pydantic import BaseModel, ConfigDict, Field
 
 # The 503 cold/warming body is defined once in contract.errors and reused here — no second shape.
 from sequence_base.contract.errors import WarmingError
+from sequence_base.contract.io import ActionContract, ObservationContract
 
 __all__ = ["Lease", "ConnectRequest", "ConnectResponse", "WarmingError"]
 
@@ -35,6 +36,7 @@ class ConnectRequest(BaseModel):
     model_config = ConfigDict(extra="forbid")
 
     model: str = Field(..., description="Deployment name to connect to")
+    embodiment: str | None = Field(default=None, description="Which declared embodiment this session drives")
 
 
 class ConnectResponse(BaseModel):
@@ -51,3 +53,7 @@ class ConnectResponse(BaseModel):
     lease: Lease
     warming: bool = Field(default=False, description="True → worker still warming; see warming_eta_s")
     warming_eta_s: int | None = Field(default=None, description="Seconds until warm, when warming")
+    # The contracts this session is held to, so the client can check and assemble before the first act.
+    action: ActionContract | None = None
+    observation: ObservationContract | None = None
+    embodiment: str | None = None

{sequence_base-0.3.3 → sequence_base-0.3.4}/sequence_base/contract/deployments.py

@@ -22,6 +22,7 @@ from pydantic import BaseModel, ConfigDict, Field, field_validator, model_valida
 
 from sequence_base.contract.accounts import SecretRef
 from sequence_base.contract.volumes import VOL_SCHEME, parse_vol
+from sequence_base.contract.io import Embodiment, ObservationContract
 from sequence_base.contract.policy import (
     ActionContract,
     Concurrency,
@@ -104,6 +105,15 @@ class DeploymentPolicy(BaseModel):
     streaming: bool = False
     frames_per_chunk: int | None = None
     secrets: list[SecretRef] = Field(default_factory=list)
+    # The observation contract the worker checks every /act against (None: undeclared), and per-robot
+    # 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"}
+    action_declared: bool | None = None
 
 
 MAX_CODE_BUNDLE_BYTES = 8 * 1024 * 1024

sequence_base-0.3.4/sequence_base/contract/io.py

@@ -0,0 +1,83 @@
+"""
+The I/O contract — what a policy reads and what it returns, declared once and checked everywhere.
+
+In one sentence: the author declares `action=` (and `observation=`, or per-robot `embodiments=`) on `@seq.policy`
+→ it rides the deploy body into the worker's manifest → the worker refuses an /act whose observation does not
+match before inference, and a chunk that does not match before it leaves → connect hands the same contracts to
+the robot, which checks and assembles against them. {gs-plans/customization/io-contract.md}
+
+Kept in its own module (not policy.py) because both the policy declaration and the connect response use it, and
+policy → accounts → connect would otherwise import back into policy.
+"""
+from __future__ import annotations
+
+from typing import Any
+
+from pydantic import BaseModel, ConfigDict, Field, field_validator
+
+from sequence_base.contract.act import ActionSpace
+
+
+class ActionContract(BaseModel):
+    """The fixed obs→ActionChunk contract a policy promises. Every field required; `action_space` reuses
+    contract 4's enum (not a free string). Each ActionChunk echoes exactly these invariants back."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    robot: str
+    action_space: ActionSpace
+    action_dim: int
+    control_frequency_hz: float
+
+
+# The proprioception fields an observation contract may require, with the wire field each one names.
+PROPRIO_FIELDS = ("joint_positions", "joint_velocities", "end_effector_pose", "gripper")
+
+
+class Camera(BaseModel):
+    """One camera view a policy reads: the size it expects. Informational at the worker (the policy resizes);
+    the client resizes and letterboxes to it before sending, so the bytes on the wire are what is used."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    width: int = Field(..., gt=0, le=8192)
+    height: int = Field(..., gt=0, le=8192)
+
+
+class ObservationContract(BaseModel):
+    """What a policy reads, declared once: the worker checks every /act against it before inference, the
+    client assembles to it. An observation that does not match is refused with what is missing — it is never
+    inferred on. {gs-plans/customization/io-contract.md "二、观测契约"}"""
+
+    model_config = ConfigDict(extra="forbid")
+
+    cameras: dict[str, Camera] = Field(default_factory=dict, description="view name → expected size")
+    history: int = Field(default=1, ge=1, le=64, description="frames per view the policy reads")
+    proprio: dict[str, int] = Field(default_factory=dict,
+                                    description="proprioception field → its length, e.g. joint_positions: 7")
+    state: dict[str, int] = Field(default_factory=dict,
+                                  description="named extra state vector → its length (Observation.state)")
+    instruction: bool = Field(default=True, description="whether a non-empty instruction is required")
+
+    @field_validator("proprio")
+    @classmethod
+    def _known_proprio(cls, v: dict[str, int]) -> dict[str, int]:
+        bad = sorted(set(v) - set(PROPRIO_FIELDS))
+        if bad:
+            raise ValueError(f"proprio keys must be among {PROPRIO_FIELDS}; got {bad} — put other vectors in state=")
+        if any(n < 1 for n in v.values()):
+            raise ValueError("each proprio length must be at least 1")
+        return v
+
+
+class Embodiment(BaseModel):
+    """One robot body a multi-embodiment policy serves: its action contract, its observation contract, and
+    free-form metadata the policy reads (e.g. which normalisation statistics). Chosen per session at connect."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    action: ActionContract
+    observation: ObservationContract | None = None
+    meta: dict[str, Any] = Field(default_factory=dict)
+
+

{sequence_base-0.3.3 → sequence_base-0.3.4}/sequence_base/contract/policy.py

@@ -8,10 +8,19 @@ Every shape here forbids unknown fields and pins exact field types — no `Optio
 """
 from __future__ import annotations
 
+from typing import Any
+
 from pydantic import BaseModel, ConfigDict, Field, field_validator, model_validator
 
 from sequence_base.contract.accounts import SecretRef
-from sequence_base.contract.act import ActionSpace
+from sequence_base.contract.act import ActionSpace  # noqa: F401 — re-exported for older imports
+from sequence_base.contract.io import (  # noqa: F401 — the I/O contract lives in io.py, re-exported here
+    PROPRIO_FIELDS,
+    ActionContract,
+    Camera,
+    Embodiment,
+    ObservationContract,
+)
 from sequence_base.contract.flags import SeqFlags
 
 __all__ = [
@@ -112,18 +121,6 @@ class Concurrency(BaseModel):
     target_inputs: int
 
 
-class ActionContract(BaseModel):
-    """The fixed obs→ActionChunk contract a policy promises. Every field required; `action_space` reuses
-    contract 4's enum (not a free string). Each ActionChunk echoes exactly these invariants back."""
-
-    model_config = ConfigDict(extra="forbid")
-
-    robot: str
-    action_space: ActionSpace
-    action_dim: int
-    control_frequency_hz: float
-
-
 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."""
@@ -144,6 +141,9 @@ class PolicySpec(BaseModel):
     streaming: bool = False
     frames_per_chunk: int | None = None
     action: ActionContract
+    # 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
 
     @field_validator("weights")
     @classmethod

{sequence_base-0.3.3 → sequence_base-0.3.4}/sequence_base/schema_export.py

@@ -79,6 +79,9 @@ from sequence_base.contract.eval import (
 )
 from sequence_base.contract.flags import seqflags_json_schema
 from sequence_base.contract.policy import (
+    Camera,
+    Embodiment,
+    ObservationContract,
     ActionContract,
     Concurrency,
     ImageSpec,
@@ -113,6 +116,9 @@ WIRE_MODELS: dict[str, type[BaseModel]] = {
     "VolumeRef": VolumeRef,
     "Concurrency": Concurrency,
     "ActionContract": ActionContract,
+    "Camera": Camera,
+    "ObservationContract": ObservationContract,
+    "Embodiment": Embodiment,
     "PolicySpec": PolicySpec,
     "PolicyRegistration": PolicyRegistration,
     # contract 2 — deployments

{sequence_base-0.3.3 → sequence_base-0.3.4}/sequence_base/schemas/ActionChunk.json

@@ -98,5 +98,5 @@
   ],
   "title": "ActionChunk",
   "type": "object",
-  "x-contract-version": "0.4.2"
+  "x-contract-version": "0.4.3"
 }

{sequence_base-0.3.3 → sequence_base-0.3.4}/sequence_base/schemas/ActionContract.json

@@ -39,5 +39,5 @@
   ],
   "title": "ActionContract",
   "type": "object",
-  "x-contract-version": "0.4.2"
+  "x-contract-version": "0.4.3"
 }

{sequence_base-0.3.3 → sequence_base-0.3.4}/sequence_base/schemas/ActionStep.json

@@ -19,5 +19,5 @@
   ],
   "title": "ActionStep",
   "type": "object",
-  "x-contract-version": "0.4.2"
+  "x-contract-version": "0.4.3"
 }

{sequence_base-0.3.3 → sequence_base-0.3.4}/sequence_base/schemas/AdapterTransform.json

@@ -38,5 +38,5 @@
   ],
   "title": "AdapterTransform",
   "type": "object",
-  "x-contract-version": "0.4.2"
+  "x-contract-version": "0.4.3"
 }

{sequence_base-0.3.3 → sequence_base-0.3.4}/sequence_base/schemas/Autoscaler.json

@@ -39,5 +39,5 @@
   },
   "title": "Autoscaler",
   "type": "object",
-  "x-contract-version": "0.4.2"
+  "x-contract-version": "0.4.3"
 }

{sequence_base-0.3.3 → sequence_base-0.3.4}/sequence_base/schemas/BenchmarkRegisterRequest.json

@@ -393,5 +393,5 @@
   ],
   "title": "BenchmarkRegisterRequest",
   "type": "object",
-  "x-contract-version": "0.4.2"
+  "x-contract-version": "0.4.3"
 }

{sequence_base-0.3.3 → sequence_base-0.3.4}/sequence_base/schemas/BenchmarkSpec.json

@@ -207,7 +207,7 @@
       ],
       "title": "SeqFlags",
       "type": "integer",
-      "x-contract-version": "0.4.2",
+      "x-contract-version": "0.4.3",
       "x-flag-names": {
         "CHECK": 65536,
         "INFER": 16,
@@ -397,5 +397,5 @@
   ],
   "title": "BenchmarkSpec",
   "type": "object",
-  "x-contract-version": "0.4.2"
+  "x-contract-version": "0.4.3"
 }

{sequence_base-0.3.3 → sequence_base-0.3.4}/sequence_base/schemas/BenchmarkStatusResponse.json

@@ -40,5 +40,5 @@
   ],
   "title": "BenchmarkStatusResponse",
   "type": "object",
-  "x-contract-version": "0.4.2"
+  "x-contract-version": "0.4.3"
 }

{sequence_base-0.3.3 → sequence_base-0.3.4}/sequence_base/schemas/BootstrapResponse.json

@@ -72,5 +72,5 @@
   ],
   "title": "BootstrapResponse",
   "type": "object",
-  "x-contract-version": "0.4.2"
+  "x-contract-version": "0.4.3"
 }

sequence_base-0.3.4/sequence_base/schemas/Camera.json

@@ -0,0 +1,25 @@
+{
+  "additionalProperties": false,
+  "description": "One camera view a policy reads: the size it expects. Informational at the worker (the policy resizes);\nthe client resizes and letterboxes to it before sending, so the bytes on the wire are what is used.",
+  "properties": {
+    "height": {
+      "exclusiveMinimum": 0,
+      "maximum": 8192,
+      "title": "Height",
+      "type": "integer"
+    },
+    "width": {
+      "exclusiveMinimum": 0,
+      "maximum": 8192,
+      "title": "Width",
+      "type": "integer"
+    }
+  },
+  "required": [
+    "width",
+    "height"
+  ],
+  "title": "Camera",
+  "type": "object",
+  "x-contract-version": "0.4.3"
+}

{sequence_base-0.3.3 → sequence_base-0.3.4}/sequence_base/schemas/ClampInfo.json

@@ -23,5 +23,5 @@
   ],
   "title": "ClampInfo",
   "type": "object",
-  "x-contract-version": "0.4.2"
+  "x-contract-version": "0.4.3"
 }

{sequence_base-0.3.3 → sequence_base-0.3.4}/sequence_base/schemas/CodeBundle.json

@@ -23,5 +23,5 @@
   ],
   "title": "CodeBundle",
   "type": "object",
-  "x-contract-version": "0.4.2"
+  "x-contract-version": "0.4.3"
 }

{sequence_base-0.3.3 → sequence_base-0.3.4}/sequence_base/schemas/Concurrency.json

@@ -17,5 +17,5 @@
   ],
   "title": "Concurrency",
   "type": "object",
-  "x-contract-version": "0.4.2"
+  "x-contract-version": "0.4.3"
 }

{sequence_base-0.3.3 → sequence_base-0.3.4}/sequence_base/schemas/Conditions.json

@@ -55,5 +55,5 @@
   ],
   "title": "Conditions",
   "type": "object",
-  "x-contract-version": "0.4.2"
+  "x-contract-version": "0.4.3"
 }

sequence_base-0.3.4/sequence_base/schemas/ConnectRequest.json

@@ -0,0 +1,29 @@
+{
+  "additionalProperties": false,
+  "properties": {
+    "embodiment": {
+      "anyOf": [
+        {
+          "type": "string"
+        },
+        {
+          "type": "null"
+        }
+      ],
+      "default": null,
+      "description": "Which declared embodiment this session drives",
+      "title": "Embodiment"
+    },
+    "model": {
+      "description": "Deployment name to connect to",
+      "title": "Model",
+      "type": "string"
+    }
+  },
+  "required": [
+    "model"
+  ],
+  "title": "ConnectRequest",
+  "type": "object",
+  "x-contract-version": "0.4.3"
+}