sequence-base 0.3.13__tar.gz → 0.3.14__tar.gz

{sequence_base-0.3.13 → sequence_base-0.3.14}/PKG-INFO

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

@@ -1,6 +1,6 @@
 [project]
 name = "sequence-base"
-version = "0.3.13"
+version = "0.3.14"
 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.13 → sequence_base-0.3.14}/sequence_base/__init__.py

@@ -48,8 +48,10 @@ from sequence_base.contract import (  # noqa: F401  (re-export surface)
     DeploymentRequest,
     DeploymentState,
     DeploymentStatusResponse,
+    ERRORS,
     ErrorBody,
     ErrorCode,
+    ErrorSpec,
     Estimate,
     EvalDryRunResponse,
     EvalReport,
@@ -87,6 +89,7 @@ from sequence_base.contract import (  # noqa: F401  (re-export surface)
     VolumeMount,
     VolumeRef,
     WarmingError,
+    code_for_status,
 )
 
 # the single schema-level version stamp (embedded in every exported JSON Schema)
@@ -137,7 +140,7 @@ __all__ = [
     # contract 7 — volumes (uploaded checkpoints and datasets)
     "VolumeFile", "VolumeUploadRequest", "UploadTarget", "VolumeUploadResponse", "VolumeInfo", "parse_vol",
     # error bodies + version
-    "ErrorCode", "ErrorBody", "WarmingError", "CONTRACT_VERSION",
+    "ErrorCode", "ErrorBody", "WarmingError", "ERRORS", "ErrorSpec", "code_for_status", "CONTRACT_VERSION",
     # obs
     "HEADER", "new_rid", "clean", "log", "Timer", "enabled",
     # errors (exception taxonomy)

{sequence_base-0.3.13 → sequence_base-0.3.14}/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.11"  # 0.4.10 -> 0.4.11: weights in named parts (weights_name, extra_weights)
+CONTRACT_VERSION = "0.4.12"  # 0.4.11 -> 0.4.12: one error definition — ErrorBody is every non-2xx body (detail, code, retryable, retry_after_s, request_id, hint, details), ErrorCode covers every case, ERRORS / ErrorCodes.json give each code its status, retryability, SDK class and CLI exit code
+# previous: 0.4.11  # 0.4.10 -> 0.4.11: weights in named parts (weights_name, extra_weights)
 # previous: 0.4.8  # 0.4.7 -> 0.4.8: ImageSpec.python, ImageStepRun.secrets, Resources.region, DeploymentRequest/BenchmarkRegisterRequest.image_context
 # previous: 0.4.7  # 0.4.6 -> 0.4.7: ActionContract.bounds / max_delta / on_violation (action limits)
 # previous: 0.4.6  # 0.4.5 -> 0.4.6: InferParam + DeploymentPolicy.params; EvalRequest.params / variants / record; BenchmarkRegisterRequest.gpu

{sequence_base-0.3.13 → sequence_base-0.3.14}/sequence_base/contract/__init__.py

@@ -102,7 +102,7 @@ from sequence_base.contract.volumes import (
 )
 
 # shared error bodies
-from sequence_base.contract.errors import ErrorBody, ErrorCode, WarmingError
+from sequence_base.contract.errors import ERRORS, ErrorBody, ErrorCode, ErrorSpec, WarmingError, code_for_status
 
 __all__ = [
     # contract 4
@@ -129,5 +129,5 @@ __all__ = [
     "MAX_FILES", "MAX_UPLOAD_BYTES", "VolumeFile", "VolumeUploadRequest", "UploadTarget", "VolumeUploadResponse",
     "VolumeInfo", "check_volume_name", "parse_vol",
     # errors
-    "ErrorCode", "ErrorBody", "WarmingError",
+    "ErrorCode", "ErrorBody", "WarmingError", "ERRORS", "ErrorSpec", "code_for_status",
 ]

sequence_base-0.3.14/sequence_base/contract/errors.py

@@ -0,0 +1,151 @@
+"""
+Shared error wire types: one definition for every non-2xx response the platform sends.
+
+Every error the gateway or a worker returns is an `ErrorBody`. `ERRORS` is the single table that
+gives each `ErrorCode` its HTTP status, whether a retry can help, the SDK exception it becomes and
+the `seq` CLI exit code. The gateway and the worker harness import it; the SDK, which cannot import
+this package on a robot, carries a generated copy that a test compares against `ErrorCodes.json`.
+That is what makes the same situation surface the same way at every entry point.
+{gs-plans/deploy-only/errors.md "同一种情况,不管从哪个入口碰到,结果都一样"}
+
+Distinct from `sequence_base.errors.transport`, which is the internal exception taxonomy the gateway
+and harness raise before a response is built.
+"""
+from __future__ import annotations
+
+from enum import Enum
+from typing import Any, NamedTuple
+
+from pydantic import BaseModel, ConfigDict, Field, model_validator
+from pydantic_core import PydanticUndefined
+
+
+class ErrorCode(str, Enum):
+    """What a caller switches on. The wording of `detail` may change; a code does not."""
+
+    INVALID_REQUEST = "invalid_request"
+    PAYLOAD_TOO_LARGE = "payload_too_large"
+    UNAUTHENTICATED = "unauthenticated"
+    FORBIDDEN = "forbidden"
+    INSUFFICIENT_CREDIT = "insufficient_credit"
+    BUDGET_EXHAUSTED = "budget_exhausted"
+    NOT_FOUND = "not_found"
+    CONFLICT = "conflict"
+    GONE = "gone"
+    BUSY = "busy"
+    WARMING = "warming"
+    UNAVAILABLE = "unavailable"
+    UPSTREAM_ERROR = "upstream_error"
+    TIMEOUT = "timeout"
+    POLICY_ERROR = "policy_error"
+    INTERNAL = "internal"
+    DEPENDENCY_MISSING = "dependency_missing"
+
+
+class ErrorSpec(NamedTuple):
+    status: int       # the HTTP status the code is sent with
+    retryable: bool   # whether the identical request can succeed later without the caller changing anything
+    sdk_class: str    # the sequence_ai exception it becomes
+    exit_code: int    # the `seq` CLI exit code
+
+
+# Grouped by what the caller does next, not by which module failed. Exit codes: 1 internal, 2 fix the
+# request, 3 credentials or permission, 4 missing or retired, 5 state conflict, 6 money, 7 retry later.
+ERRORS: dict[ErrorCode, ErrorSpec] = {
+    ErrorCode.INVALID_REQUEST: ErrorSpec(400, False, "InvalidRequest", 2),
+    ErrorCode.PAYLOAD_TOO_LARGE: ErrorSpec(413, False, "InvalidRequest", 2),
+    ErrorCode.UNAUTHENTICATED: ErrorSpec(401, False, "AuthError", 3),
+    ErrorCode.FORBIDDEN: ErrorSpec(403, False, "PermissionDenied", 3),
+    ErrorCode.INSUFFICIENT_CREDIT: ErrorSpec(402, False, "OutOfCredit", 6),
+    ErrorCode.BUDGET_EXHAUSTED: ErrorSpec(402, False, "OutOfCredit", 6),
+    ErrorCode.NOT_FOUND: ErrorSpec(404, False, "NotFound", 4),
+    ErrorCode.CONFLICT: ErrorSpec(409, False, "Conflict", 5),
+    ErrorCode.GONE: ErrorSpec(410, False, "Gone", 4),
+    ErrorCode.BUSY: ErrorSpec(429, True, "Unavailable", 7),
+    ErrorCode.WARMING: ErrorSpec(503, True, "Unavailable", 7),
+    ErrorCode.UNAVAILABLE: ErrorSpec(503, True, "Unavailable", 7),
+    ErrorCode.UPSTREAM_ERROR: ErrorSpec(502, True, "Unavailable", 7),
+    ErrorCode.TIMEOUT: ErrorSpec(504, True, "Unavailable", 7),
+    ErrorCode.POLICY_ERROR: ErrorSpec(500, False, "PolicyError", 1),
+    ErrorCode.INTERNAL: ErrorSpec(500, False, "InternalError", 1),
+    ErrorCode.DEPENDENCY_MISSING: ErrorSpec(424, False, "InternalError", 1),
+}
+
+# A response that carries no code (an older server, a proxy in between) is read by its status alone.
+_CODE_FOR_STATUS: dict[int, ErrorCode] = {
+    400: ErrorCode.INVALID_REQUEST, 401: ErrorCode.UNAUTHENTICATED, 402: ErrorCode.INSUFFICIENT_CREDIT,
+    403: ErrorCode.FORBIDDEN, 404: ErrorCode.NOT_FOUND, 405: ErrorCode.INVALID_REQUEST,
+    409: ErrorCode.CONFLICT, 410: ErrorCode.GONE, 413: ErrorCode.PAYLOAD_TOO_LARGE,
+    422: ErrorCode.INVALID_REQUEST, 424: ErrorCode.DEPENDENCY_MISSING, 429: ErrorCode.BUSY,
+    500: ErrorCode.INTERNAL, 502: ErrorCode.UPSTREAM_ERROR, 503: ErrorCode.UNAVAILABLE,
+    504: ErrorCode.TIMEOUT,
+}
+
+
+def code_for_status(status: int) -> ErrorCode:
+    """The code a bare status stands for: the table's own entry, else invalid_request for any other 4xx
+    and internal for any other 5xx."""
+    if status in _CODE_FOR_STATUS:
+        return _CODE_FOR_STATUS[status]
+    return ErrorCode.INVALID_REQUEST if 400 <= status < 500 else ErrorCode.INTERNAL
+
+
+class ErrorBody(BaseModel):
+    """The body of every non-2xx response. `detail` stays a plain sentence (the console already reads
+    that field); everything a program needs is in `code` and `details`."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    detail: str = Field(..., description="One sentence for a person. Its wording may change; switch on `code`.")
+    code: ErrorCode
+    retryable: bool = Field(..., description="Whether the identical request can succeed later. Always ERRORS[code].retryable")
+    retry_after_s: float | None = Field(default=None, description="Seconds to wait before retrying; sent with 429 and 503, mirrored in Retry-After")
+    request_id: str | None = Field(default=None, description="Quote it when reporting a problem")
+    hint: str | None = Field(default=None, description="The next step, e.g. a command to run")
+    details: dict[str, Any] = Field(default_factory=dict, description="Fields specific to the code: resource, name, reason, since, replacement, state, exception, ...")
+
+    @model_validator(mode="before")
+    @classmethod
+    def _retryable_from_table(cls, data: Any) -> Any:
+        # Filled from the table so no producer can contradict it; a body that states the opposite is refused.
+        # A subclass that fixes the code (WarmingError) is read through its default.
+        if not isinstance(data, dict):
+            return data
+        code = data.get("code")
+        if code is None:
+            default = cls.model_fields["code"].default
+            code = None if default is PydanticUndefined else default
+        if code is not None:
+            want = ERRORS[ErrorCode(code)].retryable
+            if data.get("retryable") is None:
+                data = {**data, "retryable": want}
+            elif data["retryable"] != want:
+                raise ValueError(f"retryable for {ErrorCode(code).value} is {want}")
+        return data
+
+    @property
+    def status(self) -> int:
+        return ERRORS[self.code].status
+
+
+class WarmingError(ErrorBody):
+    """503 while a worker loads: the one error whose remedy is purely to wait `retry_after_s`. A known
+    time-to-ready goes in `details["eta_s"]`."""
+
+    code: ErrorCode = ErrorCode.WARMING
+    retry_after_s: float
+
+
+def error_codes_json_schema(contract_version: str) -> dict:
+    """`ERRORS` as data, so a consumer that cannot import this package (the SDK on a robot) can check its
+    own copy against it: the code is a string enum, `x-errors` gives each code its status, retryability,
+    SDK class and CLI exit code."""
+    return {
+        "$schema": "https://json-schema.org/draft/2020-12/schema",
+        "title": "ErrorCode",
+        "description": "Every error code the platform sends, with what each one means for the caller.",
+        "type": "string",
+        "enum": [c.value for c in ErrorCode],
+        "x-errors": {c.value: spec._asdict() for c, spec in ERRORS.items()},
+        "x-contract-version": contract_version,
+    }

{sequence_base-0.3.13 → sequence_base-0.3.14}/sequence_base/schema_export.py

@@ -57,7 +57,7 @@ from sequence_base.contract.deployments import (
     Timeouts,
     VolumeAttach,
 )
-from sequence_base.contract.errors import ErrorBody, WarmingError
+from sequence_base.contract.errors import ErrorBody, WarmingError, error_codes_json_schema
 from sequence_base.contract.volumes import (
     UploadTarget,
     VolumeFile,
@@ -237,9 +237,10 @@ def build_schema(model: type[BaseModel]) -> dict:
 
 
 def all_schemas() -> dict[str, dict]:
-    """Every exported schema, by filename stem — pydantic models plus the SeqFlags IntFlag."""
+    """Every exported schema, by filename stem — pydantic models, the SeqFlags IntFlag and the error table."""
     out: dict[str, dict] = {name: build_schema(m) for name, m in WIRE_MODELS.items()}
     out["SeqFlags"] = seqflags_json_schema(CONTRACT_VERSION)
+    out["ErrorCodes"] = error_codes_json_schema(CONTRACT_VERSION)
     return out
 
 

{sequence_base-0.3.13 → sequence_base-0.3.14}/sequence_base/schemas/ActionChunk.json

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

{sequence_base-0.3.13 → sequence_base-0.3.14}/sequence_base/schemas/ActionContract.json

@@ -99,5 +99,5 @@
   ],
   "title": "ActionContract",
   "type": "object",
-  "x-contract-version": "0.4.11"
+  "x-contract-version": "0.4.12"
 }

{sequence_base-0.3.13 → sequence_base-0.3.14}/sequence_base/schemas/ActionStep.json

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

{sequence_base-0.3.13 → sequence_base-0.3.14}/sequence_base/schemas/AdapterTransform.json

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

{sequence_base-0.3.13 → sequence_base-0.3.14}/sequence_base/schemas/Autoscaler.json

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

{sequence_base-0.3.13 → sequence_base-0.3.14}/sequence_base/schemas/BenchmarkConditionSpec.json

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

{sequence_base-0.3.13 → sequence_base-0.3.14}/sequence_base/schemas/BenchmarkRegisterRequest.json

@@ -638,5 +638,5 @@
   ],
   "title": "BenchmarkRegisterRequest",
   "type": "object",
-  "x-contract-version": "0.4.11"
+  "x-contract-version": "0.4.12"
 }

{sequence_base-0.3.13 → sequence_base-0.3.14}/sequence_base/schemas/BenchmarkSpec.json

@@ -235,7 +235,7 @@
       ],
       "title": "SeqFlags",
       "type": "integer",
-      "x-contract-version": "0.4.11",
+      "x-contract-version": "0.4.12",
       "x-flag-names": {
         "CHECK": 65536,
         "INFER": 16,
@@ -425,5 +425,5 @@
   ],
   "title": "BenchmarkSpec",
   "type": "object",
-  "x-contract-version": "0.4.11"
+  "x-contract-version": "0.4.12"
 }

{sequence_base-0.3.13 → sequence_base-0.3.14}/sequence_base/schemas/BenchmarkStatusResponse.json

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

{sequence_base-0.3.13 → sequence_base-0.3.14}/sequence_base/schemas/BootstrapResponse.json

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

{sequence_base-0.3.13 → sequence_base-0.3.14}/sequence_base/schemas/Camera.json

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

{sequence_base-0.3.13 → sequence_base-0.3.14}/sequence_base/schemas/ClampInfo.json

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

{sequence_base-0.3.13 → sequence_base-0.3.14}/sequence_base/schemas/CodeBundle.json

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

{sequence_base-0.3.13 → sequence_base-0.3.14}/sequence_base/schemas/Concurrency.json

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

{sequence_base-0.3.13 → sequence_base-0.3.14}/sequence_base/schemas/Conditions.json

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

{sequence_base-0.3.13 → sequence_base-0.3.14}/sequence_base/schemas/ConnectRequest.json

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

{sequence_base-0.3.13 → sequence_base-0.3.14}/sequence_base/schemas/ConnectResponse.json

@@ -294,5 +294,5 @@
   ],
   "title": "ConnectResponse",
   "type": "object",
-  "x-contract-version": "0.4.11"
+  "x-contract-version": "0.4.12"
 }

{sequence_base-0.3.13 → sequence_base-0.3.14}/sequence_base/schemas/DeploymentAccepted.json

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

{sequence_base-0.3.13 → sequence_base-0.3.14}/sequence_base/schemas/DeploymentPolicy.json

@@ -366,5 +366,5 @@
   ],
   "title": "DeploymentPolicy",
   "type": "object",
-  "x-contract-version": "0.4.11"
+  "x-contract-version": "0.4.12"
 }

{sequence_base-0.3.13 → sequence_base-0.3.14}/sequence_base/schemas/DeploymentRequest.json

@@ -811,5 +811,5 @@
   ],
   "title": "DeploymentRequest",
   "type": "object",
-  "x-contract-version": "0.4.11"
+  "x-contract-version": "0.4.12"
 }

{sequence_base-0.3.13 → sequence_base-0.3.14}/sequence_base/schemas/DeploymentStatusResponse.json

@@ -41,5 +41,5 @@
   ],
   "title": "DeploymentStatusResponse",
   "type": "object",
-  "x-contract-version": "0.4.11"
+  "x-contract-version": "0.4.12"
 }

{sequence_base-0.3.13 → sequence_base-0.3.14}/sequence_base/schemas/Embodiment.json

@@ -212,5 +212,5 @@
   ],
   "title": "Embodiment",
   "type": "object",
-  "x-contract-version": "0.4.11"
+  "x-contract-version": "0.4.12"
 }

sequence_base-0.3.14/sequence_base/schemas/ErrorBody.json

@@ -0,0 +1,98 @@
+{
+  "$defs": {
+    "ErrorCode": {
+      "description": "What a caller switches on. The wording of `detail` may change; a code does not.",
+      "enum": [
+        "invalid_request",
+        "payload_too_large",
+        "unauthenticated",
+        "forbidden",
+        "insufficient_credit",
+        "budget_exhausted",
+        "not_found",
+        "conflict",
+        "gone",
+        "busy",
+        "warming",
+        "unavailable",
+        "upstream_error",
+        "timeout",
+        "policy_error",
+        "internal",
+        "dependency_missing"
+      ],
+      "title": "ErrorCode",
+      "type": "string"
+    }
+  },
+  "additionalProperties": false,
+  "description": "The body of every non-2xx response. `detail` stays a plain sentence (the console already reads\nthat field); everything a program needs is in `code` and `details`.",
+  "properties": {
+    "code": {
+      "$ref": "#/$defs/ErrorCode"
+    },
+    "detail": {
+      "description": "One sentence for a person. Its wording may change; switch on `code`.",
+      "title": "Detail",
+      "type": "string"
+    },
+    "details": {
+      "additionalProperties": true,
+      "description": "Fields specific to the code: resource, name, reason, since, replacement, state, exception, ...",
+      "title": "Details",
+      "type": "object"
+    },
+    "hint": {
+      "anyOf": [
+        {
+          "type": "string"
+        },
+        {
+          "type": "null"
+        }
+      ],
+      "default": null,
+      "description": "The next step, e.g. a command to run",
+      "title": "Hint"
+    },
+    "request_id": {
+      "anyOf": [
+        {
+          "type": "string"
+        },
+        {
+          "type": "null"
+        }
+      ],
+      "default": null,
+      "description": "Quote it when reporting a problem",
+      "title": "Request Id"
+    },
+    "retry_after_s": {
+      "anyOf": [
+        {
+          "type": "number"
+        },
+        {
+          "type": "null"
+        }
+      ],
+      "default": null,
+      "description": "Seconds to wait before retrying; sent with 429 and 503, mirrored in Retry-After",
+      "title": "Retry After S"
+    },
+    "retryable": {
+      "description": "Whether the identical request can succeed later. Always ERRORS[code].retryable",
+      "title": "Retryable",
+      "type": "boolean"
+    }
+  },
+  "required": [
+    "detail",
+    "code",
+    "retryable"
+  ],
+  "title": "ErrorBody",
+  "type": "object",
+  "x-contract-version": "0.4.12"
+}