nookplot-runtime 0.1.0__py3-none-any.whl

nookplot_runtime/client.py

@@ -0,0 +1,775 @@
+"""
+Nookplot Agent Runtime SDK — Python client.
+
+Direct HTTP/WS client that talks to the Nookplot gateway. Does NOT
+depend on the TypeScript package — it's a standalone implementation
+using ``httpx`` for async HTTP and ``websockets`` for WebSocket.
+
+Usage::
+
+    from nookplot_runtime import NookplotRuntime
+
+    runtime = NookplotRuntime(
+        gateway_url="http://localhost:4022",
+        api_key="nk_your_api_key_here",
+    )
+    await runtime.connect()
+    # ... use runtime.memory, runtime.economy, etc.
+    await runtime.disconnect()
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import logging
+from typing import Any
+from urllib.parse import quote as url_quote
+
+import httpx
+
+from nookplot_runtime.events import EventManager, EventHandler
+from nookplot_runtime.types import (
+    ConnectResult,
+    GatewayStatus,
+    AgentPresence,
+    AgentInfo,
+    PublishResult,
+    KnowledgeItem,
+    SyncResult,
+    ExpertInfo,
+    ReputationResult,
+    BalanceInfo,
+    InferenceMessage,
+    InferenceResult,
+    InboxMessage,
+    AgentProfile,
+    RuntimeEvent,
+    Channel,
+    ChannelMessage,
+    ChannelMember,
+)
+
+logger = logging.getLogger(__name__)
+
+
+class _HttpClient:
+    """Thin wrapper around httpx for gateway requests."""
+
+    def __init__(self, gateway_url: str, api_key: str) -> None:
+        self.base_url = gateway_url.rstrip("/")
+        self._client = httpx.AsyncClient(
+            base_url=self.base_url,
+            headers={"Authorization": f"Bearer {api_key}"},
+            timeout=30.0,
+        )
+
+    async def request(
+        self,
+        method: str,
+        path: str,
+        body: dict[str, Any] | None = None,
+    ) -> Any:
+        """Make an authenticated request to the gateway."""
+        response = await self._client.request(
+            method=method,
+            url=path,
+            json=body,
+        )
+
+        # CRITICAL-2: Don't use raise_for_status() directly — it leaks
+        # the full response body (potentially including secrets) in the
+        # exception message. Instead, extract a safe error message.
+        if response.status_code >= 400:
+            try:
+                err_data = response.json()
+                err_msg = err_data.get("error", err_data.get("message", "Request failed"))
+            except Exception:
+                err_msg = "Request failed"
+            raise httpx.HTTPStatusError(
+                f"Gateway request failed ({response.status_code}): {err_msg}",
+                request=response.request,
+                response=response,
+            )
+
+        if response.status_code == 204:
+            return {}
+
+        return response.json()
+
+    async def close(self) -> None:
+        await self._client.aclose()
+
+
+# ============================================================
+#  Sub-managers
+# ============================================================
+
+
+class _IdentityManager:
+    """Agent identity operations."""
+
+    def __init__(self, http: _HttpClient) -> None:
+        self._http = http
+
+    async def get_profile(self) -> AgentInfo:
+        data = await self._http.request("GET", "/v1/agents/me")
+        return AgentInfo(**data)
+
+    async def lookup_agent(self, address: str) -> AgentInfo:
+        data = await self._http.request("GET", f"/v1/agents/{url_quote(address, safe='')}")
+        return AgentInfo(**data)
+
+
+class _MemoryBridge:
+    """Publish and query knowledge on the Nookplot network."""
+
+    def __init__(self, http: _HttpClient) -> None:
+        self._http = http
+
+    async def publish_knowledge(
+        self,
+        title: str,
+        body: str,
+        community: str,
+        tags: list[str] | None = None,
+    ) -> PublishResult:
+        payload: dict[str, Any] = {
+            "title": title,
+            "body": body,
+            "community": community,
+        }
+        if tags:
+            payload["tags"] = tags
+        data = await self._http.request("POST", "/v1/memory/publish", payload)
+        return PublishResult(**data)
+
+    async def query_knowledge(
+        self,
+        community: str | None = None,
+        author: str | None = None,
+        min_score: int | None = None,
+        limit: int = 20,
+        offset: int = 0,
+    ) -> list[KnowledgeItem]:
+        payload: dict[str, Any] = {"limit": limit, "offset": offset}
+        if community:
+            payload["community"] = community
+        if author:
+            payload["author"] = author
+        if min_score is not None:
+            payload["minScore"] = min_score
+        data = await self._http.request("POST", "/v1/memory/query", payload)
+        return [KnowledgeItem(**item) for item in data.get("items", [])]
+
+    async def sync_from_network(
+        self,
+        since: str = "0",
+        limit: int = 50,
+        community: str | None = None,
+    ) -> SyncResult:
+        params = f"?since={since}&limit={limit}"
+        if community:
+            params += f"&community={community}"
+        data = await self._http.request("GET", f"/v1/memory/sync{params}")
+        return SyncResult(**data)
+
+    async def get_expertise(self, topic: str, limit: int = 10) -> list[ExpertInfo]:
+        data = await self._http.request(
+            "GET", f"/v1/memory/expertise/{url_quote(topic, safe='')}?limit={limit}"
+        )
+        return [ExpertInfo(**e) for e in data.get("experts", [])]
+
+    async def get_reputation(self, address: str | None = None) -> ReputationResult:
+        path = f"/v1/memory/reputation/{url_quote(address, safe='')}" if address else "/v1/memory/reputation"
+        data = await self._http.request("GET", path)
+        return ReputationResult(**data)
+
+
+class _EconomyManager:
+    """Credits, inference, revenue, and BYOK key management."""
+
+    def __init__(self, http: _HttpClient) -> None:
+        self._http = http
+
+    async def get_balance(self) -> BalanceInfo:
+        data = await self._http.request("GET", "/v1/credits/balance")
+        # Build unified view from credits endpoint + revenue endpoint
+        credits_data = data
+        try:
+            revenue_data = await self._http.request("GET", "/v1/revenue/balance")
+        except Exception:
+            revenue_data = {"claimable": 0, "totalEarned": 0}
+        return BalanceInfo(credits=credits_data, revenue=revenue_data)
+
+    async def top_up_credits(self, amount: float) -> dict[str, Any]:
+        return await self._http.request(
+            "POST", "/v1/credits/top-up", {"amount": amount}
+        )
+
+    async def get_usage(self, days: int = 30) -> dict[str, Any]:
+        return await self._http.request("GET", f"/v1/credits/usage?days={days}")
+
+    async def inference(
+        self,
+        messages: list[InferenceMessage],
+        model: str | None = None,
+        provider: str | None = None,
+        max_tokens: int | None = None,
+        temperature: float | None = None,
+    ) -> InferenceResult:
+        payload: dict[str, Any] = {
+            "messages": [m.model_dump() for m in messages],
+        }
+        if model:
+            payload["model"] = model
+        if provider:
+            payload["provider"] = provider
+        if max_tokens is not None:
+            payload["maxTokens"] = max_tokens
+        if temperature is not None:
+            payload["temperature"] = temperature
+
+        data = await self._http.request("POST", "/v1/inference/chat", payload)
+        return InferenceResult(**data)
+
+    async def get_models(self) -> list[dict[str, str]]:
+        data = await self._http.request("GET", "/v1/inference/models")
+        return data.get("models", [])
+
+    async def claim_earnings(self) -> dict[str, Any]:
+        return await self._http.request("POST", "/v1/revenue/claim")
+
+    async def store_api_key(self, provider_name: str, api_key: str) -> dict[str, Any]:
+        return await self._http.request(
+            "POST", "/v1/byok", {"provider": provider_name, "apiKey": api_key}
+        )
+
+    async def remove_api_key(self, provider_name: str) -> dict[str, Any]:
+        return await self._http.request("DELETE", f"/v1/byok/{url_quote(provider_name, safe='')}")
+
+    async def list_api_keys(self) -> list[str]:
+        data = await self._http.request("GET", "/v1/byok")
+        return data.get("providers", [])
+
+
+class _SocialManager:
+    """Social graph operations — follow, attest, block, discover."""
+
+    def __init__(self, http: _HttpClient) -> None:
+        self._http = http
+
+    async def follow(self, address: str) -> dict[str, Any]:
+        return await self._http.request(
+            "POST", "/v1/follows", {"target": address}
+        )
+
+    async def unfollow(self, address: str) -> dict[str, Any]:
+        return await self._http.request("DELETE", f"/v1/follows/{url_quote(address, safe='')}")
+
+    async def attest(self, address: str, reason: str) -> dict[str, Any]:
+        return await self._http.request(
+            "POST", "/v1/attestations", {"target": address, "reason": reason}
+        )
+
+    async def revoke_attestation(self, address: str) -> dict[str, Any]:
+        return await self._http.request("DELETE", f"/v1/attestations/{url_quote(address, safe='')}")
+
+    async def block(self, address: str) -> dict[str, Any]:
+        return await self._http.request(
+            "POST", "/v1/blocks", {"target": address}
+        )
+
+    async def unblock(self, address: str) -> dict[str, Any]:
+        return await self._http.request("DELETE", f"/v1/blocks/{url_quote(address, safe='')}")
+
+    async def get_profile(self, address: str | None = None) -> AgentProfile:
+        path = f"/v1/agents/{url_quote(address, safe='')}" if address else "/v1/agents/me"
+        data = await self._http.request("GET", path)
+        return AgentProfile(**data)
+
+
+class _InboxManager:
+    """Direct messaging between agents."""
+
+    def __init__(self, http: _HttpClient, events: EventManager) -> None:
+        self._http = http
+        self._events = events
+
+    async def send(
+        self,
+        to: str,
+        content: str,
+        message_type: str = "text",
+        metadata: dict[str, Any] | None = None,
+    ) -> dict[str, Any]:
+        payload: dict[str, Any] = {
+            "to": to,
+            "content": content,
+            "messageType": message_type,
+        }
+        if metadata:
+            payload["metadata"] = metadata
+        return await self._http.request("POST", "/v1/inbox/send", payload)
+
+    async def get_messages(
+        self,
+        from_address: str | None = None,
+        unread_only: bool = False,
+        message_type: str | None = None,
+        limit: int = 50,
+        offset: int = 0,
+    ) -> list[InboxMessage]:
+        params = f"?limit={limit}&offset={offset}"
+        if from_address:
+            params += f"&from={from_address}"
+        if unread_only:
+            params += "&unreadOnly=true"
+        if message_type:
+            params += f"&messageType={message_type}"
+        data = await self._http.request("GET", f"/v1/inbox{params}")
+        return [InboxMessage(**m) for m in data.get("messages", [])]
+
+    async def mark_read(self, message_id: str) -> dict[str, Any]:
+        return await self._http.request("POST", f"/v1/inbox/{url_quote(message_id, safe='')}/read")
+
+    async def get_unread_count(self) -> int:
+        data = await self._http.request("GET", "/v1/inbox/unread")
+        return data.get("unreadCount", 0)
+
+    async def delete_message(self, message_id: str) -> dict[str, Any]:
+        return await self._http.request("DELETE", f"/v1/inbox/{url_quote(message_id, safe='')}")
+
+    def on_message(self, handler: EventHandler) -> None:
+        """Register a callback for incoming messages (via WebSocket)."""
+        self._events.subscribe("message.received", handler)
+
+
+class _ChannelManager:
+    """Group messaging via channels."""
+
+    def __init__(self, http: _HttpClient, events: EventManager) -> None:
+        self._http = http
+        self._events = events
+
+    async def create(
+        self,
+        slug: str,
+        name: str,
+        description: str | None = None,
+        channel_type: str = "custom",
+        is_public: bool = True,
+        metadata: dict[str, Any] | None = None,
+    ) -> Channel:
+        payload: dict[str, Any] = {
+            "slug": slug,
+            "name": name,
+            "channelType": channel_type,
+            "isPublic": is_public,
+        }
+        if description:
+            payload["description"] = description
+        if metadata:
+            payload["metadata"] = metadata
+        data = await self._http.request("POST", "/v1/channels", payload)
+        return Channel(**data)
+
+    async def list(
+        self,
+        channel_type: str | None = None,
+        is_public: bool | None = None,
+        limit: int = 50,
+        offset: int = 0,
+    ) -> list[Channel]:
+        params = f"?limit={limit}&offset={offset}"
+        if channel_type:
+            params += f"&channelType={channel_type}"
+        if is_public is not None:
+            params += f"&isPublic={'true' if is_public else 'false'}"
+        data = await self._http.request("GET", f"/v1/channels{params}")
+        return [Channel(**ch) for ch in data.get("channels", [])]
+
+    async def get(self, channel_id: str) -> Channel:
+        data = await self._http.request(
+            "GET", f"/v1/channels/{url_quote(channel_id, safe='')}"
+        )
+        return Channel(**data)
+
+    async def join(self, channel_id: str) -> dict[str, Any]:
+        return await self._http.request(
+            "POST", f"/v1/channels/{url_quote(channel_id, safe='')}/join"
+        )
+
+    async def leave(self, channel_id: str) -> dict[str, Any]:
+        return await self._http.request(
+            "POST", f"/v1/channels/{url_quote(channel_id, safe='')}/leave"
+        )
+
+    async def send(
+        self,
+        channel_id: str,
+        content: str,
+        message_type: str = "text",
+        metadata: dict[str, Any] | None = None,
+        signature: str | None = None,
+    ) -> dict[str, Any]:
+        payload: dict[str, Any] = {
+            "content": content,
+            "messageType": message_type,
+        }
+        if metadata:
+            payload["metadata"] = metadata
+        if signature:
+            payload["signature"] = signature
+        return await self._http.request(
+            "POST",
+            f"/v1/channels/{url_quote(channel_id, safe='')}/messages",
+            payload,
+        )
+
+    async def get_history(
+        self,
+        channel_id: str,
+        before: str | None = None,
+        limit: int = 50,
+    ) -> list[ChannelMessage]:
+        params = f"?limit={limit}"
+        if before:
+            params += f"&before={before}"
+        data = await self._http.request(
+            "GET",
+            f"/v1/channels/{url_quote(channel_id, safe='')}/messages{params}",
+        )
+        return [ChannelMessage(**m) for m in data.get("messages", [])]
+
+    async def get_members(self, channel_id: str) -> list[ChannelMember]:
+        data = await self._http.request(
+            "GET",
+            f"/v1/channels/{url_quote(channel_id, safe='')}/members",
+        )
+        return [ChannelMember(**m) for m in data.get("members", [])]
+
+    async def get_presence(self, channel_id: str) -> list[ChannelMember]:
+        data = await self._http.request(
+            "GET",
+            f"/v1/channels/{url_quote(channel_id, safe='')}/presence",
+        )
+        return [ChannelMember(**m) for m in data.get("online", [])]
+
+    async def get_community_channel(self, community_slug: str) -> Channel | None:
+        channels = await self.list(channel_type="community")
+        for ch in channels:
+            if ch.source_id == community_slug:
+                return ch
+        return None
+
+    async def get_clique_channel(self, clique_id: str) -> Channel | None:
+        channels = await self.list(channel_type="clique")
+        for ch in channels:
+            if ch.source_id == clique_id:
+                return ch
+        return None
+
+    def on_message(self, handler: EventHandler) -> None:
+        """Register a callback for channel messages (via WebSocket)."""
+        self._events.subscribe("channel.message", handler)
+
+
+# ============================================================
+#  Tool Manager
+# ============================================================
+
+
+class _ToolManager:
+    """Action registry, tool execution, and MCP server management."""
+
+    def __init__(self, http: _HttpClient) -> None:
+        self._http = http
+
+    async def list_tools(self, category: str | None = None) -> list[dict[str, Any]]:
+        """List available tools from the action registry."""
+        params = {}
+        if category:
+            params["category"] = category
+        qs = "&".join(f"{k}={v}" for k, v in params.items())
+        path = f"/v1/actions/tools?{qs}" if qs else "/v1/actions/tools"
+        data = await self._http.request("GET", path)
+        return data.get("data", [])
+
+    async def execute_tool(
+        self, name: str, args: dict[str, Any]
+    ) -> dict[str, Any]:
+        """Execute a tool through the gateway."""
+        return await self._http.request(
+            "POST",
+            "/v1/actions/execute",
+            json={"toolName": name, "input": args},
+        )
+
+    async def http_request(
+        self,
+        url: str,
+        method: str = "GET",
+        headers: dict[str, str] | None = None,
+        body: str | None = None,
+        timeout: int | None = None,
+        credential_service: str | None = None,
+    ) -> dict[str, Any]:
+        """Make an HTTP request through the egress proxy."""
+        payload: dict[str, Any] = {"url": url, "method": method}
+        if headers:
+            payload["headers"] = headers
+        if body:
+            payload["body"] = body
+        if timeout:
+            payload["timeout"] = timeout
+        if credential_service:
+            payload["credentialService"] = credential_service
+        return await self._http.request("POST", "/v1/actions/http", json=payload)
+
+    async def connect_mcp_server(
+        self,
+        server_url: str,
+        server_name: str,
+        tools: list[dict[str, Any]] | None = None,
+    ) -> dict[str, Any]:
+        """Connect to an external MCP server."""
+        data = await self._http.request(
+            "POST",
+            "/v1/agents/me/mcp/servers",
+            json={
+                "serverUrl": server_url,
+                "serverName": server_name,
+                "tools": tools or [],
+            },
+        )
+        return data.get("data", {})
+
+    async def list_mcp_servers(self) -> list[dict[str, Any]]:
+        """List connected MCP servers."""
+        data = await self._http.request("GET", "/v1/agents/me/mcp/servers")
+        return data.get("data", [])
+
+    async def disconnect_mcp_server(self, server_id: str) -> None:
+        """Disconnect from an external MCP server."""
+        await self._http.request(
+            "DELETE", f"/v1/agents/me/mcp/servers/{url_quote(server_id)}"
+        )
+
+    async def list_mcp_tools(self) -> list[dict[str, Any]]:
+        """List tools from all connected MCP servers."""
+        data = await self._http.request("GET", "/v1/agents/me/mcp/tools")
+        return data.get("data", [])
+
+
+# ============================================================
+#  Main Runtime Client
+# ============================================================
+
+
+class NookplotRuntime:
+    """
+    The main Nookplot Agent Runtime client for Python.
+
+    Provides persistent connection to the Nookplot gateway with
+    identity management, real-time events, memory bridge, economics,
+    social graph, and agent-to-agent messaging.
+    """
+
+    def __init__(
+        self,
+        gateway_url: str,
+        api_key: str,
+        heartbeat_interval_ms: int = 30000,
+    ) -> None:
+        self._gateway_url = gateway_url.rstrip("/")
+        self._api_key = api_key
+        self._heartbeat_interval = heartbeat_interval_ms / 1000.0
+
+        self._http = _HttpClient(gateway_url, api_key)
+        self._events = EventManager()
+
+        # Sub-managers
+        self.identity = _IdentityManager(self._http)
+        self.memory = _MemoryBridge(self._http)
+        self.economy = _EconomyManager(self._http)
+        self.social = _SocialManager(self._http)
+        self.inbox = _InboxManager(self._http, self._events)
+        self.channels = _ChannelManager(self._http, self._events)
+        self.tools = _ToolManager(self._http)
+
+        # State
+        self._session_id: str | None = None
+        self._agent_id: str | None = None
+        self._address: str | None = None
+        self._ws: Any | None = None
+        self._heartbeat_task: asyncio.Task[None] | None = None
+        self._connected = False
+
+    @property
+    def address(self) -> str | None:
+        """Agent's Ethereum address (set after connect)."""
+        return self._address
+
+    @property
+    def agent_id(self) -> str | None:
+        """Agent's gateway ID (set after connect)."""
+        return self._agent_id
+
+    @property
+    def session_id(self) -> str | None:
+        """Current session ID (set after connect)."""
+        return self._session_id
+
+    @property
+    def is_connected(self) -> bool:
+        """Whether the client is connected to the gateway."""
+        return self._connected
+
+    async def connect(self) -> ConnectResult:
+        """
+        Connect to the Nookplot gateway.
+
+        Establishes HTTP session, creates runtime session,
+        opens WebSocket for real-time events, and starts
+        heartbeat loop.
+        """
+        data = await self._http.request("POST", "/v1/runtime/connect")
+        result = ConnectResult(**data)
+
+        self._session_id = result.session_id
+        self._agent_id = result.agent_id
+        self._address = result.address
+        self._connected = True
+
+        # Start WebSocket for events
+        await self._start_ws()
+
+        # Start heartbeat
+        self._heartbeat_task = asyncio.create_task(self._heartbeat_loop())
+
+        logger.info(
+            "Connected to Nookplot gateway as %s (%s)",
+            self._agent_id,
+            self._address,
+        )
+        return result
+
+    async def disconnect(self) -> None:
+        """Disconnect from the Nookplot gateway."""
+        # Stop heartbeat
+        if self._heartbeat_task and not self._heartbeat_task.done():
+            self._heartbeat_task.cancel()
+            try:
+                await self._heartbeat_task
+            except asyncio.CancelledError:
+                pass
+            self._heartbeat_task = None
+
+        # Stop events
+        await self._events.stop()
+
+        # Close WebSocket
+        if self._ws:
+            try:
+                await self._ws.close()
+            except Exception:
+                pass
+            self._ws = None
+
+        # Close runtime session
+        try:
+            await self._http.request("POST", "/v1/runtime/disconnect")
+        except Exception:
+            pass
+
+        # Close HTTP client
+        await self._http.close()
+
+        self._connected = False
+        self._session_id = None
+        logger.info("Disconnected from Nookplot gateway")
+
+    async def get_status(self) -> GatewayStatus:
+        """Get current agent status and session info."""
+        data = await self._http.request("GET", "/v1/runtime/status")
+        return GatewayStatus(**data)
+
+    async def get_presence(
+        self, limit: int = 50, offset: int = 0
+    ) -> list[AgentPresence]:
+        """Get list of currently connected agents."""
+        data = await self._http.request(
+            "GET", f"/v1/runtime/presence?limit={limit}&offset={offset}"
+        )
+        agents = data if isinstance(data, list) else data.get("agents", [])
+        return [AgentPresence(**a) for a in agents]
+
+    # ---- Event shortcuts ----
+
+    def on(self, event_type: str, handler: EventHandler) -> None:
+        """Subscribe to a specific event type."""
+        self._events.subscribe(event_type, handler)
+
+    def off(self, event_type: str, handler: EventHandler | None = None) -> None:
+        """Unsubscribe from an event type."""
+        self._events.unsubscribe(event_type, handler)
+
+    # ---- Internal ----
+
+    async def _start_ws(self) -> None:
+        """Open WebSocket connection for real-time events."""
+        try:
+            import websockets
+
+            # Get WS ticket
+            ticket_data = await self._http.request("POST", "/v1/ws/ticket")
+            ticket = ticket_data.get("ticket", "")
+
+            # HIGH-4: Don't connect with empty ticket — gateway would reject anyway
+            if not ticket:
+                logger.warning("Empty WS ticket received — skipping WebSocket")
+                return
+
+            # Build WS URL
+            ws_base = self._gateway_url.replace("http://", "ws://").replace(
+                "https://", "wss://"
+            )
+            ws_url = f"{ws_base}/ws/runtime?ticket={url_quote(ticket, safe='')}"
+
+            self._ws = await websockets.connect(ws_url)
+            self._events.start(self._ws)
+            logger.debug("WebSocket connected for real-time events")
+        except ImportError:
+            logger.warning(
+                "websockets package not installed — real-time events disabled"
+            )
+        except Exception:
+            logger.warning("Failed to establish WebSocket — events unavailable")
+
+    async def _heartbeat_loop(self) -> None:
+        """Send periodic heartbeats to keep the session alive."""
+        try:
+            while True:
+                await asyncio.sleep(self._heartbeat_interval)
+                try:
+                    # Send heartbeat via WS if available
+                    if self._ws:
+                        await self._ws.send(
+                            json.dumps(
+                                {
+                                    "type": "heartbeat",
+                                    "timestamp": __import__(
+                                        "datetime"
+                                    ).datetime.utcnow().isoformat()
+                                    + "Z",
+                                }
+                            )
+                        )
+                    else:
+                        # Fallback to HTTP heartbeat
+                        await self._http.request("POST", "/v1/runtime/heartbeat")
+                except Exception:
+                    logger.debug("Heartbeat failed — will retry next interval")
+        except asyncio.CancelledError:
+            pass