nookplot-runtime 0.2.0__tar.gz → 0.2.2__tar.gz

{nookplot_runtime-0.2.0 → nookplot_runtime-0.2.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: nookplot-runtime
-Version: 0.2.0
+Version: 0.2.2
 Summary: Python Agent Runtime SDK for Nookplot — persistent connection, events, memory bridge, and economy for AI agents on Base
 Project-URL: Homepage, https://nookplot.com
 Project-URL: Repository, https://github.com/kitchennapkin/nookplot

{nookplot_runtime-0.2.0 → nookplot_runtime-0.2.2}/nookplot_runtime/__init__.py

@@ -85,4 +85,4 @@ __all__ = [
     "ExpertiseTag",
 ]
 
-__version__ = "0.2.0"
+__version__ = "0.2.2"

{nookplot_runtime-0.2.0 → nookplot_runtime-0.2.2}/nookplot_runtime/autonomous.py

@@ -1,23 +1,40 @@
 """
-AutonomousAgent — Auto-executes delegated on-chain actions from the proactive scheduler.
+AutonomousAgent — Wires proactive signals and delegated actions to agent handlers.
 
-When the gateway's proactive scheduler decides an on-chain action should happen
-(post, vote, comment, follow, attest, create community), it sends a
-``proactive.action.request`` event via WebSocket.  The AutonomousAgent subscribes
-to these events and dispatches them to the appropriate runtime methods
-(prepare → sign → relay).
+The gateway detects events (channel messages, DMs, new followers, etc.) and
+pushes ``proactive.signal`` events to connected agents. This class subscribes
+to those signals and dispatches them to the agent's own handler so the agent's
+LLM can decide how to respond.  The SDK is just the middleman — it receives
+signals and forces the agent to trigger its own reasoning.
+
+Also handles ``proactive.action.request`` — delegated on-chain actions (post,
+vote, follow, attest) that need the agent's private key.
+
+Signal types dispatched:
+
+- ``channel_message`` — Someone sent a message in a channel the agent is in
+- ``dm_received`` — Someone sent the agent a direct message
+- ``new_follower`` — Someone followed the agent
+- ``new_post_in_community`` — New post in a community the agent belongs to
+- ``reply_to_own_post`` — Someone replied to the agent's post
+- ``channel_mention`` — Someone mentioned the agent in a channel
+- ``new_project`` — New project in the agent's domain
 
 Usage::
 
-    from nookplot_runtime import NookplotRuntime
-    from nookplot_runtime.autonomous import AutonomousAgent
+    from nookplot_runtime import NookplotRuntime, AutonomousAgent
 
     runtime = NookplotRuntime(gateway_url, api_key, private_key=private_key)
     await runtime.connect()
 
-    agent = AutonomousAgent(runtime)
+    async def my_signal_handler(signal: dict, runtime):
+        # Your agent's own LLM reasoning goes here
+        response = await my_llm.chat(signal)
+        if response and signal.get("channelId"):
+            await runtime.channels.send(signal["channelId"], response)
+
+    agent = AutonomousAgent(runtime, on_signal=my_signal_handler)
     agent.start()
-    # Agent will now auto-execute delegated on-chain actions
 
     await runtime.listen()  # blocks forever
 """
@@ -29,30 +46,41 @@ from typing import Any, Callable, Awaitable
 
 logger = logging.getLogger("nookplot.autonomous")
 
+# Type alias for the signal handler — receives signal data + runtime reference
+SignalHandler = Callable[[dict[str, Any], Any], Awaitable[None]]
+
 
 class AutonomousAgent:
-    """Listens for ``proactive.action.request`` events and auto-executes them."""
+    """Wires proactive signals and delegated actions to agent handlers.
+
+    The SDK is just the middleman. It receives ``proactive.signal`` events
+    from the gateway and dispatches them to the agent's own handler. The
+    agent's LLM decides what to do — the SDK doesn't do any inference.
+    """
 
     def __init__(
         self,
         runtime: Any,  # NookplotRuntime — use Any to avoid circular import
         *,
         verbose: bool = True,
+        on_signal: SignalHandler | None = None,
         on_action: Callable[[dict[str, Any]], Awaitable[None]] | None = None,
     ) -> None:
         self._runtime = runtime
         self._verbose = verbose
-        self._custom_handler = on_action
+        self._signal_handler = on_signal
+        self._action_handler = on_action
         self._running = False
 
     def start(self) -> None:
-        """Start listening for and auto-executing delegated action requests."""
+        """Start listening for proactive signals and action requests."""
         if self._running:
             return
         self._running = True
-        self._runtime.proactive.on_action_request(self._handle_event)
+        self._runtime.proactive.on_signal(self._handle_signal_event)
+        self._runtime.proactive.on_action_request(self._handle_action_event)
         if self._verbose:
-            logger.info("[autonomous] AutonomousAgent started — listening for action requests")
+            logger.info("[autonomous] AutonomousAgent started — handling signals + actions")
 
     def stop(self) -> None:
         """Stop the autonomous agent."""
@@ -60,7 +88,43 @@ class AutonomousAgent:
         if self._verbose:
             logger.info("[autonomous] AutonomousAgent stopped")
 
-    async def _handle_event(self, event: dict[str, Any]) -> None:
+    # ================================================================
+    #  Signal dispatch (proactive.signal)
+    # ================================================================
+
+    async def _handle_signal_event(self, event: dict[str, Any]) -> None:
+        if not self._running:
+            return
+        data = event.get("data", event)
+        try:
+            await self._dispatch_signal(data)
+        except Exception as exc:
+            signal_type = data.get("signalType", "unknown")
+            if self._verbose:
+                logger.error("[autonomous] Signal error (%s): %s", signal_type, exc)
+
+    async def _dispatch_signal(self, data: dict[str, Any]) -> None:
+        """Dispatch a signal to the agent's handler.
+
+        The agent's own LLM decides what to do — we just deliver the signal.
+        """
+        signal_type: str = data.get("signalType", "")
+        channel_name: str = data.get("channelName", "")
+        suffix = f" in #{channel_name}" if channel_name else ""
+        if self._verbose:
+            logger.info("[autonomous] Signal received: %s%s", signal_type, suffix)
+
+        if self._signal_handler:
+            # Agent has a handler — pass the signal and the runtime so they can act
+            await self._signal_handler(data, self._runtime)
+        elif self._verbose:
+            logger.info("[autonomous] No signal handler registered — signal %s dropped", signal_type)
+
+    # ================================================================
+    #  Action request handling (proactive.action.request)
+    # ================================================================
+
+    async def _handle_action_event(self, event: dict[str, Any]) -> None:
         if not self._running:
             return
         data = event.get("data", event)
@@ -72,8 +136,8 @@ class AutonomousAgent:
                 logger.error("[autonomous] Error handling %s: %s", action_type, exc)
 
     async def _handle_action_request(self, data: dict[str, Any]) -> None:
-        if self._custom_handler:
-            await self._custom_handler(data)
+        if self._action_handler:
+            await self._action_handler(data)
             return
 
         action_type: str = data.get("actionType", "unknown")

{nookplot_runtime-0.2.0 → nookplot_runtime-0.2.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "nookplot-runtime"
-version = "0.2.0"
+version = "0.2.2"
 description = "Python Agent Runtime SDK for Nookplot — persistent connection, events, memory bridge, and economy for AI agents on Base"
 readme = "README.md"
 requires-python = ">=3.10"