sequence-ai 0.44.2__tar.gz → 0.45.0__tar.gz

{sequence_ai-0.44.2 → sequence_ai-0.45.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: sequence-ai
-Version: 0.44.2
+Version: 0.45.0
 Summary: The inference and benchmark platform for physical AI: deploy a robot policy, run it on your robot, score it.
 Project-URL: Homepage, https://generalsequences.com
 Project-URL: Documentation, https://generalsequences.com/docs/
@@ -991,7 +991,8 @@ adapter's `__init__` keywords and a benchmark's `@seq.setup` keywords the same w
   (`observations=seq.Observations({"cam": seq.Stream(at=[-15, 0])})`) has its worker keep the frames its acts
   read: hand it every step's observation (`run()` and a `Player` do), only the steps a window reads go up, and each act
   is handed them with its own. When the copy holding an episode stops (out of memory, a crash), the robot goes on in a new episode with a
-  warning, and `run()` and a `Player` count it in `episode_resets`; on a worker of one copy the act sent again finds
+  warning - its steps counted from 0 again, none of the old one's observations handed to it - and `run()` and a `Player`
+  count it in `episode_resets`; on a worker of one copy the act sent again finds
   it still starting - a loop of `act()` calls waits that out, while `run()` and a `Player` raise it, saying so, and
   `run()` called again goes on in the new episode. A policy that only needs the last N
   frames needs no state: declare `observation=seq.ObservationContract(history=N)` and the robot sends

{sequence_ai-0.44.2 → sequence_ai-0.45.0}/README.md

@@ -945,7 +945,8 @@ adapter's `__init__` keywords and a benchmark's `@seq.setup` keywords the same w
   (`observations=seq.Observations({"cam": seq.Stream(at=[-15, 0])})`) has its worker keep the frames its acts
   read: hand it every step's observation (`run()` and a `Player` do), only the steps a window reads go up, and each act
   is handed them with its own. When the copy holding an episode stops (out of memory, a crash), the robot goes on in a new episode with a
-  warning, and `run()` and a `Player` count it in `episode_resets`; on a worker of one copy the act sent again finds
+  warning - its steps counted from 0 again, none of the old one's observations handed to it - and `run()` and a `Player`
+  count it in `episode_resets`; on a worker of one copy the act sent again finds
   it still starting - a loop of `act()` calls waits that out, while `run()` and a `Player` raise it, saying so, and
   `run()` called again goes on in the new episode. A policy that only needs the last N
   frames needs no state: declare `observation=seq.ObservationContract(history=N)` and the robot sends

{sequence_ai-0.44.2 → sequence_ai-0.45.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "sequence-ai"
-version = "0.44.2"
+version = "0.45.0"
 description = "The inference and benchmark platform for physical AI: deploy a robot policy, run it on your robot, score it."
 readme = "README.md"
 requires-python = ">=3.9"

{sequence_ai-0.44.2 → sequence_ai-0.45.0}/seq/named.py

@@ -10,7 +10,8 @@ each name is a method of the class (its own or inherited) taking what the worker
 ones its constructor - or the factory `make` names - takes → the class keeps every method as written, and its
 registration names them (INFER, OBSERVE, RESET, ON_EPISODE) beside how the worker builds it (PolicyConstructor): the
 worker calls the constructor at load, config files read and "{weights}" filled where it runs (sequence_base.construct),
-resets the class at an episode's first act, hands its observe method each observation, then asks its infer method.
+resets the class at an episode's first act, hands its observe method each observation - and its step in the episode,
+from 0, by name, when the method takes `step` - then asks its infer method.
 
 WHY the platform calls the user's methods rather than the user writing @seq.load / @seq.infer around them: the goal
 is that a class that runs locally deploys as it is - "just add a decoration and now you can upload it" - and nothing
@@ -106,7 +107,8 @@ def _method(cls: type, arg: str, name: Any) -> str:
 
 def _takes(cls: type, arg: str, name: str | None, positional: int) -> None:
     """That the method `name` takes `positional` arguments besides self and no more required ones: the worker hands
-    observe one observation, infer the act's inputs (or nothing when the class observes), reset and end nothing."""
+    observe one observation - and step=, its step in the episode, when it takes one - infer the act's inputs (or nothing
+    when the class observes), reset and end nothing."""
     if name is None:
         return
     fn = getattr(cls, name)
@@ -117,11 +119,16 @@ def _takes(cls: type, arg: str, name: str | None, positional: int) -> None:
     params = list(sig.parameters.values())
     if params and inspect.isfunction(inspect.getattr_static(cls, name)):
         params = params[1:]
+
+    by_name = {"step": 0} if arg == "observe" and any(
+        p.kind is inspect.Parameter.VAR_KEYWORD or (p.name == "step" and p.kind in (
+            inspect.Parameter.POSITIONAL_OR_KEYWORD, inspect.Parameter.KEYWORD_ONLY)) for p in params) else {}
     try:
-        inspect.Signature(params).bind(*([None] * positional))
+        inspect.Signature(params).bind(*([None] * positional), **by_name)
     except TypeError:
         hands = {0: "nothing", 1: "one argument"}[positional]
-        why = {"observe": "each observation", "infer": "the act's inputs" if positional else
+        why = {"observe": "each observation, and step= - its step in the episode, from 0 - when it takes one",
+               "infer": "the act's inputs" if positional else
                "nothing - its observations went to observe=", "reset": "nothing", "end": "nothing",
                "sample": "nothing - it returns the episode's act inputs"}[arg]
         raise PolicyDefinitionError(f"{cls.__name__}.{name}{sig} ({arg}=): the worker hands it {hands} ({why})") \

{sequence_ai-0.44.2 → sequence_ai-0.45.0}/sequence_ai/_core/direct.py

@@ -25,7 +25,8 @@ still does `self._t.post("/v1/act", payload)`, and this class routes that one pa
 worker while `/v1/models` and `/v1/act/ready` stay on the gateway.
 
 The data plane is worker_transport.py's (one kept-alive client to one worker's `/act`), the pin
-pinned_tls.py's (the worker's certificate checked by the fingerprint the gateway pinned).
+pinned_tls.py's (the worker's certificate checked by the fingerprint the gateway pinned). A robot's observations between
+acts are direct_observe.py's, its episodes direct_episode.py's: DirectConnection mixes both in.
 
 Stdlib `ssl` + `hashlib` only for the pin (no `cryptography`, no `certifi`: a worker checked by the
 CAs instead is public_tls.py's); httpx-only, Python 3.9-clean (no runtime `X | Y`, no `match`); and none
@@ -48,15 +49,13 @@ from typing import Any, Callable, NamedTuple, Optional
 
 from ..errors import AuthError, Conflict, InternalError, InvalidRequest, SequencesError, Unavailable
 from . import act_size
-from .names import segment
 from .public_tls import unmask_name
 from .transport import DEFAULT_TIMEOUT_S, Transport
 from .warn import warn
-from . import obs_schedule as _obs_schedule
 from . import observe_stream as _observe
-from .window import Window as _Window
-from .worker_transport import (_EPISODE_END_S, _KEEP_PING_TIMEOUT_S, _STILL_OPENING, _WorkerGone, _WorkerTransport,
-                               _frames_on, _wait_set)
+from .worker_transport import _STILL_OPENING, _WorkerGone, _WorkerTransport, _frames_on, _wait_set
+from .direct_episode import _EPISODE_LOST, _STATE_GONE, _Episodes
+from .direct_observe import _ObservationStream
 
 
 
@@ -107,21 +106,6 @@ def _busy_backoff(attempt: int, retry_after_s: Optional[float]) -> float:
 
 
 
-
-
-
-
-_COPY_STOPPED = frozenset({"gpu_out_of_memory", "host_out_of_memory", "crashed", "hung"})
-_EPISODE_LOST = "episode_lost"
-
-
-
-
-_BATCH_FAILED = "batch_failed"
-_STATE_GONE = _COPY_STOPPED | {_BATCH_FAILED}
-
-
-
 _SAY_BUSY_AFTER_S = 5.0
 
 
@@ -366,7 +350,7 @@ def _keep_alive(ref: "weakref.ref[DirectConnection]", stop: threading.Event) ->
         del conn
 
 
-class DirectConnection:
+class DirectConnection(_ObservationStream, _Episodes):
     """
     Control/data-plane split behind the `Transport` surface `Policy` already drives.
 
@@ -531,6 +515,7 @@ class DirectConnection:
         feedback = payload.pop("_feedback", None)
 
         own = self._own_act(asked, step_at, payload.get("plan")) if asked is not None else None
+        resets = self.episode_resets
         resent = False
         lost = 0
         busy_since: Optional[float] = None
@@ -541,6 +526,9 @@ class DirectConnection:
             if asked is not None:
                 payload["episode_id"] = asked
             self._apply_episode(payload)
+            if own is not None and self.episode_resets != resets:
+
+                own, resets = self._own_anew(asked, own), self.episode_resets
             if own is not None:
                 self._observed_act(payload, worker, own, timeout_s)
             if not by_hand:
@@ -660,183 +648,6 @@ class DirectConnection:
                     warn(f"waiting for a free copy of the policy on its worker: {exc}")
                 time.sleep(wait)
 
-    def observe(self, inputs: Any, episode_id: str, step: Optional[int] = None) -> int:
-        """One observation of the caller's episode `episode_id`, handed over as the robot makes it: its number in the
-        episode, at once. Packed here, on the robot's own thread (what msgpack cannot carry is refused as an act's inputs
-        are), then posted on a connection of its own to a worker that takes them (observe_stream), held for the
-        episode's next act while the worker has not said whether it does, and sent nowhere when it does not. The next
-        act of the episode is the next number. A policy that declares what it reads keeps it by step (_observe_window);
-        `step`: the step it was made at (a Player's rows played), else the next. Mid-episode, its worker gone and the
-        one in its place starting (or the robot in line for one), the observation is kept for the episode's next act,
-        which waits for that worker as an act does and sends it: never waited for here."""
-        self._assert_open()
-        try:
-            self._ensure_connected()
-            reachable = True
-        except Unavailable as exc:
-            if self.contract is None or not (exc.warming or exc.queued):
-                raise
-
-
-
-            reachable = False
-        if _obs_schedule.reads_past(self._observations):
-            return self._observe_window(inputs, episode_id, step, reachable)
-        try:
-            packed = _observe.packed(inputs)
-        except ValueError as exc:
-            raise InvalidRequest(f"observe(): this observation cannot be sent - {exc}") from None
-        with self._lock:
-            n = self._numbers.get(episode_id, 0)
-            self._numbers[episode_id] = n + 1
-            worker = self._worker if reachable else None
-            wid = self._worker_episode if episode_id == self._caller_episode and self._worker_episode else episode_id
-            takes = None if worker is None else worker.takes_observations
-            stream = self._stream_for(worker) if takes else None
-            held = self._held.pop(episode_id, []) if takes is not None else []
-            if takes is None:
-                self._held.setdefault(episode_id, []).append((n, _observe.frame(n, packed)))
-        if stream is not None:
-            for s, f in [*held, (n, _observe.frame(n, packed))]:
-                stream.put(wid, s, f)
-            self._say_refusals(stream)
-        elif takes is False:
-            self._say_unread()
-        return n
-
-    def expect_ask(self, episode_id: str, step: Optional[int]) -> None:
-        """The step a Player expects to ask at next in `episode_id` (its playback left until its lead, or the planning
-        worker's time) - None: none, its run's last rows in hand: its window's frames go up as that act reads them, not
-        by a guess from the last spacing, and none go up ahead when no act is coming."""
-        with self._lock:
-            win = self._windows.get(episode_id)
-            if win is not None:
-                win.expect(step)
-
-    def reads_past(self) -> bool:
-        """Whether the policy reads steps before an act's own (its Observations, as connect answered them): a Player then
-        hands it every tick's observation (observe), each numbered by its step."""
-        return _obs_schedule.reads_past(self._observations)
-
-    def _observe_window(self, inputs: Any, episode_id: str, step: Optional[int], reachable: bool = True) -> int:
-        """observe() for a policy that declares what it reads, steps before an act's own among it: numbered by step and
-        kept (its Window) - what the next act is expected to read at that step posted now, to a worker that takes them;
-        the rest goes up just before the act that reads it. Not `reachable` (its worker restarting): all of it goes up
-        just before the act. Returns its step."""
-        with self._lock:
-            worker = self._worker if reachable else None
-            takes = None if worker is None else worker.takes_observations
-            win = self._window_for(episode_id, None)
-            s = win.step(step)
-            uploads = win.observe(s, inputs)
-            if takes is None:
-                win.lost()
-            wid = self._worker_episode if episode_id == self._caller_episode and self._worker_episode else episode_id
-            stream = self._stream_for(worker) if takes else None
-        if stream is not None:
-            for st, f in self._packed_steps(uploads):
-                stream.put(wid, st, f)
-            self._say_refusals(stream)
-        elif takes is False:
-            self._say_unread()
-        return s
-
-    def _window_for(self, episode_id: str, plan: Any) -> "_Window":
-        """The episode's Window, made at its first observation or act (called under self._lock): its schedule taken to
-        steps by the robot's rate - its act's plan.hz (a Player's), else connect(control_hz=) - and the next act expected
-        as far on as the policy's open_loop_horizon until there are two."""
-        win = self._windows.get(episode_id)
-        if win is None:
-            rate = plan.get("hz") if isinstance(plan, dict) else None
-            try:
-                sched = _obs_schedule.of(self._observations, rate=rate or self.control_hz)
-            except ValueError as exc:
-                raise InvalidRequest(str(exc)) from None
-            gap = (self._actions or {}).get("open_loop_horizon") if isinstance(self._actions, dict) else None
-            win = self._windows[episode_id] = _Window(sched, gap=gap or 1)
-        return win
-
-    @staticmethod
-    def _packed_steps(uploads: list) -> list:
-        """[(step, frame)] of a Window's uploads, packed on the caller's thread: what msgpack cannot carry refused here."""
-        try:
-            return [(s, _observe.frame(s, _observe.packed(obs))) for s, obs in uploads]
-        except ValueError as exc:
-            raise InvalidRequest(f"observe(): an observation cannot be sent - {exc}") from None
-
-    def _stream_for(self, worker: "_WorkerTransport") -> "_observe.ObserveStream":
-        """The stream posting to `worker` - made the first time it is asked for, and anew for another worker, posting
-        again what the one before kept since each episode's last served act; another worker holds none of a window's
-        frames, which go again as their acts read them. Called under self._lock."""
-        if self._stream is None or self._stream_to is not worker:
-            carried = {}
-            if self._stream is not None:
-                carried = self._stream.carry()
-                self._stream.close()
-                for win in self._windows.values():
-                    win.lost()
-            self._stream, self._stream_to = _observe.ObserveStream(worker.post_observe, carried), worker
-        return self._stream
-
-    def _own_act(self, episode_id: str, step_at: Optional[int] = None, plan: Any = None) -> Optional[tuple]:
-        """For an act of an episode the robot hands observations to (observe), or of a policy that reads steps before an
-        act's own: (its number - `step_at`, a Player's rows played, else the next - the frames held for it, its Window
-        or None); None for any other act."""
-        self._ensure_connected()
-        with self._lock:
-            if _obs_schedule.reads_past(self._observations):
-                if self._observations.get("unit") == "seconds" and not (isinstance(plan, dict) and plan.get("hz")):
-
-                    raise InvalidRequest("this policy counts its window in seconds, which its worker takes to steps by "
-                                         "your robot's rate: send each act with steps_left= (its plan carries the rate "
-                                         "connect(control_hz=) says), or let run() or a Player send them")
-                win = self._window_for(episode_id, plan)
-                return win.step(step_at), [], win
-            if episode_id not in self._numbers:
-                return None
-            n = self._numbers[episode_id]
-            self._numbers[episode_id] = n + 1
-            return n, self._held.pop(episode_id, []), None
-
-    def _observed_act(self, payload: dict, worker: "_WorkerTransport", own: tuple, timeout_s: Optional[float]) -> None:
-        """The act's body, each try, in place: its number (`seq`) when its worker takes the stream - the frames held for
-        it posted first - and nothing of the stream when it does not: its policy reads the act's own alone. A worker
-        that has not answered yet (the first act, or one after a reconnect, whose stream posts what the one before kept)
-        is waited for as the act would wait for it anyway (await_answer)."""
-        n, held, win = own
-        if worker.takes_observations is None:
-            worker.await_answer(timeout_s)
-        if worker.takes_observations:
-            with self._lock:
-                stream = self._stream_for(worker)
-                uploads = win.act(n) if win is not None else []
-            for s, f in [*self._packed_steps(uploads), *held]:
-                stream.put(payload["episode_id"], s, f)
-            held.clear()
-            payload["seq"] = n
-            self._say_refusals(stream)
-            return
-        payload.pop("seq", None)
-        if held or win is not None:
-            held.clear()
-            self._say_unread()
-
-    def _say_unread(self) -> None:
-        """Said once a connection: observations handed to observe() went nowhere, as its worker does not take them."""
-        with self._lock:
-            said, self._said_unread = self._said_unread, True
-        if not said:
-            warn("observe() hands this policy nothing: its worker reads each act's own observation alone. A policy is "
-                 "handed the ones between acts when it declares observations=seq.Observations(every=1) (naming an "
-                 "observe= method does) and its worker takes them - one deployed before workers did, once `seq deploy` builds it "
-                 "again")
-
-    def _say_refusals(self, stream: "_observe.ObserveStream") -> None:
-        """What the worker refused to keep of an episode's observations (more than it keeps between two acts), said once
-        an episode on the robot's own thread: those were left out, and its acts read the ones it kept."""
-        for why in stream.refusals():
-            warn(f"observations left out: the worker refused them ({why}); the episode's acts read the ones it kept")
-
     def handshake(self) -> Optional[dict]:
         """Connect now if not yet connected — the same handshake the first act makes — and return the contract
         the deployment declared ({"action", "observation", "embodiment"}). Lets Policy check an observation
@@ -1416,144 +1227,6 @@ A robot in line had no seat: it is told it is no longer in line. `why` is the pl
         else:
             self._lease_deadline = None
 
-    def end_episode(self, episode_id: str) -> None:
-        """The robot's episode is over: the worker frees its state now (a stateful policy's @seq.on_episode runs
-        and its replica returns to the pool) instead of after its TTL with no act. Never raises. When the platform asked the
-        robot to move (its worker is leaving), this boundary is where it does: the next episode starts on a worker
-        already up - at its deployment's cap, where the worker is replaced in place, on the new one once it is up - and
-        nothing is cut. The worker it leaves is told the episode ended while the move's connect goes, not before it;
-        kept on that worker after all, its next episode starts once the worker has been told, as with no move.
-        """
-        with self._lock:
-            worker = None if self._closed else self._worker
-            wid = self._worker_episode if episode_id == self._caller_episode else episode_id
-            self._episode_open = False
-            self._settle_params()
-
-            self._numbers.pop(episode_id, None)
-            self._held.pop(episode_id, None)
-            self._windows.pop(episode_id, None)
-            if self._stream is not None and wid:
-                self._stream.end(wid)
-            moving = worker is not None and self._rotate is not None and _ready(self._rotate)
-        told = None
-        if worker is not None and wid:
-            if moving:
-                told = worker.end_episode_behind(wid)
-            else:
-                worker.post_episode_end(wid)
-        try:
-            with self._lock:
-                if self._rotate is None or self._closed or self._worker is None:
-                    return
-                if not _ready(self._rotate):
-
-
-
-
-                    return
-
-                self._caller_episode = self._worker_episode = None
-                try:
-                    self._connect(renew=False, move=True)
-                except Unavailable:
-
-
-
-
-
-
-                    if self._worker is not None:
-                        self._worker.gone = True
-                except Exception:
-                    pass
-        finally:
-            if told is not None:
-                with self._lock:
-                    stays = self._worker is worker and not worker.gone
-                if stays:
-
-
-                    told.join(_EPISODE_END_S + _KEEP_PING_TIMEOUT_S)
-
-    def label_episode(self, episode_id: str, *, success: bool, notes: str = "") -> None:
-        """How the robot's episode went, kept with the deployment's captured field data (`seq policy capture`):
-        written for the id the workers saw it under — and every id it carried after a reconnect moved it. Raises on
-        failure.
-        """
-        with self._lock:
-            ids = [episode_id, *self._aliases.get(episode_id, [])]
-        for wid in ids:
-
-            self._gateway.post(f"/v1/deployments/{segment(self._model)}/episodes/{segment(wid)}/label",
-                               {"success": bool(success), "notes": notes})
-
-    def _take_params(self, answered: dict) -> None:
-        """What the platform answered the session runs with: at once, or — while an episode runs and they differ —
-        at its boundary, so one episode never runs on two sets of parameters."""
-        if self._episode_open and (answered or None) != self._params:
-            self._pending_params = answered
-        else:
-            self._params, self._pending_params = answered or None, None
-
-    def _settle_params(self) -> None:
-        """An episode boundary: parameters a renewal answered during the episode take effect now."""
-        if self._pending_params is not None:
-            self._params, self._pending_params = self._pending_params or None, None
-
-    def _apply_episode(self, payload: dict) -> None:
-        """Remap the caller's episode id to the current worker-side id (in place)."""
-        with self._lock:
-            caller = payload.get("episode_id")
-            if caller is None:
-                return
-            if caller != self._caller_episode:
-
-                self._caller_episode = caller
-                self._worker_episode = caller
-                self._settle_params()
-            self._episode_open = True
-            payload["episode_id"] = self._worker_episode
-
-    def _rotate_episode(self, notice: Optional[dict] = None, *, stopped: Optional[str] = None) -> Optional[str]:
-        """New worker → the episode restarts there; surface it, do not continue silently - with why, when the platform
-        had said the robot was to move (`notice`, its `rotate`). `stopped`: the copy of the policy that held it stopped
-        (its cause, _COPY_STOPPED), or ended it for a batch that raised (_BATCH_FAILED), on the same worker. Returns the
-        worker-side id it leaves, None on a stateless path."""
-        if self._caller_episode is None:
-            return None
-        left = self._worker_episode
-        self._worker_episode = uuid.uuid4().hex
-        self._aliases.setdefault(self._caller_episode, []).append(self._worker_episode)
-        self.episode_resets += 1
-        if self._stream is not None and left:
-
-            self._stream.move(left, self._worker_episode)
-        if self._caller_episode in self._windows:
-            self._windows[self._caller_episode].lost()
-        if stopped == _BATCH_FAILED:
-            warn("episode was reset: a batch it was in failed, so what the policy kept of it may be half changed and was "
-                 "given up; the robot goes on in a new episode")
-            return left
-        if stopped is not None:
-            warn(f"episode was reset: the copy of the policy that held it stopped ({stopped}); its next act starts a new "
-                 "episode, and what the policy kept of this one did not carry over")
-            return left
-        why = f" ({_moving_words(notice, moved=True)})" if notice else ""
-        warn("episode was reset after a reconnect to a new worker" + why + "; what the policy kept of this episode "
-             "on the previous worker did not carry over")
-        return left
-
-    def _lose_episode(self, worker: "_WorkerTransport", cause: Optional[str]) -> None:
-        """The copy that held the caller's episode stopped, or ended it for a batch that raised (_STATE_GONE): a new
-        worker-side episode, said with the cause (_rotate_episode), and the one it leaves ended on the worker - its lost
-        mark cleared, nothing else to free - so the act goes again under the new id. Best effort: an end that does not
-        arrive leaves the mark to run out."""
-        with self._lock:
-            left = self._rotate_episode(stopped=cause or "unknown cause")
-        if left:
-            worker.post_episode_end(left)
-
     def _assert_open(self) -> None:
         if self._closed:
             raise SequencesError("this connection is closed; open a new one with connect()")

sequence_ai-0.45.0/sequence_ai/_core/direct_episode.py

@@ -0,0 +1,181 @@
+"""
+A DirectConnection's episodes, mixed into it (_Episodes): the caller's episode id mapped to the one its worker sees
+(_apply_episode) - a new one when a reconnect moved the robot or the copy that held it stopped (_rotate_episode,
+_lose_episode) - its end told to the worker, where a move the platform asked for happens (end_episode), how it went kept
+with the captured field data (label_episode), and the session's parameters taking effect at its boundaries. The
+connection, its worker and its lock are DirectConnection's (direct.py), whose move-notice words these read.
+
+"""
+from __future__ import annotations
+
+import uuid
+from typing import Optional
+
+from ..errors import Unavailable
+from .names import segment
+from .warn import warn
+from .worker_transport import _EPISODE_END_S, _KEEP_PING_TIMEOUT_S, _WorkerTransport
+
+
+
+
+
+
+
+
+_COPY_STOPPED = frozenset({"gpu_out_of_memory", "host_out_of_memory", "crashed", "hung"})
+_EPISODE_LOST = "episode_lost"
+
+
+
+
+_BATCH_FAILED = "batch_failed"
+_STATE_GONE = _COPY_STOPPED | {_BATCH_FAILED}
+
+
+class _Episodes:
+    """DirectConnection's episodes (the module's docstring)."""
+
+    def end_episode(self, episode_id: str) -> None:
+        """The robot's episode is over: the worker frees its state now (a stateful policy's @seq.on_episode runs
+        and its replica returns to the pool) instead of after its TTL with no act. Never raises. When the platform asked the
+        robot to move (its worker is leaving), this boundary is where it does: the next episode starts on a worker
+        already up - at its deployment's cap, where the worker is replaced in place, on the new one once it is up - and
+        nothing is cut. The worker it leaves is told the episode ended while the move's connect goes, not before it;
+        kept on that worker after all, its next episode starts once the worker has been told, as with no move.
+        """
+        from .direct import _ready
+        with self._lock:
+            worker = None if self._closed else self._worker
+            wid = self._worker_episode if episode_id == self._caller_episode else episode_id
+            self._episode_open = False
+            self._settle_params()
+
+            self._numbers.pop(episode_id, None)
+            self._held.pop(episode_id, None)
+            self._windows.pop(episode_id, None)
+            if self._stream is not None and wid:
+                self._stream.end(wid)
+            moving = worker is not None and self._rotate is not None and _ready(self._rotate)
+        told = None
+        if worker is not None and wid:
+            if moving:
+                told = worker.end_episode_behind(wid)
+            else:
+                worker.post_episode_end(wid)
+        try:
+            with self._lock:
+                if self._rotate is None or self._closed or self._worker is None:
+                    return
+                if not _ready(self._rotate):
+
+
+
+
+                    return
+
+                self._caller_episode = self._worker_episode = None
+                try:
+                    self._connect(renew=False, move=True)
+                except Unavailable:
+
+
+
+
+
+
+                    if self._worker is not None:
+                        self._worker.gone = True
+                except Exception:
+                    pass
+        finally:
+            if told is not None:
+                with self._lock:
+                    stays = self._worker is worker and not worker.gone
+                if stays:
+
+
+                    told.join(_EPISODE_END_S + _KEEP_PING_TIMEOUT_S)
+
+    def label_episode(self, episode_id: str, *, success: bool, notes: str = "") -> None:
+        """How the robot's episode went, kept with the deployment's captured field data (`seq policy capture`):
+        written for the id the workers saw it under — and every id it carried after a reconnect moved it. Raises on
+        failure.
+        """
+        with self._lock:
+            ids = [episode_id, *self._aliases.get(episode_id, [])]
+        for wid in ids:
+
+            self._gateway.post(f"/v1/deployments/{segment(self._model)}/episodes/{segment(wid)}/label",
+                               {"success": bool(success), "notes": notes})
+
+    def _take_params(self, answered: dict) -> None:
+        """What the platform answered the session runs with: at once, or — while an episode runs and they differ —
+        at its boundary, so one episode never runs on two sets of parameters."""
+        if self._episode_open and (answered or None) != self._params:
+            self._pending_params = answered
+        else:
+            self._params, self._pending_params = answered or None, None
+
+    def _settle_params(self) -> None:
+        """An episode boundary: parameters a renewal answered during the episode take effect now."""
+        if self._pending_params is not None:
+            self._params, self._pending_params = self._pending_params or None, None
+
+    def _apply_episode(self, payload: dict) -> None:
+        """Remap the caller's episode id to the current worker-side id (in place)."""
+        with self._lock:
+            caller = payload.get("episode_id")
+            if caller is None:
+                return
+            if caller != self._caller_episode:
+
+                self._caller_episode = caller
+                self._worker_episode = caller
+                self._settle_params()
+            self._episode_open = True
+            payload["episode_id"] = self._worker_episode
+
+    def _rotate_episode(self, notice: Optional[dict] = None, *, stopped: Optional[str] = None) -> Optional[str]:
+        """New worker → the episode restarts there; surface it, do not continue silently - with why, when the platform
+        had said the robot was to move (`notice`, its `rotate`). `stopped`: the copy of the policy that held it stopped
+        (its cause, _COPY_STOPPED), or ended it for a batch that raised (_BATCH_FAILED), on the same worker. The new
+        episode is handed none of the old one's observations and counts its steps from 0 - the act on its way its first
+        (Window.restart, post) - as the policy's Episode does; a run's counts go on. Returns the worker-side id it leaves,
+        None on a stateless path."""
+        if self._caller_episode is None:
+            return None
+        left = self._worker_episode
+        self._worker_episode = uuid.uuid4().hex
+        self._aliases.setdefault(self._caller_episode, []).append(self._worker_episode)
+        self.episode_resets += 1
+        if self._stream is not None and left:
+            self._stream.end(left)
+        win = self._windows.get(self._caller_episode)
+        if win is not None:
+            win.restart(win.asked if win.asked > win.acted else win.unreached)
+        elif self._caller_episode in self._numbers:
+            self._number_anew(self._caller_episode)
+        if stopped == _BATCH_FAILED:
+            warn("episode was reset: a batch it was in failed, so what the policy kept of it may be half changed and was "
+                 "given up; the robot goes on in a new episode")
+            return left
+        if stopped is not None:
+            warn(f"episode was reset: the copy of the policy that held it stopped ({stopped}); its next act starts a new "
+                 "episode, and what the policy kept of this one did not carry over")
+            return left
+        from .direct import _moving_words
+        why = f" ({_moving_words(notice, moved=True)})" if notice else ""
+        warn("episode was reset after a reconnect to a new worker" + why + "; what the policy kept of this episode "
+             "on the previous worker did not carry over")
+        return left
+
+    def _lose_episode(self, worker: "_WorkerTransport", cause: Optional[str]) -> None:
+        """The copy that held the caller's episode stopped, or ended it for a batch that raised (_STATE_GONE): a new
+        worker-side episode, said with the cause (_rotate_episode), and the one it leaves ended on the worker - its lost
+        mark cleared, nothing else to free - so the act goes again under the new id. Best effort: an end that does not
+        arrive leaves the mark to run out."""
+        with self._lock:
+            left = self._rotate_episode(stopped=cause or "unknown cause")
+        if left:
+            worker.post_episode_end(left)