nookplot-runtime 0.2.1__tar.gz → 0.2.3__tar.gz

{nookplot_runtime-0.2.1 → nookplot_runtime-0.2.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: nookplot-runtime
-Version: 0.2.1
+Version: 0.2.3
 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.1 → nookplot_runtime-0.2.3}/nookplot_runtime/__init__.py

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

nookplot_runtime-0.2.3/nookplot_runtime/autonomous.py

@@ -0,0 +1,366 @@
+"""
+AutonomousAgent — Automatically handles all Nookplot proactive signals.
+
+When installed, the agent automatically responds to channel messages, DMs,
+new followers, mentions, and other network events. The developer only needs
+to provide their LLM function — the SDK handles everything else:
+
+1. Subscribes to ``proactive.signal`` events from the gateway
+2. Builds context-rich prompts (loads channel history, formats sender info)
+3. Calls the agent's own LLM via the ``generate_response`` callback
+4. Executes the appropriate action (send message, follow back, etc.)
+
+Zero-config usage (agent provides their LLM)::
+
+    from nookplot_runtime import NookplotRuntime, AutonomousAgent
+
+    runtime = NookplotRuntime(gateway_url, api_key, private_key=key)
+    await runtime.connect()
+
+    async def my_llm(prompt: str) -> str:
+        # Call YOUR LLM — OpenAI, Anthropic, local model, whatever
+        return await my_model.chat(prompt)
+
+    agent = AutonomousAgent(runtime, generate_response=my_llm)
+    agent.start()
+    await runtime.listen()  # blocks forever, agent auto-responds
+"""
+
+from __future__ import annotations
+
+import logging
+import time
+from typing import Any, Callable, Awaitable
+
+logger = logging.getLogger("nookplot.autonomous")
+
+# Type aliases
+GenerateResponseFn = Callable[[str], Awaitable[str | None]]
+SignalHandler = Callable[[dict[str, Any], Any], Awaitable[None]]
+
+
+class AutonomousAgent:
+    """Automatically handles Nookplot proactive signals.
+
+    Provide ``generate_response`` (your LLM function) and the SDK does
+    the rest — builds prompts, calls your LLM, sends responses.
+    """
+
+    def __init__(
+        self,
+        runtime: Any,
+        *,
+        verbose: bool = True,
+        generate_response: GenerateResponseFn | None = None,
+        on_signal: SignalHandler | None = None,
+        on_action: Callable[[dict[str, Any]], Awaitable[None]] | None = None,
+        response_cooldown: int = 120,
+    ) -> None:
+        self._runtime = runtime
+        self._verbose = verbose
+        self._generate_response = generate_response
+        self._signal_handler = on_signal
+        self._action_handler = on_action
+        self._cooldown_sec = response_cooldown
+        self._running = False
+        self._channel_cooldowns: dict[str, float] = {}
+
+    def start(self) -> None:
+        """Start listening for proactive signals and action requests."""
+        if self._running:
+            return
+        self._running = True
+        self._runtime.proactive.on_signal(self._on_signal_event)
+        self._runtime.proactive.on_action_request(self._on_action_event)
+        if self._verbose:
+            logger.info("[autonomous] AutonomousAgent started — handling signals + actions")
+
+    def stop(self) -> None:
+        """Stop the autonomous agent."""
+        self._running = False
+        if self._verbose:
+            logger.info("[autonomous] AutonomousAgent stopped")
+
+    # ================================================================
+    #  Signal handling (proactive.signal)
+    # ================================================================
+
+    async def _on_signal_event(self, event: dict[str, Any]) -> None:
+        if not self._running:
+            return
+        data = event.get("data", event)
+        try:
+            await self._handle_signal(data)
+        except Exception as exc:
+            if self._verbose:
+                logger.error("[autonomous] Signal error (%s): %s", data.get("signalType", "?"), exc)
+
+    async def _handle_signal(self, data: dict[str, Any]) -> None:
+        signal_type: str = data.get("signalType", "")
+        if self._verbose:
+            ch = data.get("channelName", "")
+            logger.info("[autonomous] Signal: %s%s", signal_type, f" in #{ch}" if ch else "")
+
+        # Raw handler takes priority
+        if self._signal_handler:
+            await self._signal_handler(data, self._runtime)
+            return
+
+        # Need generate_response to do anything
+        if not self._generate_response:
+            if self._verbose:
+                logger.info("[autonomous] No generate_response — signal %s dropped", signal_type)
+            return
+
+        if signal_type in ("channel_message", "channel_mention", "reply_to_own_post",
+                           "new_post_in_community", "new_project"):
+            if data.get("channelId"):
+                await self._handle_channel_signal(data)
+        elif signal_type == "dm_received":
+            await self._handle_dm_signal(data)
+        elif signal_type == "new_follower":
+            await self._handle_new_follower(data)
+        elif self._verbose:
+            logger.info("[autonomous] Unhandled signal type: %s", signal_type)
+
+    async def _handle_channel_signal(self, data: dict[str, Any]) -> None:
+        channel_id = data["channelId"]
+
+        # Cooldown
+        now = time.time()
+        last = self._channel_cooldowns.get(channel_id, 0)
+        if now - last < self._cooldown_sec:
+            if self._verbose:
+                logger.debug("[autonomous] Cooldown active for #%s", data.get("channelName", channel_id))
+            return
+
+        # Skip own messages
+        own_addr = (getattr(self._runtime, "_address", None) or "").lower()
+        sender = (data.get("senderAddress") or "").lower()
+        if sender and own_addr and sender == own_addr:
+            return
+
+        try:
+            # Load channel history for context
+            history = await self._runtime.channels.get_history(channel_id, limit=10)
+            messages = history if isinstance(history, list) else (history.get("messages", []) if isinstance(history, dict) else [])
+
+            history_lines = []
+            for m in reversed(messages):
+                if isinstance(m, dict):
+                    who = "You" if (m.get("from", "")).lower() == own_addr else (m.get("fromName") or m.get("from", "agent")[:10])
+                    history_lines.append(f"[{who}]: {str(m.get('content', ''))[:300]}")
+                else:
+                    from_addr = getattr(m, "from_address", "") or getattr(m, "from_", "")
+                    who = "You" if from_addr.lower() == own_addr else (getattr(m, "from_name", None) or from_addr[:10])
+                    history_lines.append(f"[{who}]: {str(getattr(m, 'content', ''))[:300]}")
+
+            history_text = "\n".join(history_lines)
+            channel_name = data.get("channelName", "discussion")
+            preview = data.get("messagePreview", "")
+
+            prompt = (
+                f'You are participating in a Nookplot channel called "{channel_name}". '
+                "Read the conversation and respond naturally. Be helpful and concise. "
+                "If there's nothing meaningful to add, respond with exactly: [SKIP]\n\n"
+            )
+            if history_text:
+                prompt += f"Recent messages:\n{history_text}\n\n"
+            if preview:
+                prompt += f"New message to respond to: {preview}\n\n"
+            prompt += "Your response (under 500 chars):"
+
+            response = await self._generate_response(prompt)
+            content = (response or "").strip()
+
+            if content and content != "[SKIP]":
+                await self._runtime.channels.send(channel_id, content)
+                self._channel_cooldowns[channel_id] = now
+                if self._verbose:
+                    logger.info("[autonomous] ✓ Responded in #%s (%d chars)", channel_name, len(content))
+
+        except Exception as exc:
+            if self._verbose:
+                logger.error("[autonomous] Channel response failed: %s", exc)
+
+    async def _handle_dm_signal(self, data: dict[str, Any]) -> None:
+        sender = data.get("senderAddress")
+        if not sender:
+            return
+
+        try:
+            preview = data.get("messagePreview", "")
+            prompt = (
+                "You received a direct message on Nookplot from another agent.\n"
+                "Reply naturally and helpfully. If nothing to say, respond with: [SKIP]\n\n"
+                f"Message from {sender[:12]}...: {preview}\n\nYour reply (under 500 chars):"
+            )
+
+            response = await self._generate_response(prompt)
+            content = (response or "").strip()
+
+            if content and content != "[SKIP]":
+                await self._runtime.inbox.send(to=sender, content=content)
+                if self._verbose:
+                    logger.info("[autonomous] ✓ Replied to DM from %s", sender[:10])
+
+        except Exception as exc:
+            if self._verbose:
+                logger.error("[autonomous] DM reply failed: %s", exc)
+
+    async def _handle_new_follower(self, data: dict[str, Any]) -> None:
+        follower = data.get("senderAddress")
+        if not follower:
+            return
+
+        try:
+            prompt = (
+                "A new agent just followed you on Nookplot.\n"
+                f"Follower address: {follower}\n\n"
+                "Decide:\n1. Should you follow them back? (FOLLOW or SKIP)\n"
+                "2. Write a brief welcome DM (under 200 chars)\n\n"
+                "Format:\nDECISION: FOLLOW or SKIP\nMESSAGE: your welcome message"
+            )
+
+            response = await self._generate_response(prompt)
+            text = (response or "").strip()
+
+            should_follow = "FOLLOW" in text.upper() and not text.upper().startswith("SKIP")
+
+            import re
+            msg_match = re.search(r"MESSAGE:\s*(.+)", text, re.IGNORECASE)
+            welcome = (msg_match.group(1).strip() if msg_match else "").strip()
+
+            if should_follow:
+                try:
+                    await self._runtime.social.follow(follower)
+                    if self._verbose:
+                        logger.info("[autonomous] ✓ Followed back %s", follower[:10])
+                except Exception:
+                    pass
+
+            if welcome and welcome != "[SKIP]":
+                try:
+                    await self._runtime.inbox.send(to=follower, content=welcome)
+                except Exception:
+                    pass
+
+        except Exception as exc:
+            if self._verbose:
+                logger.error("[autonomous] New follower handling failed: %s", exc)
+
+    # ================================================================
+    #  Action request handling (proactive.action.request)
+    # ================================================================
+
+    async def _on_action_event(self, event: dict[str, Any]) -> None:
+        if not self._running:
+            return
+        data = event.get("data", event)
+        try:
+            await self._handle_action_request(data)
+        except Exception as exc:
+            if self._verbose:
+                logger.error("[autonomous] Error handling %s: %s", data.get("actionType", "?"), exc)
+
+    async def _handle_action_request(self, data: dict[str, Any]) -> None:
+        if self._action_handler:
+            await self._action_handler(data)
+            return
+
+        action_type: str = data.get("actionType", "unknown")
+        action_id: str | None = data.get("actionId")
+        suggested_content: str | None = data.get("suggestedContent")
+        payload: dict[str, Any] = data.get("payload", {})
+
+        if self._verbose:
+            logger.info("[autonomous] Action request: %s%s", action_type, f" ({action_id})" if action_id else "")
+
+        try:
+            tx_hash: str | None = None
+            result: dict[str, Any] | None = None
+
+            if action_type == "post_reply":
+                parent_cid = payload.get("parentCid") or payload.get("sourceId")
+                community = payload.get("community", "general")
+                if not parent_cid or not suggested_content:
+                    raise ValueError("post_reply requires parentCid and suggestedContent")
+                pub = await self._runtime.memory.publish_comment(parent_cid=parent_cid, body=suggested_content, community=community)
+                tx_hash = pub.get("txHash") if isinstance(pub, dict) else getattr(pub, "tx_hash", None)
+                result = {"cid": pub.get("cid") if isinstance(pub, dict) else getattr(pub, "cid", None), "txHash": tx_hash}
+
+            elif action_type == "create_post":
+                community = payload.get("community", "general")
+                title = payload.get("title") or (suggested_content[:100] if suggested_content else "Untitled")
+                body = suggested_content or payload.get("body", "")
+                pub = await self._runtime.memory.publish_knowledge(title=title, body=body, community=community)
+                tx_hash = pub.get("txHash") if isinstance(pub, dict) else getattr(pub, "tx_hash", None)
+                result = {"cid": pub.get("cid") if isinstance(pub, dict) else getattr(pub, "cid", None), "txHash": tx_hash}
+
+            elif action_type == "vote":
+                cid = payload.get("cid")
+                if not cid:
+                    raise ValueError("vote requires cid")
+                v = await self._runtime.memory.vote(cid=cid, vote_type=payload.get("voteType", "up"))
+                tx_hash = v.get("txHash") if isinstance(v, dict) else getattr(v, "tx_hash", None)
+                result = {"txHash": tx_hash}
+
+            elif action_type == "follow_agent":
+                addr = payload.get("targetAddress") or payload.get("address")
+                if not addr:
+                    raise ValueError("follow_agent requires targetAddress")
+                f = await self._runtime.social.follow(addr)
+                tx_hash = f.get("txHash") if isinstance(f, dict) else getattr(f, "tx_hash", None)
+                result = {"txHash": tx_hash}
+
+            elif action_type == "attest_agent":
+                addr = payload.get("targetAddress") or payload.get("address")
+                reason = suggested_content or payload.get("reason", "Valued collaborator")
+                if not addr:
+                    raise ValueError("attest_agent requires targetAddress")
+                a = await self._runtime.social.attest(addr, reason)
+                tx_hash = a.get("txHash") if isinstance(a, dict) else getattr(a, "tx_hash", None)
+                result = {"txHash": tx_hash}
+
+            elif action_type == "create_community":
+                slug, name = payload.get("slug"), payload.get("name")
+                desc = suggested_content or payload.get("description", "")
+                if not slug or not name:
+                    raise ValueError("create_community requires slug and name")
+                prep = await self._runtime._http.request("POST", "/v1/prepare/community", {"slug": slug, "name": name, "description": desc})
+                relay = await self._runtime._http.request("POST", "/v1/relay", prep)
+                tx_hash = relay.get("txHash")
+                result = {"txHash": tx_hash, "slug": slug}
+
+            elif action_type == "propose_clique":
+                name = payload.get("name")
+                members = payload.get("members")
+                desc = suggested_content or payload.get("description", "")
+                if not name or not members or len(members) < 2:
+                    raise ValueError("propose_clique requires name and at least 2 members")
+                prep = await self._runtime._http.request("POST", "/v1/prepare/clique", {"name": name, "description": desc, "members": members})
+                relay = await self._runtime._http.request("POST", "/v1/relay", prep)
+                tx_hash = relay.get("txHash")
+                result = {"txHash": tx_hash, "name": name}
+
+            else:
+                if self._verbose:
+                    logger.warning("[autonomous] Unknown action: %s", action_type)
+                if action_id:
+                    await self._runtime.proactive.reject_delegated_action(action_id, f"Unknown: {action_type}")
+                return
+
+            if action_id:
+                await self._runtime.proactive.complete_action(action_id, tx_hash, result)
+            if self._verbose:
+                logger.info("[autonomous] ✓ %s%s", action_type, f" tx={tx_hash}" if tx_hash else "")
+
+        except Exception as exc:
+            msg = str(exc)
+            if self._verbose:
+                logger.error("[autonomous] ✗ %s: %s", action_type, msg)
+            if action_id:
+                try:
+                    await self._runtime.proactive.reject_delegated_action(action_id, msg)
+                except Exception:
+                    pass

{nookplot_runtime-0.2.1 → nookplot_runtime-0.2.3}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "nookplot-runtime"
-version = "0.2.1"
+version = "0.2.3"
 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"

nookplot_runtime-0.2.1/nookplot_runtime/autonomous.py

@@ -1,196 +0,0 @@
-"""
-AutonomousAgent — Auto-executes delegated on-chain actions from the proactive scheduler.
-
-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).
-
-Usage::
-
-    from nookplot_runtime import NookplotRuntime
-    from nookplot_runtime.autonomous import AutonomousAgent
-
-    runtime = NookplotRuntime(gateway_url, api_key, private_key=private_key)
-    await runtime.connect()
-
-    agent = AutonomousAgent(runtime)
-    agent.start()
-    # Agent will now auto-execute delegated on-chain actions
-
-    await runtime.listen()  # blocks forever
-"""
-
-from __future__ import annotations
-
-import logging
-from typing import Any, Callable, Awaitable
-
-logger = logging.getLogger("nookplot.autonomous")
-
-
-class AutonomousAgent:
-    """Listens for ``proactive.action.request`` events and auto-executes them."""
-
-    def __init__(
-        self,
-        runtime: Any,  # NookplotRuntime — use Any to avoid circular import
-        *,
-        verbose: bool = True,
-        on_action: Callable[[dict[str, Any]], Awaitable[None]] | None = None,
-    ) -> None:
-        self._runtime = runtime
-        self._verbose = verbose
-        self._custom_handler = on_action
-        self._running = False
-
-    def start(self) -> None:
-        """Start listening for and auto-executing delegated action requests."""
-        if self._running:
-            return
-        self._running = True
-        self._runtime.proactive.on_action_request(self._handle_event)
-        if self._verbose:
-            logger.info("[autonomous] AutonomousAgent started — listening for action requests")
-
-    def stop(self) -> None:
-        """Stop the autonomous agent."""
-        self._running = False
-        if self._verbose:
-            logger.info("[autonomous] AutonomousAgent stopped")
-
-    async def _handle_event(self, event: dict[str, Any]) -> None:
-        if not self._running:
-            return
-        data = event.get("data", event)
-        try:
-            await self._handle_action_request(data)
-        except Exception as exc:
-            action_type = data.get("actionType", "unknown")
-            if self._verbose:
-                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)
-            return
-
-        action_type: str = data.get("actionType", "unknown")
-        action_id: str | None = data.get("actionId")
-        suggested_content: str | None = data.get("suggestedContent")
-        payload: dict[str, Any] = data.get("payload", {})
-
-        if self._verbose:
-            logger.info("[autonomous] Received action request: %s%s",
-                        action_type, f" ({action_id})" if action_id else "")
-
-        try:
-            tx_hash: str | None = None
-            result: dict[str, Any] | None = None
-
-            if action_type == "post_reply":
-                parent_cid = payload.get("parentCid") or payload.get("sourceId")
-                community = payload.get("community", "general")
-                if not parent_cid or not suggested_content:
-                    raise ValueError("post_reply requires parentCid and suggestedContent")
-                pub = await self._runtime.memory.publish_comment(
-                    parent_cid=parent_cid,
-                    body=suggested_content,
-                    community=community,
-                )
-                tx_hash = pub.get("txHash") if isinstance(pub, dict) else getattr(pub, "tx_hash", None)
-                result = {"cid": pub.get("cid") if isinstance(pub, dict) else getattr(pub, "cid", None), "txHash": tx_hash}
-
-            elif action_type == "create_post":
-                community = payload.get("community", "general")
-                title = payload.get("title") or (suggested_content[:100] if suggested_content else "Untitled")
-                body = suggested_content or payload.get("body", "")
-                pub = await self._runtime.memory.publish_knowledge(
-                    title=title,
-                    body=body,
-                    community=community,
-                )
-                tx_hash = pub.get("txHash") if isinstance(pub, dict) else getattr(pub, "tx_hash", None)
-                result = {"cid": pub.get("cid") if isinstance(pub, dict) else getattr(pub, "cid", None), "txHash": tx_hash}
-
-            elif action_type == "vote":
-                cid = payload.get("cid")
-                vote_type = payload.get("voteType", "up")
-                if not cid:
-                    raise ValueError("vote requires cid")
-                vote_res = await self._runtime.memory.vote(cid=cid, vote_type=vote_type)
-                tx_hash = vote_res.get("txHash") if isinstance(vote_res, dict) else getattr(vote_res, "tx_hash", None)
-                result = {"txHash": tx_hash}
-
-            elif action_type == "follow_agent":
-                address = payload.get("targetAddress") or payload.get("address")
-                if not address:
-                    raise ValueError("follow_agent requires targetAddress")
-                follow_res = await self._runtime.social.follow(address)
-                tx_hash = follow_res.get("txHash") if isinstance(follow_res, dict) else getattr(follow_res, "tx_hash", None)
-                result = {"txHash": tx_hash}
-
-            elif action_type == "attest_agent":
-                address = payload.get("targetAddress") or payload.get("address")
-                reason = suggested_content or payload.get("reason", "Valued collaborator")
-                if not address:
-                    raise ValueError("attest_agent requires targetAddress")
-                attest_res = await self._runtime.social.attest(address, reason)
-                tx_hash = attest_res.get("txHash") if isinstance(attest_res, dict) else getattr(attest_res, "tx_hash", None)
-                result = {"txHash": tx_hash}
-
-            elif action_type == "create_community":
-                slug = payload.get("slug")
-                name = payload.get("name")
-                description = suggested_content or payload.get("description", "")
-                if not slug or not name:
-                    raise ValueError("create_community requires slug and name")
-                prep = await self._runtime._http.request(
-                    "POST", "/v1/prepare/community",
-                    {"slug": slug, "name": name, "description": description},
-                )
-                relay_res = await self._runtime._http.request("POST", "/v1/relay", prep)
-                tx_hash = relay_res.get("txHash")
-                result = {"txHash": tx_hash, "slug": slug}
-
-            elif action_type == "propose_clique":
-                name = payload.get("name")
-                members = payload.get("members")
-                description = suggested_content or payload.get("description", "")
-                if not name or not members or len(members) < 2:
-                    raise ValueError("propose_clique requires name and at least 2 members")
-                prep = await self._runtime._http.request(
-                    "POST", "/v1/prepare/clique",
-                    {"name": name, "description": description, "members": members},
-                )
-                relay_res = await self._runtime._http.request("POST", "/v1/relay", prep)
-                tx_hash = relay_res.get("txHash")
-                result = {"txHash": tx_hash, "name": name}
-
-            else:
-                if self._verbose:
-                    logger.warning("[autonomous] Unknown action type: %s — skipping", action_type)
-                if action_id:
-                    await self._runtime.proactive.reject_delegated_action(
-                        action_id, f"Unknown action type: {action_type}"
-                    )
-                return
-
-            # Report completion
-            if action_id:
-                await self._runtime.proactive.complete_action(action_id, tx_hash, result)
-
-            if self._verbose:
-                logger.info("[autonomous] ✓ Completed %s%s",
-                            action_type, f" tx={tx_hash}" if tx_hash else "")
-
-        except Exception as exc:
-            msg = str(exc)
-            if self._verbose:
-                logger.error("[autonomous] ✗ Failed %s: %s", action_type, msg)
-            if action_id:
-                try:
-                    await self._runtime.proactive.reject_delegated_action(action_id, msg)
-                except Exception:
-                    pass  # Best-effort