sequence-base 0.4.32__tar.gz → 0.4.33__tar.gz

{sequence_base-0.4.32 → sequence_base-0.4.33}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: sequence-base
-Version: 0.4.32
+Version: 0.4.33
 Summary: Shared foundation for the Sequences platform — wire contract, correlation, error taxonomy, constants. Used by the robot SDK, gateway, and container harness.
 Project-URL: Changelog, https://generalsequences.com/docs/changelog/
 Requires-Python: >=3.10

{sequence_base-0.4.32 → sequence_base-0.4.33}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "sequence-base"
-version = "0.4.32"
+version = "0.4.33"
 description = "Shared foundation for the Sequences platform — wire contract, correlation, error taxonomy, constants. Used by the robot SDK, gateway, and container harness."
 requires-python = ">=3.10"
 dependencies = ["pydantic>=2.0"]

{sequence_base-0.4.32 → sequence_base-0.4.33}/sequence_base/by_name.py

@@ -17,10 +17,15 @@ rule on both sides.
 
 What the platform hands a method itself is `episode` - an act function, an observe function and the method an
 episode's end calls alike - and an eval's `seed`; `retired(parameters, what)` refuses a method that still takes what it
-handed once (episode_id, embodiment, feedback), and `ends(parameters, what)` an end method that takes anything but the episode,
-each in words that say what to write instead - the SDK when a class is declared, the worker when it loads one declared
-before.
+handed once (episode_id, embodiment, feedback, and a composite's plan and robot), and `ends(parameters, what)` an end
+method that takes anything but the episode, each in words that say what to write instead - the SDK when a class is
+declared, the worker when it loads one declared before.
 
+
+A composite's planner, @seq.plan, is called on a clock with the episode alone and what it returns is kept in the
+episode's state, which the act function beside it reads: `plan_refused(plan, infer_takes_episode=...)` says why a plan
+method cannot be served as it is written, and `wake_on_refused(value)` why a wake_on is no list of keys - one set of
+words for the SDK and the worker.
 """
 from __future__ import annotations
 
@@ -29,17 +34,26 @@ from collections.abc import Iterable, Mapping
 from dataclasses import dataclass
 from typing import Any
 
-__all__ = ["INFER_PLATFORM", "OBSERVE_PLATFORM", "RETIRED", "ByName", "ends", "retired", "takes_by_name"]
+__all__ = ["INFER_PLATFORM", "OBSERVE_PLATFORM", "RETIRED", "WAKE_ON", "ByName", "ends", "plan_refused", "retired",
+           "takes_by_name", "wake_on_refused"]
 
 
 
-INFER_PLATFORM = frozenset({"seed", "episode", "plan", "robot"})
+INFER_PLATFORM = frozenset({"seed", "episode"})
 OBSERVE_PLATFORM = frozenset({"step", "episode"})
 
 
 RETIRED = {"episode_id": "take episode, a seq.Episode, and read episode.id",
            "embodiment": "send what the robot is with its observations, in observe(x)",
-           "feedback": "send what the robot was playing with its observations, in observe(x)"}
+           "feedback": "send what the robot was playing with its observations, in observe(x)",
+
+           "plan": ('take episode and read the newest plan as episode.state["seq.plans"][-1]["value"], what '
+                    '@seq.plan returned (before the first, episode.state.get("seq.plans") is None)'),
+           "robot": ("take episode: episode.state is the robot's own dict, which @seq.plan is handed too, and "
+                     "episode.id names it")}
+
+WAKE_ON = ('@seq.plan(wake_on=...) is a list of the observation\'s keys whose arrival plans at once, each a string - '
+           'wake_on=["say"]: an observation that holds "say" plans its episode then, its clock going on beside')
 
 _VARIADIC = (inspect.Parameter.VAR_POSITIONAL, inspect.Parameter.VAR_KEYWORD)
 
@@ -125,3 +139,37 @@ def ends(parameters: Iterable[inspect.Parameter], what: str) -> str | None:
 
 def _keys(names: list) -> str:
     return ", ".join(repr(n) for n in names)
+
+
+def plan_refused(plan: Any, *, infer_takes_episode: bool) -> str | None:
+    """Why `plan`, a policy's @seq.plan method, cannot be served as it is written - or None, when it can: it is called on
+    a clock with the episode alone, plain or async, returning (never yielding) what is kept in the episode's state for
+    the act function beside it, which must take the episode to read it.
+"""
+    name = getattr(plan, "__name__", "plan")
+    if inspect.isgeneratorfunction(plan) or inspect.isasyncgenfunction(plan):
+        return (f"@seq.plan {name} returns its plan rather than yielding it: return the value, which is kept in "
+                'episode.state["seq.plans"] (None keeps the plans as they are)')
+    try:
+        params = inspect.signature(plan).parameters
+    except (TypeError, ValueError):
+        params = {}
+    others = [n for n, p in params.items()
+              if n not in ("self", "episode") and p.default is inspect.Parameter.empty and p.kind not in _VARIADIC]
+    if "episode" not in params or others:
+        return (f"@seq.plan is handed the episode alone: write def {name}(self, episode) - read what it needs from "
+                'episode.state, and return the plan, which is kept in episode.state["seq.plans"] (None keeps the plans '
+                "as they are)")
+    if not infer_takes_episode:
+        return ("a policy with @seq.plan reads its plans where its act function runs: take episode in it and read "
+                'episode.state["seq.plans"][-1]["value"]')
+    return None
+
+
+def wake_on_refused(value: Any) -> str | None:
+    """Why `value` cannot be a @seq.plan's wake_on - the observation's top-level keys whose arrival plans an episode at
+    once - or None, when it can: a list (or tuple) of strings, or None for none.
+"""
+    if value is None or (isinstance(value, (list, tuple)) and all(isinstance(k, str) for k in value)):
+        return None
+    return WAKE_ON