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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: sequence-base
-Version: 0.3.17
+Version: 0.3.18
 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.10
 Requires-Dist: pydantic>=2.0

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

@@ -1,6 +1,6 @@
 [project]
 name = "sequence-base"
-version = "0.3.17"
+version = "0.3.18"
 description = "Shared foundation for the Sequences platform — wire contract, correlation, error taxonomy, constants. Used by the robot SDK, gateway, and container harness."
 # 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"}

{sequence_base-0.3.17 → sequence_base-0.3.18}/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.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)
+CONTRACT_VERSION = "0.4.15"  # 0.4.14 -> 0.4.15: limits count GPUs and CPU/memory are billed like Modal — Resources.cpu / memory_gb optional floats + cpu_limit / memory_limit_gb; Autoscaler.max_gpus / on_full / queue_timeout_s replace max_containers; Concurrency fields optional + replicas_per_gpu / gpus_per_replica; DeploymentStatusResponse.reason; EvalRequest.policy_instances / policy_gpu / benchmark_instances / benchmark_gpu / envs replace gpus / envs_per_gpu; EvalStatus.QUEUED; EvalCards / EvalQueue
+# previous: 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)

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

@@ -52,12 +52,24 @@ class Resources(BaseModel):
     model_config = ConfigDict(extra="forbid")
 
     gpu: list[str]
-    cpu: int
-    memory_gb: int
+    # Physical cores and GiB the worker requests, billed like Modal: per second, at the greater of the request and what
+    # it uses. None requests the minimum (0.125 cores, 0.125 GiB) and the worker may use more. A limit caps what it may
+    # use; None leaves it free to burst. {gs-plans/parallel/cpu-memory.md "4. 默认申请量照 Modal"}
+    cpu: float | None = Field(default=None, ge=0.125, le=64)
+    cpu_limit: float | None = Field(default=None, ge=0.125, le=128)
+    memory_gb: float | None = Field(default=None, ge=0.125, le=1024)
+    memory_limit_gb: float | None = Field(default=None, ge=0.125, le=1024)
     # Where the workers run (near the robots): one of the regions the platform offers. None: the platform picks.
     # {gs-plans/customization/policy.md "区域"}
     region: str | None = Field(default=None, max_length=32)
 
+    @model_validator(mode="after")
+    def _limits_cover_requests(self) -> "Resources":
+        for what, req, lim in (("cpu", self.cpu, self.cpu_limit), ("memory", self.memory_gb, self.memory_limit_gb)):
+            if req is not None and lim is not None and lim < req:
+                raise ValueError(f"the {what} limit must be at least the {what} request")
+        return self
+
 
 class Autoscaler(BaseModel):
     """How the deployment scales. Defaults mirror PolicySpec so an omitted block scales to zero."""
@@ -65,9 +77,18 @@ class Autoscaler(BaseModel):
     model_config = ConfigDict(extra="forbid")
 
     min_containers: int = 0
+    # Accepted and ignored: limits count GPUs (`max_gpus`). sequence-ai <= 0.28 still sends it and does not pin
+    # sequence-base, so removing it would break their deploys; it goes when no supported SDK sends it.
     max_containers: int | None = None
+    # The most GPUs this deployment may hold at once. None: no cap of its own — only the account's and the platform's
+    # GPU limits bound it. Limits count cards, never machines. {gs-plans/parallel/serving.md "1. 限制按卡数,不按台数"}
+    max_gpus: int | None = Field(default=None, ge=1, le=256)
     buffer_containers: int | None = None
     scaledown_window: int = 600
+    # When every slot is taken and no card is left: queue the new robot before its control loop starts, or refuse it at
+    # once; how long a queued robot waits before it is told why. {gs-plans/parallel/serving-queue.md "connect 的处理顺序"}
+    on_full: Literal["queue", "reject"] = "queue"
+    queue_timeout_s: int = Field(default=120, ge=5, le=3600)
 
 
 class Timeouts(BaseModel):
@@ -205,11 +226,8 @@ class DeploymentRequest(BaseModel):
     # both key and value; the gateway only stores the dump, no consumer needs dict lookup.
     volumes: list[VolumeAttach] = Field(default_factory=list)
     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 — same discipline as `autoscaler`
-    # (goal 13).
-    concurrency: Concurrency = Field(default_factory=lambda: Concurrency(max_inputs=1, target_inputs=1))
+    # Every field optional: an omitted @seq.concurrent serves one robot session per model copy, one copy per card.
+    concurrency: Concurrency = Field(default_factory=Concurrency)
     timeouts: Timeouts | None = None
     # Weights in several named parts: `weights` is the first and `weights_name` its name; `extra_weights` the others,
     # each provisioned like `weights`. @seq.load then receives {name: directory}. Both None (and absent from the wire):
@@ -283,3 +301,5 @@ class DeploymentStatusResponse(BaseModel):
     status: DeploymentState
     model: str
     error: str | None = Field(default=None, description="Build-failure reason; set only when FAILED")
+    # Why a deployment that was serving was marked FAILED: its workers kept dying of the same cause.
+    reason: Literal["gpu_out_of_memory", "host_out_of_memory", "crashed"] | None = None

{sequence_base-0.3.17 → sequence_base-0.3.18}/sequence_base/contract/eval.py

@@ -20,6 +20,10 @@ __all__ = [
     "Estimate",
     "EvalResponse",
     "EvalDryRunResponse",
+    "CardSide",
+    "CardInUse",
+    "EvalCards",
+    "EvalQueue",
     "RolloutResult",
     "EvalStatus",
     "SuiteAgg",
@@ -42,8 +46,15 @@ class EvalRequest(BaseModel):
     benchmark: str
     suite: str | None = None
     trials: int | None = None
-    gpus: int | None = None
-    envs_per_gpu: int | None = None
+    # How the eval is laid out, written by the user and never derived: how many policy machines and on which card
+    # (default: one, on the deployment's declared card), how many benchmark machines and on which card (default: one,
+    # on the benchmark's declared card), and how many environments each benchmark machine runs (default: the
+    # benchmark author's `envs=`, else 1). {gs-plans/parallel/eval.md "1. 两边写法对齐"}
+    policy_instances: int = Field(default=1, ge=1, le=64)
+    policy_gpu: str | None = Field(default=None, max_length=32)
+    benchmark_instances: int = Field(default=1, ge=1, le=64)
+    benchmark_gpu: str | None = Field(default=None, max_length=32)
+    envs: int | None = Field(default=None, ge=1, le=100000)
     vlm_max_concurrency: int | None = None
     adapter: str | None = None
     compare: str | None = Field(default=None, description="Another model id to compare against")
@@ -90,6 +101,56 @@ class EvalResponse(BaseModel):
     gpus_granted: int
     estimate: Estimate
     clamped_by: ClampInfo | None = None
+    # Set when the account was short of GPUs: the eval waits (up to its timeout) instead of being refused.
+    queue: EvalQueue | None = None
+
+
+class CardSide(BaseModel):
+    """One side of an eval's machines: how many, on which card, and how many GPUs each holds."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    instances: int
+    gpu: str
+    cards_each: int
+
+
+class CardInUse(BaseModel):
+    """The account's GPUs held now, serving and evals apart; None when it could not be read."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    serving: int | None = None
+    eval: int | None = None
+
+
+class EvalCards(BaseModel):
+    """The dry-run's card report — the same checks a real submit runs, without starting or charging anything.
+    {gs-plans/parallel/eval.md "4. 预演里卡的部分"}"""
+
+    model_config = ConfigDict(extra="forbid")
+
+    policy: CardSide
+    benchmark: CardSide
+    total: int
+    limit: int
+    in_use: CardInUse
+    available: int | None = None
+    short: int = 0
+    reason: Literal["gpu_limit_reached", "gpu_busy", "gpu_low_stock"] | None = None
+    would_queue: bool = False
+    queue_timeout_s: int = 600
+
+
+class EvalQueue(BaseModel):
+    """An eval waiting for the account's GPUs: what it needs, what is free, how long it has waited, when it gives up."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    cards: int
+    available: int | None = None
+    waited_s: float = 0
+    gives_up_at: str | None = None
 
 
 class EvalDryRunResponse(BaseModel):
@@ -98,6 +159,7 @@ class EvalDryRunResponse(BaseModel):
     model_config = ConfigDict(extra="forbid")
 
     estimate: Estimate
+    cards: EvalCards | None = None
 
 
 class RolloutResult(BaseModel):
@@ -124,6 +186,7 @@ class EvalStatus(str, Enum):
     """Restricted enum — same discipline as DeploymentState (not a free string)."""
 
     PENDING = "pending"
+    QUEUED = "queued"
     RUNNING = "running"
     COMPLETED = "completed"
     FAILED = "failed"

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

@@ -10,7 +10,7 @@ from __future__ import annotations
 
 import re
 
-from typing import Any
+from typing import Any, Literal
 
 from pydantic import BaseModel, ConfigDict, Field, field_validator, model_validator
 
@@ -153,12 +153,26 @@ class VolumeRef(BaseModel):
 
 
 class Concurrency(BaseModel):
-    """How many inputs one container serves at once: the most it takes, and the level it scales to hold. Both required."""
+    """How one worker serves robots, every field optional. `replicas_per_gpu` model copies share each card (each copy is
+    its own process and serves one control loop); `gpus_per_replica` cards make one copy (None: every card of the
+    worker). A worker's slots = cards // gpus_per_replica × replicas_per_gpu. `target_inputs` is how many robot sessions
+    a worker holds before another starts, `max_inputs` the most it takes while a new one boots — both default to the
+    slots. {gs-plans/parallel/serving.md "2. 一台 worker 里" / "3. 一台 worker 多张卡"}"""
 
     model_config = ConfigDict(extra="forbid")
 
-    max_inputs: int
-    target_inputs: int
+    max_inputs: int | None = Field(default=None, ge=1, le=1024)
+    target_inputs: int | None = Field(default=None, ge=1, le=1024)
+    replicas_per_gpu: int | None = Field(default=None, ge=1, le=64)
+    gpus_per_replica: int | None = Field(default=None, ge=1, le=256)
+
+    @model_validator(mode="after")
+    def _consistent(self) -> "Concurrency":
+        if self.max_inputs is not None and self.target_inputs is not None and self.max_inputs < self.target_inputs:
+            raise ValueError("max_inputs must be at least target_inputs")
+        if (self.gpus_per_replica or 1) > 1 and (self.replicas_per_gpu or 1) > 1:
+            raise ValueError("a copy that spans several cards is one copy per card group: replicas_per_gpu must be 1")
+        return self
 
 
 class PolicySpec(BaseModel):
@@ -176,9 +190,14 @@ class PolicySpec(BaseModel):
     volumes: dict[str, VolumeRef] = Field(default_factory=dict)
     secrets: list[SecretRef] = Field(default_factory=list)
     min_containers: int = 0
+    # Accepted and ignored: limits count GPUs (`max_gpus`). sequence-ai <= 0.28 still sends it and does not pin
+    # sequence-base, so removing it would break their deploys; it goes when no supported SDK sends it.
     max_containers: int | None = None
+    max_gpus: int | None = Field(default=None, ge=1, le=256)
     buffer_containers: int | None = None
     scaledown_window: int = 600
+    on_full: Literal["queue", "reject"] = "queue"
+    queue_timeout_s: int = Field(default=120, ge=5, le=3600)
     concurrency: Concurrency | None = None
     streaming: bool = False
     frames_per_chunk: int | None = None

{sequence_base-0.3.17 → sequence_base-0.3.18}/sequence_base/schemas/ActRequest.json

@@ -65,5 +65,5 @@
   ],
   "title": "ActRequest",
   "type": "object",
-  "x-contract-version": "0.4.14"
+  "x-contract-version": "0.4.15"
 }

{sequence_base-0.3.17 → sequence_base-0.3.18}/sequence_base/schemas/ActResponse.json

@@ -75,5 +75,5 @@
   ],
   "title": "ActResponse",
   "type": "object",
-  "x-contract-version": "0.4.14"
+  "x-contract-version": "0.4.15"
 }

{sequence_base-0.3.17 → sequence_base-0.3.18}/sequence_base/schemas/ActionChunk.json

@@ -99,5 +99,5 @@
   ],
   "title": "ActionChunk",
   "type": "object",
-  "x-contract-version": "0.4.14"
+  "x-contract-version": "0.4.15"
 }

{sequence_base-0.3.17 → sequence_base-0.3.18}/sequence_base/schemas/ActionContract.json

@@ -100,5 +100,5 @@
   ],
   "title": "ActionContract",
   "type": "object",
-  "x-contract-version": "0.4.14"
+  "x-contract-version": "0.4.15"
 }

{sequence_base-0.3.17 → sequence_base-0.3.18}/sequence_base/schemas/ActionStep.json

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

{sequence_base-0.3.17 → sequence_base-0.3.18}/sequence_base/schemas/AdapterTransform.json

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

{sequence_base-0.3.17 → sequence_base-0.3.18}/sequence_base/schemas/AddLocal.json

@@ -23,5 +23,5 @@
   ],
   "title": "AddLocal",
   "type": "object",
-  "x-contract-version": "0.4.14"
+  "x-contract-version": "0.4.15"
 }

{sequence_base-0.3.17 → sequence_base-0.3.18}/sequence_base/schemas/Autoscaler.json

@@ -26,11 +26,41 @@
       "default": null,
       "title": "Max Containers"
     },
+    "max_gpus": {
+      "anyOf": [
+        {
+          "maximum": 256,
+          "minimum": 1,
+          "type": "integer"
+        },
+        {
+          "type": "null"
+        }
+      ],
+      "default": null,
+      "title": "Max Gpus"
+    },
     "min_containers": {
       "default": 0,
       "title": "Min Containers",
       "type": "integer"
     },
+    "on_full": {
+      "default": "queue",
+      "enum": [
+        "queue",
+        "reject"
+      ],
+      "title": "On Full",
+      "type": "string"
+    },
+    "queue_timeout_s": {
+      "default": 120,
+      "maximum": 3600,
+      "minimum": 5,
+      "title": "Queue Timeout S",
+      "type": "integer"
+    },
     "scaledown_window": {
       "default": 600,
       "title": "Scaledown Window",
@@ -39,5 +69,5 @@
   },
   "title": "Autoscaler",
   "type": "object",
-  "x-contract-version": "0.4.14"
+  "x-contract-version": "0.4.15"
 }

{sequence_base-0.3.17 → sequence_base-0.3.18}/sequence_base/schemas/BenchmarkConditionSpec.json

@@ -62,5 +62,5 @@
   ],
   "title": "BenchmarkConditionSpec",
   "type": "object",
-  "x-contract-version": "0.4.14"
+  "x-contract-version": "0.4.15"
 }

{sequence_base-0.3.17 → sequence_base-0.3.18}/sequence_base/schemas/BenchmarkRegisterRequest.json

@@ -681,5 +681,5 @@
   ],
   "title": "BenchmarkRegisterRequest",
   "type": "object",
-  "x-contract-version": "0.4.14"
+  "x-contract-version": "0.4.15"
 }

{sequence_base-0.3.17 → sequence_base-0.3.18}/sequence_base/schemas/BenchmarkSpec.json

@@ -277,7 +277,7 @@
       ],
       "title": "SeqFlags",
       "type": "integer",
-      "x-contract-version": "0.4.14",
+      "x-contract-version": "0.4.15",
       "x-flag-names": {
         "CHECK": 65536,
         "INFER": 16,
@@ -467,5 +467,5 @@
   ],
   "title": "BenchmarkSpec",
   "type": "object",
-  "x-contract-version": "0.4.14"
+  "x-contract-version": "0.4.15"
 }

{sequence_base-0.3.17 → sequence_base-0.3.18}/sequence_base/schemas/BenchmarkStatusResponse.json

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

{sequence_base-0.3.17 → sequence_base-0.3.18}/sequence_base/schemas/BootstrapResponse.json

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

{sequence_base-0.3.17 → sequence_base-0.3.18}/sequence_base/schemas/Camera.json

@@ -34,5 +34,5 @@
   ],
   "title": "Camera",
   "type": "object",
-  "x-contract-version": "0.4.14"
+  "x-contract-version": "0.4.15"
 }

{sequence_base-0.3.17 → sequence_base-0.3.18}/sequence_base/schemas/ClampInfo.json

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

{sequence_base-0.3.17 → sequence_base-0.3.18}/sequence_base/schemas/CodeBundle.json

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

sequence_base-0.3.18/sequence_base/schemas/Concurrency.json

@@ -0,0 +1,65 @@
+{
+  "additionalProperties": false,
+  "description": "How one worker serves robots, every field optional. `replicas_per_gpu` model copies share each card (each copy is\nits own process and serves one control loop); `gpus_per_replica` cards make one copy (None: every card of the\nworker). A worker's slots = cards // gpus_per_replica × replicas_per_gpu. `target_inputs` is how many robot sessions\na worker holds before another starts, `max_inputs` the most it takes while a new one boots — both default to the\nslots. {gs-plans/parallel/serving.md \"2. 一台 worker 里\" / \"3. 一台 worker 多张卡\"}",
+  "properties": {
+    "gpus_per_replica": {
+      "anyOf": [
+        {
+          "maximum": 256,
+          "minimum": 1,
+          "type": "integer"
+        },
+        {
+          "type": "null"
+        }
+      ],
+      "default": null,
+      "title": "Gpus Per Replica"
+    },
+    "max_inputs": {
+      "anyOf": [
+        {
+          "maximum": 1024,
+          "minimum": 1,
+          "type": "integer"
+        },
+        {
+          "type": "null"
+        }
+      ],
+      "default": null,
+      "title": "Max Inputs"
+    },
+    "replicas_per_gpu": {
+      "anyOf": [
+        {
+          "maximum": 64,
+          "minimum": 1,
+          "type": "integer"
+        },
+        {
+          "type": "null"
+        }
+      ],
+      "default": null,
+      "title": "Replicas Per Gpu"
+    },
+    "target_inputs": {
+      "anyOf": [
+        {
+          "maximum": 1024,
+          "minimum": 1,
+          "type": "integer"
+        },
+        {
+          "type": "null"
+        }
+      ],
+      "default": null,
+      "title": "Target Inputs"
+    }
+  },
+  "title": "Concurrency",
+  "type": "object",
+  "x-contract-version": "0.4.15"
+}

{sequence_base-0.3.17 → sequence_base-0.3.18}/sequence_base/schemas/Conditions.json

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

{sequence_base-0.3.17 → sequence_base-0.3.18}/sequence_base/schemas/ConnectRequest.json

@@ -25,5 +25,5 @@
   ],
   "title": "ConnectRequest",
   "type": "object",
-  "x-contract-version": "0.4.14"
+  "x-contract-version": "0.4.15"
 }

{sequence_base-0.3.17 → sequence_base-0.3.18}/sequence_base/schemas/ConnectResponse.json

@@ -307,5 +307,5 @@
   ],
   "title": "ConnectResponse",
   "type": "object",
-  "x-contract-version": "0.4.14"
+  "x-contract-version": "0.4.15"
 }

{sequence_base-0.3.17 → sequence_base-0.3.18}/sequence_base/schemas/DeploymentAccepted.json

@@ -18,5 +18,5 @@
   ],
   "title": "DeploymentAccepted",
   "type": "object",
-  "x-contract-version": "0.4.14"
+  "x-contract-version": "0.4.15"
 }

{sequence_base-0.3.17 → sequence_base-0.3.18}/sequence_base/schemas/DeploymentPolicy.json

@@ -387,5 +387,5 @@
   ],
   "title": "DeploymentPolicy",
   "type": "object",
-  "x-contract-version": "0.4.14"
+  "x-contract-version": "0.4.15"
 }