arkitekt-runtime 4.2.0__tar.gz → 4.3.0__tar.gz

{arkitekt_runtime-4.2.0 → arkitekt_runtime-4.3.0}/PKG-INFO

@@ -1,14 +1,14 @@
 Metadata-Version: 2.5
 Name: arkitekt-runtime
-Version: 4.2.0
+Version: 4.3.0
 Summary: the execution core of an Arkitekt app: agent, actors, tasks, journal, state and structure serialization, shared by every runtime
 Author-email: jhnnsrs <jhnnsrs@gmail.com>
 License-Expression: MIT
 Requires-Python: >=3.11
-Requires-Dist: arkitekt-spec>=2.0.1
+Requires-Dist: arkitekt-spec>=3.4
 Requires-Dist: janus>=2.0.0
 Requires-Dist: jsonpatch>=1.33
-Requires-Dist: koil>=3.3.3
+Requires-Dist: koil>=3.3.6
 Requires-Dist: pydantic>=2.11
 Provides-Extra: qt
 Requires-Dist: qtpy>=2.4; extra == 'qt'

{arkitekt_runtime-4.2.0 → arkitekt_runtime-4.3.0}/arkitekt_runtime/actors/types.py

@@ -22,7 +22,7 @@ from collections.abc import Sequence
 
 if TYPE_CHECKING:
     from arkitekt_spec.declare.app import AppRegistry
-    from arkitekt_runtime.agents.connection import ConnectionListener
+    from arkitekt_spec.declare.agents.connection import ConnectionListener
     from arkitekt_runtime.agents.lock import TaskLock
 
 

{arkitekt_runtime-4.2.0 → arkitekt_runtime-4.3.0}/arkitekt_runtime/agents/base.py

@@ -56,7 +56,13 @@ from arkitekt_runtime.agents.journal import (
 )
 from arkitekt_runtime.task_scope import current_task_id, task_id_scope
 from arkitekt_spec.declare.agents.types import AppContext, T
-from arkitekt_runtime.agents.connection import ConnectionListener, ConnectionState
+from arkitekt_spec.declare.agents.connection import (
+    ConnectionListener,
+    ConnectionState,
+    TaskEvent,
+    TaskEventKind,
+    TaskListener,
+)
 from arkitekt_runtime.agents.policy import ConnectionPolicy
 from arkitekt_spec.declare.agents.hooks.registry import (
     ShutdownHook,
@@ -220,7 +226,13 @@ class BaseAgent(KoiledModel):
     connection_listener: ConnectionListener | None = Field(
         default=None,
         exclude=True,
-        description="Told when the backend acknowledges the agent and when the link drops (see arkitekt_runtime.agents.connection). Settable per run, like force; None reports to nobody.",
+        description="Told when the backend acknowledges the agent and when the link drops (see arkitekt_spec.declare.agents.connection). Settable per run, like force; None reports to nobody.",
+    )
+
+    task_listener: TaskListener | None = Field(
+        default=None,
+        exclude=True,
+        description="Told what happens to each task this agent runs: assigned (with its arguments), progress, yielded, done, failed, cancelled. Settable per run; None reports to nobody.",
     )
 
     contexts: dict[str, Any] = Field(
@@ -968,6 +980,14 @@ class BaseAgent(KoiledModel):
         # From here on the task can end, and after its end nothing more is recorded
         # for it: its reports and state changes enter this gate.
         self._task_gates[message.task] = TaskGate()
+        await self._anotify_task(
+            TaskEvent(
+                task_id=message.task,
+                action=message.interface,
+                kind=TaskEventKind.ASSIGNED,
+                arguments=dict(message.args),
+            )
+        )
         # ...and it is this process's: numbered by step (unless it is a probe).
         self._journal.begin_task(message.task)
         if message.resume is not None:
@@ -1206,6 +1226,41 @@ class BaseAgent(KoiledModel):
         except Exception:
             logger.warning("The connection listener failed on %s", state.value, exc_info=True)
 
+    def _task_event_of(self, message: messages.FromAgentMessage) -> TaskEvent | None:
+        """What a task's report means to a task listener; ``None`` for anything else."""
+        if isinstance(message, messages.Progress):
+            kind, details = TaskEventKind.PROGRESS, {
+                "progress": message.progress,
+                "message": message.message,
+            }
+        elif isinstance(message, messages.Yield):
+            kind, details = TaskEventKind.YIELDED, {}
+        elif isinstance(message, messages.Completed):
+            kind, details = TaskEventKind.DONE, {}
+        elif isinstance(message, (messages.Failed, messages.Critical)):
+            kind, details = TaskEventKind.FAILED, {"error": message.error}
+        elif isinstance(message, (messages.Cancelled, messages.Interrupted)):
+            kind, details = TaskEventKind.CANCELLED, {}
+        else:
+            return None
+        return TaskEvent(
+            task_id=message.task,
+            action=self._action_key_for(message) or message.task,
+            kind=kind,
+            **details,
+        )
+
+    async def _anotify_task(self, event: TaskEvent) -> None:
+        """Tell the task listener, if there is one."""
+        if self.task_listener is None:
+            return
+        try:
+            await self.task_listener(event)
+        except Exception:
+            logger.warning(
+                "The task listener failed on %s of %s", event.kind.value, event.task_id, exc_info=True
+            )
+
     def _start_disconnect_watchdog(self) -> None:
         """Begin counting down the grace periods of disconnect-sensitive actors."""
         if (
@@ -1400,6 +1455,10 @@ class BaseAgent(KoiledModel):
             )
         self._retain_emitted(message, entry)
         await self._adeliver(message, entry)
+        if self.task_listener is not None:
+            event = self._task_event_of(message)
+            if event is not None:
+                await self._anotify_task(event)
         if isinstance(message, messages.TERMINAL_REPORTS):
             # The task is done, so it is no longer running on any actor, and no
             # longer an assignment this agent is managing. Nothing used to pop

{arkitekt_runtime-4.2.0 → arkitekt_runtime-4.3.0}/arkitekt_runtime/state/observable.py

@@ -70,9 +70,6 @@ class StateConfig:
 
     state_name: str
     definition: StateDefinitionInput
-    publish_interval: float = (
-        0.1  # Optional: Minimum interval between patches to prevent flooding
-    )
     required_locks: list[str] = dataclasses.field(default_factory=list)
     publisher: StateHolder | None = dataclasses.field(default=None, compare=False)
     """Where patches go: the agent that adopted the state. None until then."""
@@ -91,7 +88,6 @@ class StateConfig:
         return cls(
             state_name=declaration.interface,
             definition=declaration.definition,
-            publish_interval=declaration.publish_interval,
             required_locks=list(declaration.required_locks),
         )
 

{arkitekt_runtime-4.2.0 → arkitekt_runtime-4.3.0}/arkitekt_runtime/structures/serialization/actor.py

@@ -660,6 +660,15 @@ async def _shrink_structure(
             "Port is structure but does not have identifier. Please report this to the developers.",
         )
     fstruc = ctx.registry.get_fullfilled_structure(port.identifier)
+    other = ctx.registry.declared_as_another(value, port.identifier)
+    if other is not None:
+        raise _shrink_error(
+            port,
+            value,
+            ctx,
+            f"A {type(value).__name__} ({other.identifier}) was returned where "
+            f"{port.identifier} is declared; its id would be sent as the wrong structure.",
+        )
     try:
         shrunk = await fstruc.shrink(value)
     except Exception as e:

{arkitekt_runtime-4.2.0 → arkitekt_runtime-4.3.0}/arkitekt_runtime/structures/serialization/shrink.py

@@ -166,6 +166,12 @@ async def _structure(
         # A bare string is taken as a reference to a global structure.
         return value
     fstruc = ctx.registry.get_fullfilled_structure(port.identifier)
+    other = ctx.registry.declared_as_another(value, port.identifier)
+    if other is not None:
+        raise StructureShrinkingError(
+            f"A {type(value).__name__} ({other.identifier}) was given where "
+            f"{port.identifier} is declared; its id would be sent as the wrong structure."
+        )
     try:
         shrunk = await fstruc.shrink(value)
     except Exception:

{arkitekt_runtime-4.2.0 → arkitekt_runtime-4.3.0}/arkitekt_runtime/task.py

@@ -29,7 +29,7 @@ import secrets
 import time
 from typing import TYPE_CHECKING, Any, ClassVar
 
-from koil import unkoil, unkoil_gen
+from koil import check_cancelled, unkoil, unkoil_gen
 
 from arkitekt_spec.actions import Execution
 from arkitekt_spec.declare.agents.errors import NoCallerError
@@ -141,6 +141,10 @@ class Task:
         """Pause here if the task was asked to."""
         unkoil(self.apausepoint)
 
+    def check_cancelled(self) -> None:
+        """Stop here if the task was cancelled: the cancellation point of a sync action."""
+        check_cancelled()
+
     # -- effects ---------------------------------------------------------- #
     # Values the task takes from outside itself, each recorded as an ``EFFECT`` under a
     # key. A resumed workflow gets the recorded value back instead of taking a new one.

{arkitekt_runtime-4.2.0 → arkitekt_runtime-4.3.0}/pyproject.toml

@@ -10,9 +10,9 @@ license = "MIT"
 # server) executes actions the same way, so this is what they share. It carries no
 # transport and no client: no websockets, no rath, no graphql-core.
 dependencies = [
-    "arkitekt-spec>=2.0.1",
+    "arkitekt-spec>=3.4",
     "pydantic>=2.11",
-    "koil>=3.3.3",
+    "koil>=3.3.6",
     "janus>=2.0.0",
     "jsonpatch>=1.33",
 ]

arkitekt_runtime-4.2.0/arkitekt_runtime/agents/connection.py

@@ -1,19 +0,0 @@
-"""What an agent tells whoever runs it about its connection to the backend."""
-
-from collections.abc import Awaitable, Callable
-from enum import Enum
-
-
-class ConnectionState(str, Enum):
-    """Where the agent's connection to the backend stands."""
-
-    REGISTERED = "registered"
-    """The backend acknowledged the agent's registration (an ``Init``). Reported on
-    the first connection and again whenever a dropped one is back."""
-    DISCONNECTED = "disconnected"
-    """The link dropped and the transport is trying to get it back."""
-
-
-ConnectionListener = Callable[[ConnectionState], Awaitable[None]]
-"""Called with each change of the agent's connection. It only reports: what it
-raises is logged and dropped, never the agent's problem."""