mainsequence 8.1.20.dev14__py3-none-any.whl → 8.1.20.dev16__py3-none-any.whl

mainsequence/client/agent_runtime_models.py

@@ -6,7 +6,6 @@ import json
 import pathlib
 import time
 import uuid
-from enum import Enum
 from typing import Any, ClassVar, Literal
 
 import requests
@@ -31,6 +30,7 @@ from .observability import (
     PublicLogLevel,
 )
 from .utils import make_request, serialize_to_json
+from .value_sets import OpenStrEnum, OpenValueSet
 
 DEFAULT_AGENT_SESSION_LONG_REQUEST_TIMEOUT = (5.0, 900.0)
 DEFAULT_AGENT_RUNTIME_ACCESS_CACHE_TTL_SECONDS = 60.0
@@ -50,7 +50,7 @@ MIN_RUNTIME_INTERACTION_RETRY_SECONDS = 0.5
 MAX_RUNTIME_INTERACTION_RETRY_SECONDS = 30.0
 
 
-class AgentSessionStatus(str, Enum):
+class AgentSessionStatus(OpenStrEnum):
     PENDING = "pending"
     RUNNING = "running"
     COMPLETED = "completed"
@@ -58,7 +58,7 @@ class AgentSessionStatus(str, Enum):
     CANCELED = "canceled"
 
 
-class A2AResponseKind(str, Enum):
+class A2AResponseKind(OpenStrEnum):
     MESSAGE = "message"
     TASK = "task"
 
@@ -121,12 +121,12 @@ class A2AMessageSendResult(BasePydanticModel):
         return A2AResponseKind.TASK if self.task is not None else A2AResponseKind.MESSAGE
 
 
-class AgentHarnessKind(str, Enum):
+class AgentHarnessKind(OpenStrEnum):
     PI = "pi"
     TAU = "tau"
 
 
-class AgentHarnessProtocol(str, Enum):
+class AgentHarnessProtocol(OpenStrEnum):
     PI_CHECKPOINT_V1 = "pi-checkpoint-v1"
     TAU_SESSION_V1 = "tau-session-v1"
 
@@ -136,13 +136,15 @@ class AgentRuntimeUpdateRemediation(BasePydanticModel):
 
 
 class AgentRuntimeUpdate(BasePydanticModel):
-    state: Literal[
-        "current",
-        "update_required",
-        "updating",
-        "update_failed",
-        "not_deployed",
-        "unknown",
+    state: OpenValueSet[
+        Literal[
+            "current",
+            "update_required",
+            "updating",
+            "update_failed",
+            "not_deployed",
+            "unknown",
+        ]
     ]
     needs_redeploy: bool | None
     remediation: AgentRuntimeUpdateRemediation | None
@@ -279,7 +281,7 @@ class AgentRuntimeInteractionNotice(BasePydanticModel):
 class AgentRuntimeInteractionAction(BasePydanticModel):
     model_config = ConfigDict(extra="allow")
 
-    type: Literal["update_agent_runtime", "retry_runtime_wake"]
+    type: OpenValueSet[Literal["update_agent_runtime", "retry_runtime_wake"]]
     label: str
     confirmation_message: str
     interaction_revision: str
@@ -299,16 +301,18 @@ class AgentRuntimeInteractionOperation(BasePydanticModel):
 class AgentRuntimeInteraction(BasePydanticModel):
     model_config = ConfigDict(extra="allow")
 
-    state: Literal[
-        "ready",
-        "warning",
-        "checking",
-        "starting",
-        "waking",
-        "update_required",
-        "updating",
-        "update_failed",
-        "unavailable",
+    state: OpenValueSet[
+        Literal[
+            "ready",
+            "warning",
+            "checking",
+            "starting",
+            "waking",
+            "update_required",
+            "updating",
+            "update_failed",
+            "unavailable",
+        ]
     ]
     can_submit: bool
     notice: AgentRuntimeInteractionNotice | None
@@ -324,29 +328,33 @@ class AgentRuntimePresenceReplicas(BasePydanticModel):
 
 class AgentRuntimePresenceWake(BasePydanticModel):
     operation_uid: str
-    state: Literal[
-        "requested",
-        "in_progress",
-        "serving",
-        "failed",
-        "expired",
-        "superseded",
+    state: OpenValueSet[
+        Literal[
+            "requested",
+            "in_progress",
+            "serving",
+            "failed",
+            "expired",
+            "superseded",
+        ]
     ]
     requested_at: str
     deadline_at: str
 
 
 class AgentRuntimePresence(BasePydanticModel):
-    phase: Literal[
-        "not_deployed",
-        "observing",
-        "idle",
-        "provisioning",
-        "pulling_image",
-        "starting",
-        "serving",
-        "redeploying",
-        "failed",
+    phase: OpenValueSet[
+        Literal[
+            "not_deployed",
+            "observing",
+            "idle",
+            "provisioning",
+            "pulling_image",
+            "starting",
+            "serving",
+            "redeploying",
+            "failed",
+        ]
     ]
     replicas: AgentRuntimePresenceReplicas
     detail: str
@@ -361,7 +369,7 @@ class AgentSessionRuntimeAccess(BasePydanticModel):
         None,
         description="Canonical public UID of the coding-agent service that owns the runtime.",
     )
-    mode: Literal["token", "unavailable"] = Field(
+    mode: OpenValueSet[Literal["token", "unavailable"]] = Field(
         "token",
         description="Runtime access mode returned by the backend.",
     )
@@ -862,7 +870,7 @@ class TauAgentSessionInsightsSession(BasePydanticModel):
     agent_session_id: str = Field(..., alias="agentSessionId")
     session_id: str | None = Field(None, alias="sessionId")
     thread_id: str | None = Field(None, alias="threadId")
-    status: Literal["running", "completed", "error"]
+    status: OpenValueSet[Literal["running", "completed", "error"]]
     started_at: datetime.datetime | None = Field(None, alias="startedAt")
     updated_at: datetime.datetime | None = Field(None, alias="updatedAt")
     last_error: str | None = Field(None, alias="lastError")

mainsequence/client/github_issues.py

@@ -11,11 +11,16 @@ from . import utils as client_utils
 from .base import BasePydanticModel
 from .exceptions import raise_for_response
 from .utils import make_request
+from .value_sets import OpenValueSet
 
 GitHubIssueState = Literal["open", "closed"]
 GitHubIssueStateReason = Literal["completed", "not_planned", "reopened"]
-GitHubIssueOperationType = Literal["create_issue", "update_issue", "create_comment"]
-GitHubIssueOperationStatus = Literal["pending", "succeeded", "failed", "unknown"]
+GitHubIssueOperationType = OpenValueSet[
+    Literal["create_issue", "update_issue", "create_comment"]
+]
+GitHubIssueOperationStatus = OpenValueSet[
+    Literal["pending", "succeeded", "failed", "unknown"]
+]
 
 _IDEMPOTENCY_KEY_PATTERN = re.compile(r"^[A-Za-z0-9._:-]+$")
 
@@ -115,7 +120,7 @@ class _GitHubIssueProjection(BasePydanticModel):
     issue_number: int
     html_url: str
     title: str
-    state: GitHubIssueState
+    state: OpenValueSet[GitHubIssueState]
     state_reason: str | None
     created_at: datetime.datetime
     updated_at: datetime.datetime

mainsequence/client/metatables/core.py

@@ -61,6 +61,7 @@ from ..utils import (
     make_request,
     serialize_to_json,
 )
+from ..value_sets import OpenValueSet
 
 DUCK_DB = "duck_db"
 SQLITE = "sqlite"
@@ -1059,7 +1060,7 @@ class MetaTableCascadeDeletedMetaTable(BasePydanticModel):
     meta_table_uid: str
     physical_schema: str | None = None
     physical_table_name: str | None = None
-    management_mode: MetaTableManagementMode
+    management_mode: OpenValueSet[MetaTableManagementMode]
     physical_table_drop_scheduled: bool
     physical_table_drop_cascade: bool
     schema_management_protection_overridden: bool
@@ -1109,7 +1110,7 @@ class DataSource(BasePydanticModel, BaseObjectOrm):
     )
     class_type: str | None = None
     status: str | None = None
-    storage_access_mode: StorageAccessMode | None = Field(
+    storage_access_mode: OpenValueSet[StorageAccessMode] | None = Field(
         default="read_write",
         description="Runtime storage access gate: read_write, read_only, or disabled.",
     )
@@ -1369,9 +1370,9 @@ class MetaTable(
     namespace: str | None = None
     description: str | None = None
     labels: list[str] = Field(default_factory=list)
-    management_mode: MetaTableManagementMode
-    provisioning_status: Literal["reserved", "active"] = "active"
-    schema_management_mode: MetaTableSchemaManagementMode = "backend_managed"
+    management_mode: OpenValueSet[MetaTableManagementMode]
+    provisioning_status: OpenValueSet[Literal["reserved", "active"]] = "active"
+    schema_management_mode: OpenValueSet[MetaTableSchemaManagementMode] = "backend_managed"
     schema_management: dict[str, Any] = Field(default_factory=dict)
     migration_package: str | None = None
     migration_namespace: str | None = None
@@ -2544,7 +2545,7 @@ class TimeIndexTableUpdate(TableUpdateNode, BaseObjectOrm):
                 index_min=index_min,
                 multi_index_column_stats=result.get("multi_index_column_stats"),
             ),
-            direct_dependency_uids=result.get("direct_dependency_uids"),
+            upstream_update_uids=result.get("upstream_update_uids"),
         )
         return table_update_run
 
@@ -4576,7 +4577,16 @@ class _TableUpdateRunFields:
     )
     # extra fields for local control
     update_statistics: BaseUpdateStatistics | None = None
-    direct_dependency_uids: list[str] | None = None
+    upstream_update_uids: list[str] | None = Field(
+        None,
+        description=(
+            "Uids of the update's direct upstream dependencies, as set-start-of-execution "
+            "reports them. The backend reads them off the update node's "
+            "`upstream_update_dependencies` edges, which the time-index table updater hard "
+            "cut renamed from `downstream_direct_dependencies`; this field carries that "
+            "canonical name rather than the pre-cut one."
+        ),
+    )
 
 
 class TableUpdateRun(_TableUpdateRunFields, BasePydanticModel, BaseObjectOrm):

mainsequence/client/models_foundry.py

@@ -30,6 +30,7 @@ from .metatables import DataSource as _DataSource
 from .utils import (
     make_request,
 )
+from .value_sets import OpenValueSet
 
 if TYPE_CHECKING:
     from .github_issues import GitHubIssueMutationResult, GitHubIssuePage, GitHubIssueState
@@ -508,7 +509,7 @@ class CodeRepositoryBranch(BasePydanticModel, BaseObjectOrm):
     github_repository_binding_uid: str | None = None
     latest_git_version: str = ""
     is_initialized: bool
-    provisioning_status: Literal["CREATING", "READY", "FAILED"]
+    provisioning_status: OpenValueSet[Literal["CREATING", "READY", "FAILED"]]
     provisioning_job_run_uid: str | None
     provisioning_error_code: str
     provisioning_error_detail: str
@@ -726,7 +727,7 @@ class GitHubRepositoryBinding(BasePydanticModel, BaseObjectOrm):
 
 
 class CodeRepositoryImageSourceProvenance(BasePydanticModel):
-    verification_state: Literal["verified", "unverified", "building", "failed"]
+    verification_state: OpenValueSet[Literal["verified", "unverified", "building", "failed"]]
     code_repository_uid: str | None = None
     code_repository_branch_uid: str | None = None
     github_repository_binding_uid: str | None = None

mainsequence/client/models_helpers.py

@@ -5,7 +5,6 @@ import json
 import time
 from collections.abc import Collection
 from decimal import Decimal
-from enum import Enum
 from pathlib import PurePosixPath
 from typing import Any, ClassVar, Literal
 from uuid import UUID
@@ -41,6 +40,7 @@ from .observability import (
     PublicLogLevel,
 )
 from .utils import make_request
+from .value_sets import OpenStrEnum, OpenValueSet
 
 
 def get_model_class(model_class: str):
@@ -1156,27 +1156,34 @@ class CodeRepositoryResource(CurrentCodeRepositoryBranchCollectionMixin, BaseObj
         )
 
 
-class ResourceReleaseKind(str, Enum):
+class ResourceReleaseKind(OpenStrEnum):
+    """The backend's canonical release-kind vocabulary.
+
+    Open (ADR 0033): a kind a later backend adds is read as sent, rather than
+    failing the release that carries it and the listing that release is in.
+    """
+
     AGENT = "agent"
     FAST_API = "fastapi"
+    HARNESS_AGENT = "harness_agent"
     STATIC_SITE = "static_site"
 
 
 class ResourceReleaseRuntimeRouting(BasePydanticModel):
-    state: Literal["routable", "unavailable"]
+    state: OpenValueSet[Literal["routable", "unavailable"]]
     active_revision_uid: str | None = None
 
 
 class ResourceReleaseRuntimeNotice(BasePydanticModel):
     code: str
-    severity: Literal["info", "warning", "error"]
+    severity: OpenValueSet[Literal["info", "warning", "error"]]
     title: str
     message: str
 
 
 class ResourceReleaseRuntimeOperation(BasePydanticModel):
     uid: str
-    status: Literal["queued", "running", "succeeded", "failed", "superseded"]
+    status: OpenValueSet[Literal["queued", "running", "succeeded", "failed", "superseded"]]
     created_at: datetime.datetime
     started_at: datetime.datetime | None = None
     finished_at: datetime.datetime | None = None
@@ -1184,7 +1191,7 @@ class ResourceReleaseRuntimeOperation(BasePydanticModel):
 
 
 class ResourceReleaseRuntimeAdmission(BasePydanticModel):
-    state: Literal["ready", "waking", "unavailable"]
+    state: OpenValueSet[Literal["ready", "waking", "unavailable"]]
     can_request: bool
     notice: ResourceReleaseRuntimeNotice | None = None
     operation: ResourceReleaseRuntimeOperation | None = None
@@ -1198,24 +1205,28 @@ class ResourceReleaseRuntimeReplicas(BasePydanticModel):
 
 class ResourceReleaseRuntimeWake(BasePydanticModel):
     operation_uid: str
-    state: Literal[
-        "requested", "in_progress", "serving", "failed", "expired", "superseded"
+    state: OpenValueSet[
+        Literal[
+            "requested", "in_progress", "serving", "failed", "expired", "superseded"
+        ]
     ]
     requested_at: datetime.datetime
     deadline_at: datetime.datetime
 
 
 class ResourceReleaseRuntimePresence(BasePydanticModel):
-    phase: Literal[
-        "not_deployed",
-        "idle",
-        "observing",
-        "provisioning",
-        "pulling_image",
-        "starting",
-        "serving",
-        "redeploying",
-        "failed",
+    phase: OpenValueSet[
+        Literal[
+            "not_deployed",
+            "idle",
+            "observing",
+            "provisioning",
+            "pulling_image",
+            "starting",
+            "serving",
+            "redeploying",
+            "failed",
+        ]
     ]
     replicas: ResourceReleaseRuntimeReplicas
     detail: str
@@ -1225,7 +1236,9 @@ class ResourceReleaseRuntimePresence(BasePydanticModel):
 
 class ResourceReleaseRuntimeAccess(BasePydanticModel):
     resource_release_uid: str
-    release_kind: Literal["fastapi", "harness_agent"]
+    # The canonical vocabulary ResourceRelease.release_kind reads (#119): this
+    # payload names a release kind, so it names it the same way.
+    release_kind: ResourceReleaseKind
     routing: ResourceReleaseRuntimeRouting
     runtime_access: ResourceReleaseRuntimeAdmission
     runtime_presence: ResourceReleaseRuntimePresence
@@ -1512,11 +1525,14 @@ class ResourceRelease(
             normalized_release_kind = release_kind.value
         else:
             normalized_release_kind = Job._normalize_str(release_kind)
-            allowed_release_kinds = {kind.value for kind in ResourceReleaseKind}
-            if normalized_release_kind not in allowed_release_kinds:
-                raise ValueError(
-                    "release_kind must be one of: " + ", ".join(sorted(allowed_release_kinds)) + "."
-                )
+        # What the SDK sends stays closed (ADR 0033). ResourceReleaseKind reads an
+        # undeclared kind out of a response, but iterating it yields only the kinds
+        # this release declares, so a kind built here is still checked against them.
+        allowed_release_kinds = {kind.value for kind in ResourceReleaseKind}
+        if normalized_release_kind not in allowed_release_kinds:
+            raise ValueError(
+                "release_kind must be one of: " + ", ".join(sorted(allowed_release_kinds)) + "."
+            )
 
         normalized_compute = Job._validate_and_normalize_compute_fields(
             cpu_request=cpu_request,
@@ -1617,26 +1633,30 @@ class DeploymentRunStep(BaseModel):
     sequence: PositiveInt
     key: str
     name: str = ""
-    kind: Literal[
-        "source",
-        "image_build",
-        "validation",
-        "runtime_deploy",
-        "runtime_readiness",
-        "publish",
-        "cleanup",
-        "orchestration",
+    kind: OpenValueSet[
+        Literal[
+            "source",
+            "image_build",
+            "validation",
+            "runtime_deploy",
+            "runtime_readiness",
+            "publish",
+            "cleanup",
+            "orchestration",
+        ]
     ]
     required: bool = True
-    state: Literal[
-        "pending",
-        "running",
-        "succeeded",
-        "failed",
-        "cancelled",
-        "skipped",
-        "blocked",
-        "superseded",
+    state: OpenValueSet[
+        Literal[
+            "pending",
+            "running",
+            "succeeded",
+            "failed",
+            "cancelled",
+            "skipped",
+            "blocked",
+            "superseded",
+        ]
     ]
     outcome: str = ""
     artifact_context: dict[str, Any] = Field(default_factory=dict)
@@ -1658,12 +1678,14 @@ class DeploymentRunBillingComponents(BasePydanticModel):
     image_registry_service: Decimal | None = Field(max_digits=18, decimal_places=6)
 
 
-DeploymentRunPricingState = Literal[
-    "priced",
-    "partial",
-    "pending",
-    "unavailable",
-    "failed",
+DeploymentRunPricingState = OpenValueSet[
+    Literal[
+        "priced",
+        "partial",
+        "pending",
+        "unavailable",
+        "failed",
+    ]
 ]
 
 
@@ -1700,14 +1722,14 @@ class DeploymentRunLogEntry(BaseModel):
     timestamp: datetime.datetime | None = None
     step_uid: str | None = None
     source: str
-    stream: Literal["stdout", "stderr"]
-    level: Literal["debug", "info", "warning", "error"]
+    stream: OpenValueSet[Literal["stdout", "stderr"]]
+    level: OpenValueSet[Literal["debug", "info", "warning", "error"]]
     text: str = ""
 
 
 class DeploymentRunLogSource(BaseModel):
     source: str
-    state: Literal["pending", "available", "partial", "expired", "unavailable"]
+    state: OpenValueSet[Literal["pending", "available", "partial", "expired", "unavailable"]]
 
 
 class DeploymentRunLogPage(BaseModel):

mainsequence/client/models_user.py

@@ -22,6 +22,7 @@ from .utils import (
     DEFAULT_TIMEOUT,
     make_request,
 )
+from .value_sets import OpenValueSet
 
 _CURRENT_AUTH_HEADERS: ContextVar[Mapping[str, Any] | None] = ContextVar(
     "_CURRENT_AUTH_HEADERS",
@@ -528,7 +529,7 @@ class Notification(DetailActionObjectMixin, BasePydanticModel, UserApiBaseObject
         title="Notification UID",
         description="Stable public unique identifier of the notification.",
     )
-    source: Literal["system", "organization"] | None = Field(
+    source: OpenValueSet[Literal["system", "organization"]] | None = Field(
         None,
         title="Notification Source",
         description="Source scope of the notification.",
@@ -544,7 +545,7 @@ class Notification(DetailActionObjectMixin, BasePydanticModel, UserApiBaseObject
         title="Source Organization UID",
         description="Public UID of the organization that owns the notification.",
     )
-    type: Literal["UR", "IM", "IN"] = Field(
+    type: OpenValueSet[Literal["UR", "IM", "IN"]] = Field(
         "IN",
         title="Notification Type",
         description="Stored notification priority code.",
@@ -914,7 +915,7 @@ class ShareableAccessState(BasePydanticModel):
         description="Backend object type identifier for the shareable object.",
         examples=["tdag.constant"],
     )
-    access_level: Literal["view", "edit"] = Field(
+    access_level: OpenValueSet[Literal["view", "edit"]] = Field(
         ...,
         title="Access Level",
         description="Permission level represented by this access-state payload.",

mainsequence/client/observability.py

@@ -10,6 +10,7 @@ from pydantic import ConfigDict, Field
 from .base import BasePydanticModel
 from .exceptions import ApiError, raise_for_response
 from .utils import make_request
+from .value_sets import OpenValueSet
 
 PublicLogLevel = Literal[
     "debug",
@@ -55,7 +56,7 @@ class OwnerLogRow(BasePydanticModel):
     time: int | float | None = None
     timestamp: str | None = None
     severity: str | None = None
-    level: PublicLogLevel | None = None
+    level: OpenValueSet[PublicLogLevel] | None = None
     source: str | None = None
     event: str | None = None
     event_id: str | None = None
@@ -110,16 +111,18 @@ class OwnerLogPage(BasePydanticModel):
 class EnvironmentLogSearchRow(OwnerLogRow):
     """One sanitized row returned by an Environment-scoped collection search."""
 
-    owner_type: Literal[
-        "deployment_run",
-        "job_run",
-        "resource_release",
-        "agent",
-        "agent_session",
+    owner_type: OpenValueSet[
+        Literal[
+            "deployment_run",
+            "job_run",
+            "resource_release",
+            "agent",
+            "agent_session",
+        ]
     ]
     owner_uid: str
     occurred_at: datetime.datetime
-    level: PublicLogLevel
+    level: OpenValueSet[PublicLogLevel]
 
 
 class EnvironmentLogSearchPage(BasePydanticModel):
@@ -134,7 +137,9 @@ class EnvironmentLogSearchPage(BasePydanticModel):
     result_limit: int = Field(ge=0)
     next_cursor: str | None = None
     truncated: bool
-    truncation_reason: Literal["page_limit", "result_limit", "candidate_limit"] | None = None
+    truncation_reason: (
+        OpenValueSet[Literal["page_limit", "result_limit", "candidate_limit"]] | None
+    ) = None
     rows: list[EnvironmentLogSearchRow] = Field(default_factory=list)
 
 

mainsequence/client/value_sets.py

@@ -0,0 +1,164 @@
+"""Open value sets: read a closed vocabulary without failing on an undeclared value.
+
+ADR 0033. A response field whose vocabulary the backend is allowed to extend — a
+state, a phase, a kind — is declared with the types here instead of a bare `Enum`
+or `Literal`. A value this SDK release does not declare is kept as the backend
+wrote it and reported once, so one new backend state does not fail the row that
+carries it, nor the listing that row is in.
+
+Values the SDK *sends* stay closed. A request parameter typed `Literal[...]` still
+rejects a value the backend does not accept, because there the mistake is the
+caller's and raising is what catches it.
+"""
+
+from __future__ import annotations
+
+from enum import Enum
+from typing import Annotated, Any, Literal, get_args, get_origin
+
+from pydantic import AfterValidator
+
+from mainsequence.logconf import logger
+
+# An unknown value is reported once per process, not once per row: a listing of
+# 500 rows carrying the same new state is one backend change, so it is one line.
+# The set is capped so a response cannot grow it without bound.
+_MAX_REPORTED_UNKNOWN_VALUES = 512
+_reported_unknown_values: set[tuple[str, str, str]] = set()
+
+
+def _report_unknown_value(
+    owner: str,
+    field_name: str | None,
+    value: str,
+    known: tuple[str, ...],
+) -> None:
+    """Log an undeclared value once, naming the model, the field and the value."""
+    key = (owner, field_name or "", value)
+    if key in _reported_unknown_values:
+        return
+    if len(_reported_unknown_values) >= _MAX_REPORTED_UNKNOWN_VALUES:
+        return
+    _reported_unknown_values.add(key)
+    where = f"{owner}.{field_name}" if field_name else owner
+    logger.warning(
+        f"{where} received {value!r}, which this mainsequence release does not declare. "
+        f"The value is kept as sent. Declared values: {', '.join(known)}. "
+        f"Upgrade the SDK to read it as a declared member."
+    )
+
+
+def _reset_reported_unknown_values() -> None:
+    """Forget what has been reported. For tests that assert on the log line."""
+    _reported_unknown_values.clear()
+
+
+class OpenStrEnum(str, Enum):
+    """A string enum that keeps a value it does not declare instead of raising.
+
+    A known value validates to the declared member, so `kind is Kind.AGENT` and
+    `kind == "agent"` both keep working. An undeclared value becomes a member-like
+    object carrying that exact string: it compares equal to the string, serializes
+    as the string, and is not equal to any declared member. It is deliberately not
+    registered on the class, so iterating the enum still lists only what this
+    release declares.
+    """
+
+    @classmethod
+    def _missing_(cls, value: object) -> OpenStrEnum | None:
+        if not isinstance(value, str):
+            # Not a string: let Enum raise its own error, as before.
+            return None
+        undeclared = str.__new__(cls, value)
+        undeclared._name_ = value
+        undeclared._value_ = value
+        _report_unknown_value(
+            cls.__name__,
+            None,
+            value,
+            tuple(member.value for member in cls),
+        )
+        return undeclared
+
+
+class _KeepUndeclaredValue:
+    """Validator behind `OpenValueSet`: keep any string, report the undeclared ones."""
+
+    __slots__ = ("known",)
+
+    def __init__(self, known: tuple[str, ...]) -> None:
+        self.known = known
+
+    def __call__(self, value: str, info: Any) -> str:
+        if value in self.known:
+            return value
+        owner = (info.config or {}).get("title") or "response"
+        _report_unknown_value(owner, info.field_name or "value", value, self.known)
+        return value
+
+    def __eq__(self, other: object) -> bool:
+        return isinstance(other, _KeepUndeclaredValue) and other.known == self.known
+
+    def __hash__(self) -> int:
+        return hash((type(self).__name__, self.known))
+
+
+def _declared_values(item: object) -> tuple[str, ...]:
+    """The values the wrapped `Literal[...]` declares."""
+    candidates = item if isinstance(item, tuple) else (item,)
+    values: list[str] = []
+    for candidate in candidates:
+        if get_origin(candidate) is not Literal:
+            raise TypeError(
+                "OpenValueSet wraps a Literal, e.g. OpenValueSet[Literal['a', 'b']] "
+                f"or OpenValueSet[PublicLogLevel]; got {candidate!r}"
+            )
+        values.extend(get_args(candidate))
+    if not values:
+        raise TypeError("OpenValueSet requires at least one declared value")
+    for value in values:
+        if not isinstance(value, str):
+            raise TypeError(f"OpenValueSet takes string values; got {value!r}")
+    return tuple(dict.fromkeys(values))
+
+
+class OpenValueSet:
+    """Wraps a `Literal[...]` for a response field whose vocabulary may grow.
+
+    Reads as a `str` that keeps an undeclared value instead of raising:
+
+        state: OpenValueSet[Literal["routable", "unavailable"]]
+        level: OpenValueSet[PublicLogLevel]
+
+    The values stay inside a real `Literal`, so they keep one spelling for readers,
+    for `Literal` aliases reused between a request parameter and a response field,
+    and for tools that rewrite annotations. `declared_values()` reads them back.
+    """
+
+    def __class_getitem__(cls, item: object) -> Any:
+        known = _declared_values(item)
+        return Annotated[str, AfterValidator(_KeepUndeclaredValue(known))]
+
+
+def declared_values(annotation: Any) -> tuple[str, ...]:
+    """The values an `OpenValueSet` declares, in declaration order.
+
+    Takes the annotation itself, or the `FieldInfo` pydantic built from it —
+    `Model.model_fields["state"]` — because pydantic moves the metadata there.
+    """
+    candidates = (
+        *getattr(annotation, "__metadata__", ()),
+        *getattr(annotation, "metadata", ()),
+    )
+    for meta in candidates:
+        func = getattr(meta, "func", None)
+        if isinstance(func, _KeepUndeclaredValue):
+            return func.known
+    raise TypeError(f"{annotation!r} does not declare an OpenValueSet")
+
+
+__all__ = [
+    "OpenStrEnum",
+    "OpenValueSet",
+    "declared_values",
+]

{mainsequence-8.1.20.dev14.dist-info → mainsequence-8.1.20.dev16.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mainsequence
-Version: 8.1.20.dev14
+Version: 8.1.20.dev16
 Summary: Main Sequence SDK 
 Author-email: Main Sequence GmbH <dev@main-sequence.io>
 License-Expression: LicenseRef-MainSequence-Proprietary

{mainsequence-8.1.20.dev14.dist-info → mainsequence-8.1.20.dev16.dist-info}/RECORD

@@ -36,24 +36,25 @@ mainsequence/cli/sdk_utils.py,sha256=AuhnDkQ8QsBGSW7l7yqmQvaDAzfC-0iEVvFNkm3sJ48
 mainsequence/cli/ssh_utils.py,sha256=cucQFeQoctMPhoghCyrrb04WR6DhRBQXAOSZ3jFQwow,13552
 mainsequence/cli/ui.py,sha256=ATgpcIhzZ1CXGwPcvEWOrJ3OEWUIAHK-mRTuKJ0uzzc,3454
 mainsequence/client/__init__.py,sha256=Xl2ie3HEO00V1C2xurxbhlWp_nXyV4SZMkeJXh-zZ1Q,548
-mainsequence/client/agent_runtime_models.py,sha256=ZFWuZaR1Q1_25M-lamIKQtLJI3uikQsp3g3O9lxOORk,66622
+mainsequence/client/agent_runtime_models.py,sha256=B3QFA-dE7X-98bFY_HeVxVBpnI583q121n3EhZUcC7g,66948
 mainsequence/client/base.py,sha256=Xg9TXBx7IXglSWX-aRYtOMbftkXioBOZxFNwcHF5TF8,42730
 mainsequence/client/client.py,sha256=sUsJhjwKq4oZsEX2Ozm-7owcyQq0kgFNKUrtEYwf8cU,3907
 mainsequence/client/compute_validation.py,sha256=ByeX0CkIE7qq06ggZFfN92U3Qp2e9cvo2RTIGWa5_Vw,6662
 mainsequence/client/dtype_codec.py,sha256=0ydXPw0dWTVtUzmXoT6ilr2TM_vNC3WTiy3I8QI1ni8,16522
 mainsequence/client/exceptions.py,sha256=xx2L4l3OMNsTybbYkiTKK398ahnutEascM0It35tGr0,3815
-mainsequence/client/github_issues.py,sha256=1jNUJD_NZx25K0naUC23CUx6_Nm8kpriXc0DFjjqGKE,14477
-mainsequence/client/models_foundry.py,sha256=ODPdpFQ334hmD2wd_V0KoU9og6yk01nfHIJ24oWySfU,44872
-mainsequence/client/models_helpers.py,sha256=a2sQER4o75zmU4JxxuX-rBypr5M0-wECbX7gXsp00SQ,65343
-mainsequence/client/models_user.py,sha256=MYVQgpNFuodrNfDuNgO23Q6JZCpsiNykiBAwo3jGPUE,41238
-mainsequence/client/observability.py,sha256=onRFc5G3Y6omlkj86hTsPLV2q2NBd5uqtyu4YuH_GtY,15695
+mainsequence/client/github_issues.py,sha256=pSTUw3UPrmE6wqnpoJctartTaNSq6iu6PQRrd8hip6I,14568
+mainsequence/client/models_foundry.py,sha256=jrEXZrx3WweleogeDwjSjQOjQN5p3j-Ox9YDXa2iW5g,44937
+mainsequence/client/models_helpers.py,sha256=5-0ypOf_Dkp4rVmRR8S2TQ8_wb0ABjoc7oY-b6oatD4,66363
+mainsequence/client/models_user.py,sha256=l7t7q1nSa2kbLZ7dHbAjSpuRY8e9kWEjC8u3MK4Qfzw,41317
+mainsequence/client/observability.py,sha256=tDoy2NDcDrjeXFAHuxaylaMy2-NOuoN_arFdIOMppro,15842
 mainsequence/client/utils.py,sha256=vaku-aeUpnn220nzEVcSQWdiykSeW3sUzgDtYter5tk,28784
+mainsequence/client/value_sets.py,sha256=BYTvMyWGqDJu5wlIADsLoGymFoYBeQmXcW_dDRFnF6U,6114
 mainsequence/client/data_sources_interfaces/__init__.py,sha256=oUnKUx0D4nbNXYgVMgvac6MfgVNKuzGZL045p4VKqUg,668
 mainsequence/client/data_sources_interfaces/duckdb.py,sha256=JZHsN3fB2UQYpNQJnp2pAqG_9Q6FX8DIM_c8A6GbPSc,63383
 mainsequence/client/data_sources_interfaces/local_paths.py,sha256=aO7-pTGBWItcpY1MxoYYP0mbEgB3dDWqDOwniezNw5c,323
 mainsequence/client/data_sources_interfaces/sqlite.py,sha256=gWpuG9FbPWF69urRqU_K5yWX7vkHGPeOCYaJwVu8nG0,16392
 mainsequence/client/metatables/__init__.py,sha256=dLxgfvV8t5kb59SxBowXxLJJQAc1BPgNzVUl_7U6SeA,580
-mainsequence/client/metatables/core.py,sha256=FdYKoAU6AjIS3lFAOXT6GOJTgJvD01HFea9yb6-H1DM,185916
+mainsequence/client/metatables/core.py,sha256=QxtY8-pu_smlTjQGV00b-PzFz1leRLIoblnbRDDjECQ,186480
 mainsequence/instrumentation/__init__.py,sha256=K1W1vx2wu1QldzUD6tI4C8op9mFcVpS7D-Ina1O9TFc,152
 mainsequence/instrumentation/utils.py,sha256=b-ihjSioAepeLfMpudM2SqCtvnxMqIXileHx3klBCQU,3377
 mainsequence/meta_tables/__init__.py,sha256=aHwu6kRSunS3-ZiVnSS-8rBH09ZnWUu82hgrmnpeEf4,5267
@@ -83,9 +84,9 @@ mainsequence/meta_tables/time_index_table_updates/namespacing.py,sha256=obJfMnjL
 mainsequence/meta_tables/time_index_table_updates/runner.py,sha256=853p_iXJ835pI8pX3519HSdTw93Bqqd3JxHOfm3S6yg,34412
 mainsequence/meta_tables/time_index_table_updates/updaters.py,sha256=-6zJgi1sDRCyIyVxLwTfb2RLLZS4LC0syNJHnJRAtgU,31404
 mainsequence/meta_tables/time_index_table_updates/utils.py,sha256=O1iKp2tzCkqxyCblI6MKxez6XV180w87VszxDO9OfAE,621
-mainsequence-8.1.20.dev14.dist-info/licenses/LICENSE,sha256=fXoCKgEuZXmP84_QDXpvO18QHze_6AAhd-zvZBUjJxQ,4524
-mainsequence-8.1.20.dev14.dist-info/METADATA,sha256=Fu0seRII3KQmUv5_7T7kUqqxdygkAARPlhdsXLPNNV0,7384
-mainsequence-8.1.20.dev14.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
-mainsequence-8.1.20.dev14.dist-info/entry_points.txt,sha256=XGAOq3-mF2lWWpeRJvoaWyMarRcK167mH1g124aGdUs,88
-mainsequence-8.1.20.dev14.dist-info/top_level.txt,sha256=BFeblM_Q9q0cUWBvTxnfWcWQEHtf5XZi9nOS-Gdfwus,28
-mainsequence-8.1.20.dev14.dist-info/RECORD,,
+mainsequence-8.1.20.dev16.dist-info/licenses/LICENSE,sha256=fXoCKgEuZXmP84_QDXpvO18QHze_6AAhd-zvZBUjJxQ,4524
+mainsequence-8.1.20.dev16.dist-info/METADATA,sha256=DoNMwGRr6-fOmywBWA-MhO7Zc7IsndZsVV0r1Ak91sk,7384
+mainsequence-8.1.20.dev16.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+mainsequence-8.1.20.dev16.dist-info/entry_points.txt,sha256=XGAOq3-mF2lWWpeRJvoaWyMarRcK167mH1g124aGdUs,88
+mainsequence-8.1.20.dev16.dist-info/top_level.txt,sha256=BFeblM_Q9q0cUWBvTxnfWcWQEHtf5XZi9nOS-Gdfwus,28
+mainsequence-8.1.20.dev16.dist-info/RECORD,,