sequence-base 0.3.0__py3-none-any.whl

sequence_base/contract/eval.py

@@ -0,0 +1,201 @@
+"""
+契约 5 (run half) — `POST /v1/eval`, its response, and the `GET /v1/eval/{id}` report, plus the adapter
+lossless/lossy classification wire types.
+
+Two response shapes, deliberately distinguishable (goal 12): a real run returns eval_id / gpus_granted /
+estimate; `dry_run=true` returns ONLY an estimate — no id to GET, no built-machine artifacts. The report
+status is a restricted enum, matching the deployment-status discipline; every detail row is structured,
+not a bare dict or free text.
+"""
+from __future__ import annotations
+
+from enum import Enum
+
+from pydantic import BaseModel, ConfigDict, Field, model_validator
+
+__all__ = [
+    "EvalRequest",
+    "ClampInfo",
+    "Estimate",
+    "EvalResponse",
+    "EvalDryRunResponse",
+    "RolloutResult",
+    "EvalStatus",
+    "SuiteAgg",
+    "TaskAgg",
+    "MetricAgg",
+    "LossyTransform",
+    "EvalReport",
+    "AdapterKind",
+    "AdapterTransform",
+]
+
+
+class EvalRequest(BaseModel):
+    """`model` and `benchmark` required; the rest are optional knobs. `dry_run` selects the estimate-only
+    response shape below."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    model: str
+    benchmark: str
+    suite: str | None = None
+    trials: int | None = None
+    gpus: int | None = None
+    envs_per_gpu: int | None = None
+    vlm_max_concurrency: int | None = None
+    adapter: str | None = None
+    compare: str | None = Field(default=None, description="Another model id to compare against")
+    dry_run: bool = False
+
+
+class ClampInfo(BaseModel):
+    """Why the granted GPU count was clamped below the request — structured, not a bare value."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    limit: str = Field(..., description="Which limit bound it, e.g. 'account_quota'")
+    requested: int
+    granted: int
+
+
+class Estimate(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    wall_clock_s: float
+    cost_usd: float
+    vlm_calls: int
+
+
+class EvalResponse(BaseModel):
+    """A real run — carries the built-machine artifacts (eval_id to GET, gpus_granted actually reserved)."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    eval_id: str
+    gpus_granted: int
+    estimate: Estimate
+    clamped_by: ClampInfo | None = None
+
+
+class EvalDryRunResponse(BaseModel):
+    """`dry_run=true` — estimate only. No eval_id, no gpus_granted: nothing was built, nothing to GET."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    estimate: Estimate
+
+
+class RolloutResult(BaseModel):
+    """One episode's result, ASSEMBLED BY THE PLATFORM from the per-step `@seq.check` returns — the user
+    never returns a success flag. `metrics` is the episode's closed-out user metrics (passthrough; the
+    platform does not know the field names). `video_uri` points at the mp4 the platform tool produced.
+
+    Scope: W0.1 delivers this wire shape only; the runtime that settles per-step `check.done` per-env and
+    assembles it lives in the container / gateway, not in this pure-types unit."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    metrics: dict[str, float] = Field(
+        ..., description="Episode's user-named metrics (passthrough; platform does not name them)"
+    )
+    steps: int
+    terminated: bool
+    truncated: bool
+    trajectory_uri: str | None = None
+    video_uri: str | None = None
+
+
+class EvalStatus(str, Enum):
+    """Restricted enum — same discipline as DeploymentState (not a free string)."""
+
+    PENDING = "pending"
+    RUNNING = "running"
+    COMPLETED = "completed"
+    FAILED = "failed"
+
+
+class SuiteAgg(BaseModel):
+    """Per-suite aggregate of ONE user-named metric — structured detail, not a bare dict. `value` is the
+    metric aggregated over that suite; the platform does not name or interpret the metric."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    suite: str
+    value: float
+    n: int
+
+
+class TaskAgg(BaseModel):
+    """Per-task aggregate of ONE user-named metric — structured detail, not a bare dict."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    task: str
+    value: float
+    n: int
+
+
+class MetricAgg(BaseModel):
+    """The aggregate of one user-named metric key across the eval — overall plus per-suite / per-task
+    breakdowns and the sample count. The platform aggregates whatever the user returned in `Step.metrics`;
+    it neither defines nor injects `success_rate` (success is just one key the user may or may not name)."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    overall: float
+    per_suite: list[SuiteAgg] = Field(default_factory=list)
+    per_task: list[TaskAgg] = Field(default_factory=list)
+    n: int
+
+
+class LossyTransform(BaseModel):
+    """A lossy adapter transform recorded in the report. Shape aligns with the lossy element of
+    AdapterTransform (both {transform, reason})."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    transform: str
+    reason: str
+
+
+class EvalReport(BaseModel):
+    """GET /v1/eval/{id} (eval-raw revision). NO hard-coded `overall_sr` / `success_rate` top-level field —
+    `metrics` is a passthrough dict keyed by the user's metric names (from `@seq.check`'s `Step.metrics`),
+    each value a `MetricAgg`. The platform aggregates per key and invents nothing. `videos` carries the mp4
+    pointers the platform tool produced; `incomplete` flags that some condition did not finish (never pass a
+    subset off as the whole)."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    status: EvalStatus
+    metrics: dict[str, MetricAgg] = Field(
+        ..., description="User-named metric key → its aggregate; platform does not name the keys"
+    )
+    cost_usd: float
+    dashboard_url: str
+    adapter_lossy: list[LossyTransform]
+    videos: list[str] = Field(default_factory=list, description="mp4 pointers from the platform tool")
+    incomplete: bool | None = None
+
+
+class AdapterKind(str, Enum):
+    LOSSLESS = "lossless"
+    LOSSY = "lossy"
+
+
+class AdapterTransform(BaseModel):
+    """One adapter transform, classified. A lossy transform must carry a non-empty reason; a lossless one
+    needs none. The lossy element's shape ({transform, reason}) aligns with EvalReport.adapter_lossy."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    kind: AdapterKind
+    transform: str
+    reason: str | None = None
+
+    @model_validator(mode="after")
+    def _lossy_needs_reason(self) -> "AdapterTransform":
+        if self.kind is AdapterKind.LOSSY and not (self.reason and self.reason.strip()):
+            raise ValueError("a lossy transform must carry a non-empty reason")
+        return self

sequence_base/contract/flags.py

@@ -0,0 +1,92 @@
+"""
+契约 1 — `SeqFlags`: the lifecycle bitmask the SDK's `@seq.*` decorators write and the harness loader
+reads back. One IntFlag, so a registration can carry several lifecycle entrypoints in one integer and
+the harness recovers each by testing a bit.
+
+Modeled on Modal's `_PartialFunctionFlags` (one IntFlag, one bit per lifecycle hook)
+{modal _partial_function.py:29}. Four members map bit-for-bit onto Modal's flags so the harness can be
+a thin adaptation of Modal's loader; the rest are platform-only lifecycle hooks Modal has no analogue
+for (a warm-up hook, a plan step, and the benchmark SETUP / RESET / CHECK / SCORE quartet).
+
+eval-raw revision: the platform provides the reset→step→check loop as a tool; the user defines the goal
+through four hooks — SETUP (load sim + assets), RESET (build one episode's env), CHECK (per-step: read raw
+env state → done + user-named metrics), SCORE (cross-episode aggregate). RESET=32768 and CHECK=65536 are
+the new hook bits. The old single-hook `ROLLOUT` is DEPRECATED: bit 8192 stays reserved (never reused for
+another member) but appears in NO bindings — the setup/reset/check/score model replaces it.
+
+The exact bit values are the contract — see `MODAL_MAPPING` / `PLATFORM_ONLY` for the authoritative
+"member → bit value → Modal counterpart" list. A member taking the wrong value, WARMUP collapsing back
+into LOAD, RESET/CHECK overlapping an existing bit, or ROLLOUT being re-bound is caught bit-by-bit (see
+tests), not waved away with "an IntFlag is naturally bit-composable".
+"""
+from __future__ import annotations
+
+from enum import IntFlag
+
+
+class SeqFlags(IntFlag):
+    # ── mapped bit-for-bit onto Modal `_PartialFunctionFlags` ────────────────────────────────────
+    LOAD = 2            # Modal ENTER — load weights into VRAM (one-shot; no snapshot bisection)
+    SHUTDOWN = 8        # Modal EXIT — teardown / release the container
+    INFER = 16          # Modal CALLABLE_INTERFACE — the obs→ActionChunk call
+    ON_EPISODE = 1024   # Modal ~SESSIONED — sticky / session boundary for stateful policies
+
+    # ── platform-only: no Modal counterpart; each an independent, disjoint bit ────────────────────
+    # WARMUP is its OWN bit, NOT an alias of LOAD (S1.yaml goal 5 — "WARMUP=1(独立 bit,明确不并入
+    # LOAD)"). A policy may bind @seq.load and @seq.warmup to two different methods → two independent
+    # bindings, so the bit must be distinct from LOAD. Value 1 is bit 0, unused by any mapped flag.
+    WARMUP = 1          # JIT warm-up hook (ours; Modal folded warm-up into ENTER, we keep it separate)
+    PLAN = 4            # a policy planning step (ours; Modal has none) — bit 2, unused by Modal
+    # benchmark lifecycle (eval-raw: platform provides the loop tool, user hooks the goal in) — each an
+    # independent, disjoint bit, disjoint too from every mapped bit:
+    SETUP = 4096        # load sim + assets, once (≈ @seq.load)
+    SCORE = 16384       # cross-episode aggregate (optional; default = mean of each numeric metric)
+    RESET = 32768       # build one episode's env (gym-style handle) — eval-raw new hook, bit 15
+    CHECK = 65536       # per step: read raw env state → done + user-named metrics — eval-raw new hook, bit 16
+    # DEPRECATED — the old single-hook benchmark model. Bit 8192 stays reserved (never reused for another
+    # member) but is NOT bound in any registration; setup/reset/check/score replaces it. Kept only so the
+    # value cannot be recycled and an old serialized 8192 still decodes to a known name.
+    ROLLOUT = 8192
+
+
+# Authoritative "member → Modal counterpart" list. Anything here must equal the bit above; anything in
+# PLATFORM_ONLY must be disjoint from every mapped bit and from each other.
+MODAL_MAPPING: dict[str, str] = {
+    "LOAD": "ENTER",
+    "SHUTDOWN": "EXIT",
+    "INFER": "CALLABLE_INTERFACE",
+    "ON_EPISODE": "~SESSIONED",
+}
+
+# Platform-only members Modal has no flag for. ROLLOUT is included: it is still a real (if deprecated)
+# member and its bit must stay disjoint from every other, so the disjointness check must cover it.
+PLATFORM_ONLY: frozenset[str] = frozenset(
+    {"WARMUP", "PLAN", "SETUP", "SCORE", "RESET", "CHECK", "ROLLOUT"}
+)
+
+# The benchmark lifecycle bits a live registration may bind (eval-raw): SETUP / RESET / CHECK / SCORE.
+# ROLLOUT is deliberately absent — deprecated, never bound.
+BENCHMARK_BINDABLE: frozenset[SeqFlags] = frozenset(
+    {SeqFlags.SETUP, SeqFlags.RESET, SeqFlags.CHECK, SeqFlags.SCORE}
+)
+
+# Deprecated benchmark bits: reserved value, must not appear in any bindings.
+DEPRECATED_FLAGS: frozenset[SeqFlags] = frozenset({SeqFlags.ROLLOUT})
+
+
+def seqflags_json_schema(contract_version: str) -> dict:
+    """`SeqFlags` is an IntFlag, so `model_json_schema()` does not apply. Export it as an integer whose
+    named members are enumerated, with `x-flag-names` giving name→value for every member (WARMUP, PLAN and
+    the benchmark trio included). Every member is its own bit, so each is emitted once under its own name."""
+    # Every member has a distinct value (no aliases), so this maps value → name one-to-one.
+    canonical = {m.value: m.name for m in SeqFlags}  # value → member name (one entry per distinct bit)
+    names = {name: value for value, name in sorted(canonical.items())}
+    return {
+        "$schema": "https://json-schema.org/draft/2020-12/schema",
+        "title": "SeqFlags",
+        "description": "Lifecycle bitmask (IntFlag). One bit per lifecycle entrypoint.",
+        "type": "integer",
+        "enum": sorted(canonical),
+        "x-flag-names": names,
+        "x-contract-version": contract_version,
+    }

sequence_base/contract/policy.py

@@ -0,0 +1,172 @@
+"""
+契约 1 — the `@seq.policy` infra spec (SDK produces it, harness loader introspects it) and契约 2's
+declarative building blocks (ImageSpec / VolumeMount / Concurrency), defined once and reused by the
+deployments request so the two sides cannot drift.
+
+Every shape here forbids unknown fields and pins exact field types — no `Optional[Any] = None`, no bare
+`dict` standing in for a structured sub-shape (goal 2 / 4 / 5 / 18).
+"""
+from __future__ import annotations
+
+from pydantic import BaseModel, ConfigDict, Field, field_validator, model_validator
+
+from sequence_base.contract.accounts import SecretRef
+from sequence_base.contract.act import ActionSpace
+from sequence_base.contract.flags import SeqFlags
+
+__all__ = [
+    "ImageStepUvPip",
+    "ImageStepApt",
+    "ImageStepEnv",
+    "ImageStepRun",
+    "ImageStep",
+    "ImageSpec",
+    "VolumeMount",
+    "VolumeRef",
+    "Concurrency",
+    "ActionContract",
+    "PolicySpec",
+    "PolicyRegistration",
+]
+
+
+# ── ImageSpec — a discriminated union of exactly four step variants ───────────────────────────────
+# Each variant carries exactly one key; extra="forbid" makes a dict that names two keys (or an unknown
+# key) match NONE of them, so every step matches exactly one variant (goal 4). `run_commands` is its own
+# variant (SDK contract S2 goal 5) so an arbitrary build command is an ordered step in the chain, never
+# coalesced into pip/apt and never silently dropped for lack of a home.
+class ImageStepUvPip(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+    uv_pip_install: list[str]
+
+
+class ImageStepApt(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+    apt_install: list[str]
+
+
+class ImageStepEnv(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+    env: dict[str, str]
+
+
+class ImageStepRun(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+    run_commands: list[str]
+
+
+ImageStep = ImageStepUvPip | ImageStepApt | ImageStepEnv | ImageStepRun
+
+
+class ImageSpec(BaseModel):
+    """Declarative image (gateway builds it via Cloud Build) — = Modal `Image` message. Exactly one of
+    `base` (a pullable registry ref) or `dockerfile` (inline Dockerfile source) is set — the Dockerfile
+    is its OWN component, never smuggled into the `base` string (S2 goal 4), so the gateway can tell a
+    registry build from a Dockerfile build. `steps` is an ordered list of the four-variant union above
+    (a bare list[dict] is refused), extending whichever base was chosen."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    base: str | None = None
+    dockerfile: str | None = None
+    steps: list[ImageStep] = Field(default_factory=list)
+
+    @model_validator(mode="after")
+    def _base_xor_dockerfile(self) -> "ImageSpec":
+        # Exactly one origin. Neither → nothing to build; both → an ambiguous spec whose build order the
+        # gateway would have to guess. Either is a malformed image, caught at construction, not at build.
+        if (self.base is None) == (self.dockerfile is None):
+            raise ValueError(
+                "ImageSpec needs exactly one of base= (a registry ref) or dockerfile= "
+                "(inline Dockerfile source); got "
+                + ("both" if self.base is not None else "neither")
+            )
+        return self
+
+
+# ── shared sub-shapes (referenced by PolicySpec and the deployments body) ─────────────────────────
+class VolumeMount(BaseModel):
+    """A concrete mount: where the data lives and where it lands in the container. Both required."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    uri: str
+    mount: str
+
+
+class VolumeRef(BaseModel):
+    """PolicySpec.volumes value — at least a `uri`; a `mount` may pin the container path."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    uri: str
+    mount: str | None = None
+
+
+class Concurrency(BaseModel):
+    """= Modal max/target_concurrent_inputs. Both required."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    max_inputs: int
+    target_inputs: int
+
+
+class ActionContract(BaseModel):
+    """The fixed obs→ActionChunk contract a policy promises. Every field required; `action_space` reuses
+    contract 4's enum (not a free string). Each ActionChunk echoes exactly these invariants back."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    robot: str
+    action_space: ActionSpace
+    action_dim: int
+    control_frequency_hz: float
+
+
+class PolicySpec(BaseModel):
+    """What `@seq.policy(...)` accrues — a policy's complete infra declaration, losslessly. `action` is
+    required (no default): a policy without an obs→ActionChunk contract is not deployable."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    name: str
+    gpu: str | list[str] = Field(..., description="A GPU type, or a list = cross-provider fallback")
+    image: ImageSpec
+    weights: str = Field(..., description="Weights URI; scheme restricted to gs:// or hf://")
+    volumes: dict[str, VolumeRef] = Field(default_factory=dict)
+    secrets: list[SecretRef] = Field(default_factory=list)
+    min_containers: int = 0
+    max_containers: int | None = None
+    buffer_containers: int | None = None
+    scaledown_window: int = 600
+    concurrency: Concurrency | None = None
+    streaming: bool = False
+    frames_per_chunk: int | None = None
+    action: ActionContract
+
+    @field_validator("weights")
+    @classmethod
+    def _weights_scheme(cls, v: str) -> str:
+        if not (v.startswith("gs://") or v.startswith("hf://")):
+            raise ValueError("weights must be a gs:// or hf:// URI")
+        return v
+
+
+class PolicyRegistration(BaseModel):
+    """What the harness loader introspects: the spec, the SeqFlags→method-name bindings, and the
+    `handler_ref` it importlib-loads the policy class from. From one of these the loader recovers which
+    method is which lifecycle entrypoint (load / infer / on_episode / plan …)."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    spec: PolicySpec
+    bindings: dict[SeqFlags, str] = Field(..., description="lifecycle flag → method name on the handler")
+    handler_ref: str = Field(..., description='"module.path:ClassName" for importlib load')
+    # `bindings` is flag→method-name and cannot carry a per-binding parameter, so the one lifecycle hook
+    # that takes a schedule — @seq.plan(every_s=…), the low-frequency composite planner (契约 1) — needs a
+    # separate landing spot here. None when there is no PLAN binding; a positive seconds cadence otherwise.
+    # The harness reads bindings[PLAN] for the method and this for how often to call it.
+    plan_every_s: float | None = Field(
+        default=None, gt=0, description="Seconds between @seq.plan calls; set iff a PLAN binding exists"
+    )

sequence_base/errors/transport.py

@@ -0,0 +1,36 @@
+"""
+Shared transport status taxonomy — the infrastructure outcomes all three sides must speak the same
+way, so a caller can tell "retry in 2 min" from "stop and page someone" from "your payload is wrong".
+{from general-sequences api/handoff/runpod.py — the four classes it defines}
+"""
+from __future__ import annotations
+
+
+class TransportUnavailable(RuntimeError):
+    """Endpoint unreachable / not configured / worker failed → 503. Retrying is meaningful (says
+    "this upstream is down now", not "we are broken")."""
+
+
+class TransportWarming(RuntimeError):
+    """Model loading, not ready yet → 503 + Retry-After. Distinct from Unavailable: it WILL succeed
+    shortly and the only useful action is to wait `eta_s`. `job_id` (if set) is the warming job, left
+    running so the retry lands on a hot worker."""
+
+    def __init__(self, message: str, eta_s: float, job_id: str | None = None) -> None:
+        super().__init__(message)
+        self.eta_s = eta_s
+        self.job_id = job_id
+
+
+class TransportRejected(RuntimeError):
+    """The worker ran and refused the payload → 400, not 503. Never mislabel as a crash — a caller
+    must not retry a request that can never succeed."""
+
+
+class TransportOverloaded(RuntimeError):
+    """The admission queue is full → 429 + Retry-After. Refuse here rather than pile onto the worker
+    (an unbounded pile starves /ping and turns one burst into a 503-storm)."""
+
+    def __init__(self, message: str, retry_after_s: float = 1.0) -> None:
+        super().__init__(message)
+        self.retry_after_s = retry_after_s

sequence_base/obs/log.py

@@ -0,0 +1,57 @@
+"""
+Structured logging — one line per event: `seq ev=<what> rid=<which> k=v ...`, greppable, flushed.
+Deliberately `print` (not `logging`): in Cloud Run and in a bare worker, stdout IS the log.
+{from general-sequences obs.py}
+"""
+from __future__ import annotations
+
+import os
+import sys
+import time
+
+from sequence_base.obs.rid import clean
+
+
+def enabled() -> bool:
+    """On by default — a fleet that can't be debugged is worse than a noisy one. SEQ_LOG=0 quiets it."""
+    return os.environ.get("SEQ_LOG", "1") != "0"
+
+
+def log(ev: str, rid: str | None = None, **fields: object) -> None:
+    """Print one event. `seq` first so a grep finds our lines among a vendor's; `ev` a dotted
+    noun.verb that narrows by prefix; `rid` threads the call. flush=True so a line isn't lost when a
+    worker is killed before its 30 s log-tail ships."""
+    parts = [f"seq ev={clean(ev)}"]
+    if rid:
+        parts.append(f"rid={clean(rid)}")
+    parts.extend(f"{k}={clean(v)}" for k, v in fields.items() if v is not None)
+    print(" ".join(parts), file=sys.stdout, flush=True)
+
+
+class Timer:
+    """Measure a phase and log it as one line when it ends — including when it raises, so every
+    start has an end and a gap in the log is real rather than a missing print.
+
+        with Timer("act.upstream", rid, model=m) as t:
+            ...
+            t.add(status=200)
+    """
+
+    def __init__(self, ev: str, rid: str | None = None, **fields: object) -> None:
+        self.ev, self.rid, self.fields = ev, rid, dict(fields)
+        self.t0 = 0.0
+
+    def add(self, **fields: object) -> None:
+        self.fields.update(fields)
+
+    def __enter__(self) -> "Timer":
+        self.t0 = time.perf_counter()
+        return self
+
+    def __exit__(self, exc_type, exc, tb) -> bool:
+        ms = (time.perf_counter() - self.t0) * 1000
+        if exc_type is not None:
+            self.fields["ok"] = 0
+            self.fields["err"] = exc_type.__name__
+        log(self.ev, self.rid, ms=round(ms, 1), **self.fields)
+        return False

sequence_base/obs/rid.py

@@ -0,0 +1,31 @@
+"""
+Correlation id — one value threads a call through sdk → gateway → worker, so "what happened to that
+call" is one grep instead of three log stores and a stopwatch. {from general-sequences obs.py}
+"""
+from __future__ import annotations
+
+import re
+import uuid
+
+# The id travels in a HEADER, not a body field, so it survives paths that don't parse the body (the
+# worker reads it without touching the observation; a JSON-rewriting proxy can't lose it).
+HEADER = "X-Seq-Request-Id"
+
+_UNSAFE = re.compile(r"\s+")
+
+
+def new_rid() -> str:
+    """Short (read off a terminal, quoted in bug reports) + random (gateway instances don't
+    coordinate, so it must not collide)."""
+    return "r-" + uuid.uuid4().hex[:8]
+
+
+def clean(v: object) -> str:
+    """Collapse whitespace and cap length. A value with a space would split into two log fields and
+    let anything user-supplied forge keys into the line; 200 chars keeps a real error readable."""
+    s = _UNSAFE.sub("_", str(v))
+    return s if len(s) <= 200 else s[:197] + "..."
+
+
+# Back-compat alias: general-sequences code calls obs._clean; keep it working after the switch.
+_clean = clean