sequence-base 0.3.22__tar.gz → 0.3.24__tar.gz

{sequence_base-0.3.22 → sequence_base-0.3.24}/PKG-INFO

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

@@ -1,6 +1,6 @@
 [project]
 name = "sequence-base"
-version = "0.3.22"
+version = "0.3.24"
 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.22 → sequence_base-0.3.24}/sequence_base/constants/version.py

@@ -4,7 +4,9 @@
 # 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.19"  # 0.4.18 -> 0.4.19: RenderSpec.flip — how the platform turns a recorded camera's frames before encoding ("vertical" / "horizontal" / "both"; None, left off the wire, as drawn), declared once by the benchmark's author (seq.Record(flip=...)); gs-plans benchmarks
+CONTRACT_VERSION = "0.4.21"  # 0.4.20 -> 0.4.21: InferParam.min / max / choices — the values an inference parameter allows (seq.Range / seq.OneOf), refused before inference outside them; None, left off the wire, as before (gs-plans deploy-serving/35)
+# previous: 0.4.20  # 0.4.19 -> 0.4.20: BenchmarkRegisterRequest.params — the parameters a benchmark's @seq.setup declares (InferParam: type and default), which an eval may set; EvalReport.arm_params — per arm each parameter's value and source, and the steps that asked the policy of all it took (gs-plans eval-adapters/36)
+# previous: 0.4.19  # 0.4.18 -> 0.4.19: RenderSpec.flip — how the platform turns a recorded camera's frames before encoding ("vertical" / "horizontal" / "both"; None, left off the wire, as drawn), declared once by the benchmark's author (seq.Record(flip=...)); gs-plans benchmarks
 # previous: 0.4.18  # 0.4.17 -> 0.4.18: DeploymentPolicy.models — the platform models a policy calls while it runs (catalogue ids), which the act key driving it may call on /v1/chat and /v1/decide (gs-plans models-api/11)
 # previous: 0.4.17  # 0.4.16 -> 0.4.17: weights optional — PolicySpec.weights, DeploymentRequest.weights and BootstrapResponse.weights_uri may be None, for a policy without a checkpoint (nothing copied or mounted; gs-plans storage T13)
 # previous: 0.4.16  # 0.4.15 -> 0.4.16: batched benchmarks — SeqFlags.OBSERVE / STEP, BenchmarkSpec / BenchmarkRegisterRequest.envs and .batched; per-arm eval reports — EvalReport.arms / paired / timing / stop_reason, EvalStatus.CANCELED, Estimate.breakdown / default_timing, EvalResponse.arms, EvalDryRunResponse.layout / notes

{sequence_base-0.3.22 → sequence_base-0.3.24}/sequence_base/contract/benchmarks.py

@@ -17,7 +17,7 @@ from typing import Literal
 from pydantic import BaseModel, ConfigDict, Field, model_validator
 
 from sequence_base.contract.accounts import SecretRef
-from sequence_base.contract.deployments import CodeBundle, DeploymentState
+from sequence_base.contract.deployments import CodeBundle, DeploymentState, InferParam
 from sequence_base.contract.flags import BENCHMARK_BATCHED, BENCHMARK_BINDABLE, SeqFlags
 from sequence_base.contract.policy import ActionContract, ImageSpec, VolumeRef
 
@@ -185,11 +185,22 @@ class BenchmarkRegisterRequest(BaseModel):
     gpu: str | None = Field(default=None, max_length=32)
     # How many environments one instance runs at once when an eval does not say; None takes 1.
     envs: int | None = Field(default=None, ge=1, le=65536)
+    # The parameters its @seq.setup declares — `def setup(self, envs, *, noise_std: float = 0.02)` — each with its type
+    # and default, which an eval may set (--param benchmark.noise_std=0); None: it declares none, or an SDK from before
+    # them. {gs-plans/eval-adapters/36}
+    params: dict[str, InferParam] | None = Field(default=None, max_length=32)
     # Whether the benchmark is batched (binds OBSERVE and STEP and steps many environments in one call).
     batched: bool = False
     # The Dockerfile's build context, as for a deployment.
     image_context: CodeBundle | None = None
 
+    @model_validator(mode="after")
+    def _param_names(self) -> "BenchmarkRegisterRequest":
+        for name in self.params or {}:
+            if not name.isidentifier() or name.startswith("_"):
+                raise ValueError(f"setup parameter {name!r} is not a public Python identifier")
+        return self
+
 
 class BenchmarkStatusResponse(BaseModel):
     """GET /v1/benchmarks/{name} — the build state of a registered benchmark (same lifecycle as a deployment:

{sequence_base-0.3.22 → sequence_base-0.3.24}/sequence_base/contract/deployments.py

@@ -116,12 +116,52 @@ class VolumeAttach(BaseModel):
 class InferParam(BaseModel):
     """One inference parameter the policy's `@seq.infer` declares — `def infer(self, obs, *, num_steps: int = 10)`
     — with its type and default. An /act or an eval may set it; the worker passes only declared names, cast to
-    this type, and refuses any other. {gs-plans/customization/policy.md "四、推理行为"}"""
+    this type, and refuses any other. {gs-plans/customization/policy.md "四、推理行为"}
+
+    `min` / `max` (a number's bounds, inclusive) and `choices` (the values it may take) — declared as
+    `Annotated[int, seq.Range(1, 10)]` / `seq.OneOf(...)` — refuse any other value before inference, saying which are
+    allowed; None (left off the wire) holds it to its type alone. {gs-plans/deploy-serving/35 "允许声明范围或可选值"}"""
 
     model_config = ConfigDict(extra="forbid")
 
     type: Literal["int", "float", "bool", "str"]
     default: int | float | bool | str | None = None
+    min: int | float | None = None
+    max: int | float | None = None
+    choices: list[int | float | bool | str] | None = Field(default=None, min_length=1, max_length=64)
+
+    @model_validator(mode="after")
+    def _bounds_fit(self) -> "InferParam":
+        numeric = self.type in ("int", "float")
+        if (self.min is not None or self.max is not None) and not numeric:
+            raise ValueError(f"min / max bound a number; a {self.type} parameter takes choices instead")
+        if self.min is not None and self.max is not None and self.min > self.max:
+            raise ValueError(f"min {self.min} is above max {self.max}")
+        if self.default is not None and not allowed(self, self.default):
+            raise ValueError(f"the default {self.default!r} is outside what the parameter allows ({describe(self)})")
+        return self
+
+
+def allowed(param: "InferParam", value) -> bool:
+    """Whether a value (already cast to the parameter's type) is one the parameter allows."""
+    if param.choices is not None and value not in param.choices:
+        return False
+    if param.min is not None and value < param.min:
+        return False
+    return not (param.max is not None and value > param.max)
+
+
+def describe(param: "InferParam") -> str:
+    """What a parameter allows, in words: "one of 5, 10", "from 1 to 10", "at least 1", "at most 10"."""
+    if param.choices is not None:
+        return "one of " + ", ".join(repr(c) for c in param.choices)
+    if param.min is not None and param.max is not None:
+        return f"from {param.min} to {param.max}"
+    if param.min is not None:
+        return f"at least {param.min}"
+    if param.max is not None:
+        return f"at most {param.max}"
+    return f"any {param.type}"
 
 
 class DeploymentPolicy(BaseModel):

{sequence_base-0.3.22 → sequence_base-0.3.24}/sequence_base/contract/eval.py

@@ -71,7 +71,9 @@ class EvalRequest(BaseModel):
     max_usd: float | None = Field(default=None, gt=0)
     # Run again only the episodes of that earlier eval that errored; the report covers both runs.
     rerun_of: str | None = None
-    # Inference parameters the model's @seq.infer declares, set for every /act of this eval.
+    # Parameters set for every arm of this eval: by `side.name` — the policy's @seq.infer, the adapter's __init__, the
+    # benchmark's @seq.setup, or the eval loop's own (`eval.steps_per_query`) — or by the bare name when only one side
+    # declares it. `sweep` names them the same way. {gs-plans/eval-adapters/36}
     params: dict[str, int | float | bool | str] | None = Field(default=None, max_length=32)
     # Only the conditions whose variant takes one of these values on each named axis.
     variants: dict[str, list[str]] | None = Field(default=None, max_length=32)
@@ -261,6 +263,8 @@ class ArmReport(BaseModel):
 
     arm: int
     model: str
+    # What this arm's eval set (the eval's params and this arm's sweep values): a policy's inference parameter by its
+    # name, any other side's as side.name (`eval.steps_per_query`). Every value it ran with is in EvalReport.arm_params.
     params: dict[str, int | float | bool | str] = Field(default_factory=dict)
     metrics: dict[str, MetricAgg] = Field(default_factory=dict)
     # Each metric's 95% confidence interval as [low, high].
@@ -271,6 +275,33 @@ class ArmReport(BaseModel):
     budget_stopped: bool = False
 
 
+class ParamUsed(BaseModel):
+    """One parameter's value in an arm, and who gave it: the eval (`cli`), the default its declaring side wrote
+    (`policy` / `adapter` / `benchmark`), or the platform's own (`platform`). {gs-plans/eval-adapters/36}"""
+
+    model_config = ConfigDict(extra="forbid")
+
+    value: int | float | bool | str | None = None
+    source: Literal["cli", "policy", "adapter", "benchmark", "platform"]
+
+
+class ArmParams(BaseModel):
+    """An arm's parameters, side by side: every one the policy's @seq.infer, the adapter's __init__, the benchmark's
+    @seq.setup and the eval loop declare, with the value the arm ran with and where it came from; and how many of its
+    steps asked the policy (their observation read, so rendered, once each) of all the steps it took — what
+    `eval.steps_per_query` saves. {gs-plans/eval-adapters/36}"""
+
+    model_config = ConfigDict(extra="forbid")
+
+    arm: int
+    policy: dict[str, ParamUsed] = Field(default_factory=dict)
+    adapter: dict[str, ParamUsed] = Field(default_factory=dict)
+    benchmark: dict[str, ParamUsed] = Field(default_factory=dict)
+    eval: dict[str, ParamUsed] = Field(default_factory=dict)
+    queries: int | None = None
+    steps: int | None = None
+
+
 class PairedDiff(BaseModel):
     """`compare`: one metric's difference between two arms over the seeds both ran (b - a), with its interval."""
 
@@ -323,6 +354,9 @@ class EvalReport(BaseModel):
     paired: list[PairedDiff] | None = None
     timing: EvalTiming | None = None
     stop_reason: str | None = None
+    # Per arm, every parameter's value and where it came from (gs-plans eval-adapters/36). Here and not in ArmReport:
+    # an SDK from before it drops a report key its contract does not define, but would refuse one inside an arm.
+    arm_params: list[ArmParams] | None = None
 
 
 class AdapterKind(str, Enum):

{sequence_base-0.3.22 → sequence_base-0.3.24}/sequence_base/schemas/ActRequest.json

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

{sequence_base-0.3.22 → sequence_base-0.3.24}/sequence_base/schemas/ActResponse.json

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

{sequence_base-0.3.22 → sequence_base-0.3.24}/sequence_base/schemas/ActionChunk.json

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

{sequence_base-0.3.22 → sequence_base-0.3.24}/sequence_base/schemas/ActionContract.json

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

{sequence_base-0.3.22 → sequence_base-0.3.24}/sequence_base/schemas/ActionStep.json

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

{sequence_base-0.3.22 → sequence_base-0.3.24}/sequence_base/schemas/AdapterTransform.json

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

{sequence_base-0.3.22 → sequence_base-0.3.24}/sequence_base/schemas/AddLocal.json

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

{sequence_base-0.3.22 → sequence_base-0.3.24}/sequence_base/schemas/Autoscaler.json

@@ -69,5 +69,5 @@
   },
   "title": "Autoscaler",
   "type": "object",
-  "x-contract-version": "0.4.19"
+  "x-contract-version": "0.4.21"
 }

{sequence_base-0.3.22 → sequence_base-0.3.24}/sequence_base/schemas/BenchmarkConditionSpec.json

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

{sequence_base-0.3.22 → sequence_base-0.3.24}/sequence_base/schemas/BenchmarkRegisterRequest.json

@@ -415,6 +415,108 @@
       "title": "ImageStepUvPip",
       "type": "object"
     },
+    "InferParam": {
+      "additionalProperties": false,
+      "description": "One inference parameter the policy's `@seq.infer` declares — `def infer(self, obs, *, num_steps: int = 10)`\n— with its type and default. An /act or an eval may set it; the worker passes only declared names, cast to\nthis type, and refuses any other. {gs-plans/customization/policy.md \"四、推理行为\"}\n\n`min` / `max` (a number's bounds, inclusive) and `choices` (the values it may take) — declared as\n`Annotated[int, seq.Range(1, 10)]` / `seq.OneOf(...)` — refuse any other value before inference, saying which are\nallowed; None (left off the wire) holds it to its type alone. {gs-plans/deploy-serving/35 \"允许声明范围或可选值\"}",
+      "properties": {
+        "choices": {
+          "anyOf": [
+            {
+              "items": {
+                "anyOf": [
+                  {
+                    "type": "integer"
+                  },
+                  {
+                    "type": "number"
+                  },
+                  {
+                    "type": "boolean"
+                  },
+                  {
+                    "type": "string"
+                  }
+                ]
+              },
+              "maxItems": 64,
+              "minItems": 1,
+              "type": "array"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "default": null,
+          "title": "Choices"
+        },
+        "default": {
+          "anyOf": [
+            {
+              "type": "integer"
+            },
+            {
+              "type": "number"
+            },
+            {
+              "type": "boolean"
+            },
+            {
+              "type": "string"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "default": null,
+          "title": "Default"
+        },
+        "max": {
+          "anyOf": [
+            {
+              "type": "integer"
+            },
+            {
+              "type": "number"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "default": null,
+          "title": "Max"
+        },
+        "min": {
+          "anyOf": [
+            {
+              "type": "integer"
+            },
+            {
+              "type": "number"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "default": null,
+          "title": "Min"
+        },
+        "type": {
+          "enum": [
+            "int",
+            "float",
+            "bool",
+            "str"
+          ],
+          "title": "Type",
+          "type": "string"
+        }
+      },
+      "required": [
+        "type"
+      ],
+      "title": "InferParam",
+      "type": "object"
+    },
     "RenderSpec": {
       "additionalProperties": false,
       "description": "a.k.a. `seq.Record` — declares the mp4 the platform records (money-shot is a platform tool, not user\nglue). `camera` picks which camera stream to pull frames from; `fps` is the output frame rate. Used two\nways: as `BenchmarkSpec.render` (record the whole eval) and as `Step.record` (a per-frame hint).",
@@ -665,6 +767,22 @@
       "title": "Name",
       "type": "string"
     },
+    "params": {
+      "anyOf": [
+        {
+          "additionalProperties": {
+            "$ref": "#/$defs/InferParam"
+          },
+          "maxProperties": 32,
+          "type": "object"
+        },
+        {
+          "type": "null"
+        }
+      ],
+      "default": null,
+      "title": "Params"
+    },
     "render": {
       "anyOf": [
         {
@@ -718,5 +836,5 @@
   ],
   "title": "BenchmarkRegisterRequest",
   "type": "object",
-  "x-contract-version": "0.4.19"
+  "x-contract-version": "0.4.21"
 }

{sequence_base-0.3.22 → sequence_base-0.3.24}/sequence_base/schemas/BenchmarkSpec.json

@@ -297,7 +297,7 @@
       ],
       "title": "SeqFlags",
       "type": "integer",
-      "x-contract-version": "0.4.19",
+      "x-contract-version": "0.4.21",
       "x-flag-names": {
         "CHECK": 65536,
         "INFER": 16,
@@ -505,5 +505,5 @@
   ],
   "title": "BenchmarkSpec",
   "type": "object",
-  "x-contract-version": "0.4.19"
+  "x-contract-version": "0.4.21"
 }

{sequence_base-0.3.22 → sequence_base-0.3.24}/sequence_base/schemas/BenchmarkStatusResponse.json

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

{sequence_base-0.3.22 → sequence_base-0.3.24}/sequence_base/schemas/BootstrapResponse.json

@@ -79,5 +79,5 @@
   ],
   "title": "BootstrapResponse",
   "type": "object",
-  "x-contract-version": "0.4.19"
+  "x-contract-version": "0.4.21"
 }

{sequence_base-0.3.22 → sequence_base-0.3.24}/sequence_base/schemas/Camera.json

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

{sequence_base-0.3.22 → sequence_base-0.3.24}/sequence_base/schemas/ClampInfo.json

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

{sequence_base-0.3.22 → sequence_base-0.3.24}/sequence_base/schemas/CodeBundle.json

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

{sequence_base-0.3.22 → sequence_base-0.3.24}/sequence_base/schemas/Concurrency.json

@@ -61,5 +61,5 @@
   },
   "title": "Concurrency",
   "type": "object",
-  "x-contract-version": "0.4.19"
+  "x-contract-version": "0.4.21"
 }

{sequence_base-0.3.22 → sequence_base-0.3.24}/sequence_base/schemas/Conditions.json

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

{sequence_base-0.3.22 → sequence_base-0.3.24}/sequence_base/schemas/ConnectRequest.json

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

{sequence_base-0.3.22 → sequence_base-0.3.24}/sequence_base/schemas/ConnectResponse.json

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

{sequence_base-0.3.22 → sequence_base-0.3.24}/sequence_base/schemas/DeploymentAccepted.json

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

{sequence_base-0.3.22 → sequence_base-0.3.24}/sequence_base/schemas/DeploymentPolicy.json

@@ -170,8 +170,38 @@
     },
     "InferParam": {
       "additionalProperties": false,
-      "description": "One inference parameter the policy's `@seq.infer` declares — `def infer(self, obs, *, num_steps: int = 10)`\n— with its type and default. An /act or an eval may set it; the worker passes only declared names, cast to\nthis type, and refuses any other. {gs-plans/customization/policy.md \"四、推理行为\"}",
+      "description": "One inference parameter the policy's `@seq.infer` declares — `def infer(self, obs, *, num_steps: int = 10)`\n— with its type and default. An /act or an eval may set it; the worker passes only declared names, cast to\nthis type, and refuses any other. {gs-plans/customization/policy.md \"四、推理行为\"}\n\n`min` / `max` (a number's bounds, inclusive) and `choices` (the values it may take) — declared as\n`Annotated[int, seq.Range(1, 10)]` / `seq.OneOf(...)` — refuse any other value before inference, saying which are\nallowed; None (left off the wire) holds it to its type alone. {gs-plans/deploy-serving/35 \"允许声明范围或可选值\"}",
       "properties": {
+        "choices": {
+          "anyOf": [
+            {
+              "items": {
+                "anyOf": [
+                  {
+                    "type": "integer"
+                  },
+                  {
+                    "type": "number"
+                  },
+                  {
+                    "type": "boolean"
+                  },
+                  {
+                    "type": "string"
+                  }
+                ]
+              },
+              "maxItems": 64,
+              "minItems": 1,
+              "type": "array"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "default": null,
+          "title": "Choices"
+        },
         "default": {
           "anyOf": [
             {
@@ -193,6 +223,36 @@
           "default": null,
           "title": "Default"
         },
+        "max": {
+          "anyOf": [
+            {
+              "type": "integer"
+            },
+            {
+              "type": "number"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "default": null,
+          "title": "Max"
+        },
+        "min": {
+          "anyOf": [
+            {
+              "type": "integer"
+            },
+            {
+              "type": "number"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "default": null,
+          "title": "Min"
+        },
         "type": {
           "enum": [
             "int",
@@ -403,5 +463,5 @@
   ],
   "title": "DeploymentPolicy",
   "type": "object",
-  "x-contract-version": "0.4.19"
+  "x-contract-version": "0.4.21"
 }