grid-agent-sdk 1.0.0__tar.gz

grid_agent_sdk-1.0.0/PKG-INFO

@@ -0,0 +1,13 @@
+Metadata-Version: 2.4
+Name: grid-agent-sdk
+Version: 1.0.0
+Requires-Dist: anthropic
+Requires-Dist: openai
+Requires-Dist: httpx
+Requires-Dist: python-dotenv
+Requires-Dist: web3
+Requires-Dist: eth-account
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: pytest-asyncio; extra == "dev"
+Requires-Dist: mypy; extra == "dev"

grid_agent_sdk-1.0.0/grid_agent/agent.py

@@ -0,0 +1,514 @@
+"""
+GridAgent — autonomous agent with MCP tool dispatch and x402 payment signing.
+"""
+from __future__ import annotations
+
+import asyncio
+import json
+import os
+import time
+import logging
+from contextlib import asynccontextmanager
+from typing import Any, AsyncIterator
+
+import httpx
+
+from .types import GridManifest, SessionInfo, ToolCallResult, X402Attestation
+from .wallet import WalletSigner
+from .session import SessionManager, USDC_BASE_SEPOLIA
+
+logger = logging.getLogger(__name__)
+
+# ─── MCP HTTP client ──────────────────────────────────────────────────────────
+
+class MCPClient:
+    """Async HTTP client for the Grid gateway /api/mcp endpoint."""
+
+    def __init__(self, gateway_url: str, http_client: httpx.AsyncClient) -> None:
+        url = gateway_url.rstrip("/")
+        # FIX: Explicit endswith guards for both variants to prevent duplicate paths
+        if url.endswith("/api/mcp") or url.endswith("/mcp"):
+            self._url = url
+        else:
+            self._url = url + "/api/mcp"
+        self._http = http_client
+
+    async def call(
+        self,
+        tool: str,
+        input: dict[str, Any],
+        session_id: str,
+        agent_sig: str,
+        payment_header: str | None = None,
+        idempotency_key: str | None = None,
+    ) -> httpx.Response:
+        import uuid
+        request_id = str(uuid.uuid4())
+        headers: dict[str, str] = {
+            "Content-Type": "application/json",
+            "x-agent-sig":  agent_sig,
+            "x-session-id": session_id,
+            "X-Request-Id": request_id,
+        }
+        if payment_header:
+            headers["x-payment"] = payment_header
+        if idempotency_key:
+            headers["x-idempotency-key"] = idempotency_key
+
+        return await self._http.post(
+            self._url,
+            json={"tool": tool, "input": input, "sessionId": session_id, "agentSig": agent_sig},
+            headers=headers,
+            timeout=60.0,
+        )
+
+    async def stream(
+        self,
+        tool: str,
+        input: dict[str, Any],
+        session_id: str,
+        agent_sig: str,
+        payment_header: str | None = None,
+        idempotency_key: str | None = None,
+    ) -> AsyncIterator[str]:
+        import uuid
+        request_id = str(uuid.uuid4())
+        headers: dict[str, str] = {
+            "Content-Type": "application/json",
+            "x-agent-sig":  agent_sig,
+            "x-session-id": session_id,
+            "X-Request-Id": request_id,
+            "Accept":       "text/event-stream",
+        }
+        if payment_header:
+            headers["x-payment"] = payment_header
+        if idempotency_key:
+            headers["x-idempotency-key"] = idempotency_key
+
+        async with self._http.stream(
+            "POST",
+            self._url,
+            json={"tool": tool, "input": input, "sessionId": session_id, "agentSig": agent_sig},
+            headers=headers,
+            timeout=None,
+        ) as resp:
+            if resp.status_code not in (200, 201):
+                body = await resp.aread()
+                raise RuntimeError(f"Gateway error {resp.status_code}: {body.decode()}")
+            async for line in resp.aiter_lines():
+                if line.startswith("data:"):
+                    data = line[5:].strip()
+                    if data == "[DONE]":
+                        break
+                    yield data
+
+
+# ─── Nonce counter ────────────────────────────────────────────────────────────
+
+class _NonceCounter:
+    """Persistent per-session nonce to prevent attestation replay across restarts."""
+    def __init__(self) -> None:
+        self._counters: dict[str, int] = {}
+        self._base_dir = os.path.join(os.getcwd(), ".grid", "nonces")
+        os.makedirs(self._base_dir, exist_ok=True)
+
+    def _get_path(self, session_id: str) -> str:
+        # Use a safe filename for the session_id
+        safe_id = session_id.removeprefix("0x")
+        return os.path.join(self._base_dir, f"{safe_id}.nonce")
+
+    def next(self, session_id: str) -> int:
+        if session_id not in self._counters:
+            path = self._get_path(session_id)
+            if os.path.exists(path):
+                try:
+                    with open(path, "r") as f:
+                        self._counters[session_id] = int(f.read().strip())
+                except (ValueError, IOError):
+                    self._counters[session_id] = 0
+            else:
+                self._counters[session_id] = 0
+
+        self._counters[session_id] += 1
+        
+        # Persist to disk
+        try:
+            with open(self._get_path(session_id), "w") as f:
+                f.write(str(self._counters[session_id]))
+        except IOError as e:
+            logger.warning(f"Failed to persist nonce for {session_id}: {e}")
+
+        return self._counters[session_id]
+
+
+# ─── GridAgent ────────────────────────────────────────────────────────────────
+
+from .providers import LLMProvider, AnthropicProvider, OpenAIProvider, OpenAICompatibleProvider
+
+class GridAgent:
+    def __init__(
+        self,
+        *,
+        provider: LLMProvider,
+        gateway_url: str,
+        manifest: GridManifest,
+        signer: WalletSigner,
+        rpc_url: str,
+        contract_address: str,
+        usdc_address: str = USDC_BASE_SEPOLIA,
+        max_tool_retries: int = 2,
+    ) -> None:
+        self._provider     = provider
+        self._manifest     = manifest
+        self._signer       = signer
+        self._max_retries  = max_tool_retries
+        self._nonces       = _NonceCounter()
+        self._http         = httpx.AsyncClient()
+        self._mcp          = MCPClient(gateway_url, self._http)
+        self._sandbox = os.environ.get("GRID_SANDBOX", "").lower() in ("1", "true", "yes")
+        self._session_mgr  = SessionManager(
+            rpc_url=rpc_url,
+            contract_address=contract_address,
+            signer=signer,
+            usdc_address=usdc_address,
+            sandbox=self._sandbox,
+        )
+
+    @classmethod
+    def from_env(cls, manifest_path: str = "grid.manifest.json") -> "GridAgent":
+        from dotenv import load_dotenv
+        load_dotenv()
+
+        # Preflight check for core Grid variables
+        required_grid_env = ["GRID_RPC_URL", "GRID_OWNER_KEY"]
+        missing = [e for e in required_grid_env if e not in os.environ]
+        if missing:
+            raise EnvironmentError(f"Missing core Grid environment variables: {', '.join(missing)}")
+
+        if not os.path.exists(manifest_path):
+            raise FileNotFoundError(f"Grid manifest not found at {manifest_path}. Run `grid deploy` first.")
+
+        try:
+            with open(manifest_path) as fh:
+                manifest = GridManifest.from_dict(json.load(fh))
+        except json.JSONDecodeError as e:
+            raise RuntimeError(f"Failed to parse Grid manifest at {manifest_path}: {str(e)}")
+
+        signer = WalletSigner.from_env()
+
+        # FIX: Universal Provider Selection
+        provider_name = os.environ.get("GRID_PROVIDER", "").lower()
+        
+        if provider_name == "anthropic" or "ANTHROPIC_API_KEY" in os.environ:
+            provider = AnthropicProvider(
+                api_key=os.environ["ANTHROPIC_API_KEY"],
+                model=os.environ.get("GRID_MODEL", "claude-3-5-sonnet-20240620")
+            )
+        elif provider_name == "openai" or "OPENAI_API_KEY" in os.environ:
+            provider = OpenAIProvider(
+                api_key=os.environ["OPENAI_API_KEY"],
+                model=os.environ.get("GRID_MODEL", "gpt-4-turbo")
+            )
+        elif provider_name == "local" or "GRID_LOCAL_MODEL_URL" in os.environ:
+            provider = OpenAICompatibleProvider(
+                base_url=os.environ["GRID_LOCAL_MODEL_URL"],
+                model=os.environ.get("GRID_MODEL", "local-model")
+            )
+        else:
+            raise EnvironmentError(
+                "No LLM provider configured. Set ANTHROPIC_API_KEY, OPENAI_API_KEY, or GRID_LOCAL_MODEL_URL."
+            )
+
+        return cls(
+            provider=provider,
+            gateway_url=manifest.gateway_url,
+            manifest=manifest,
+            signer=signer,
+            rpc_url=os.environ["GRID_RPC_URL"],
+            contract_address=os.environ.get("GRID_CONTRACT_ADDRESS", manifest.contract_address),
+            usdc_address=os.environ.get("GRID_USDC_ADDRESS", USDC_BASE_SEPOLIA),
+        )
+
+    @asynccontextmanager
+    async def session(self, allowance_usdc: float, ttl_seconds: int = 3600) -> AsyncIterator[SessionInfo]:
+        """
+        Context manager for an on-chain Grid session.
+        Ensures the session is closed even if the agent crashes.
+        """
+        sess = await self._session_mgr.open(allowance_usdc, ttl_seconds)
+        try:
+            yield sess
+        finally:
+            try:
+                await self._session_mgr.close(sess.session_id)
+            except Exception as e:
+                logger.error(f"Failed to close session {sess.session_id}: {str(e)}")
+
+    async def run(
+        self,
+        prompt: str,
+        session: SessionInfo,
+        system: str | None = None,
+    ) -> str:
+        # Preflight expiry check
+        if session.expiry and time.time() > session.expiry:
+            raise RuntimeError(f"Session {session.session_id!r} expired at {session.expiry}.")
+
+        tools   = self._build_tool_schemas()
+        system  = system or (
+            "You are an autonomous agent with access to paid API tools via the Grid protocol. "
+            "Use tools as needed. Tools are metered — prefer fewer calls to conserve budget."
+        )
+        messages: list[dict[str, Any]] = [{"role": "user", "content": prompt}]
+
+        while True:
+            response = self._provider.create_message(messages, tools, system)
+            assistant_blocks, stop_reason = self._provider.parse_response(response)
+
+            messages.append({"role": "assistant", "content": assistant_blocks})
+
+            if stop_reason != "tool_use":
+                return " ".join(
+                    b["text"] for b in assistant_blocks if b["type"] == "text"
+                )
+
+            tool_blocks = [b for b in assistant_blocks if b["type"] == "tool_use"]
+            
+            # return_exceptions=True to prevent one tool crash from killing the entire run
+            results_raw = await asyncio.gather(
+                *[self._dispatch_tool(b, session) for b in tool_blocks],
+                return_exceptions=True,
+            )
+
+            # Build tool_result turn
+            result_content: list[dict[str, Any]] = []
+            for i, tr in enumerate(results_raw):
+                # Handle exceptions from gather
+                if isinstance(tr, Exception):
+                    logger.error(f"Tool execution failed: {str(tr)}")
+                    result_content.append({
+                        "type": "tool_result",
+                        "tool_use_id": tool_blocks[i]["id"],
+                        "content": f"Internal Error: {str(tr)}",
+                        "is_error": True,
+                    })
+                    continue
+
+                session.spent_micro += tr.cost_usdc_micro
+                result_content.append({
+                    "type":        "tool_result",
+                    "tool_use_id": tr.call_id,
+                    "content": (
+                        json.dumps(tr.content)
+                        if not isinstance(tr.content, str)
+                        else tr.content
+                    ) if tr.error is None else f"Error: {tr.error}",
+                    "is_error": tr.error is not None,
+                })
+
+            messages.append({"role": "user", "content": result_content})
+
+    # ── Tool dispatch with 402 retry ──────────────────────────────────────────
+
+    async def _dispatch_tool(
+        self,
+        block: Any,
+        session: SessionInfo,
+    ) -> ToolCallResult:
+        call_id    = block.id
+        tool_name  = block.name
+        tool_input = block.input
+
+        # Use the hot session key to sign the specific tool call authorisation
+        agent_sig = self._signer.sign_mcp_call(
+            tool=tool_name,
+            session_id=session.session_id,
+            input_data=tool_input
+        )
+
+        for attempt in range(self._max_retries + 1):
+            try:
+                resp = await self._mcp.call(
+                    tool=tool_name,
+                    input=tool_input,
+                    session_id=session.session_id,
+                    agent_sig=agent_sig,
+                )
+            except httpx.RequestError as e:
+                return ToolCallResult(
+                    call_id=call_id,
+                    content=None,
+                    error=f"Network error: {str(e)}",
+                )
+
+            if resp.status_code in (200, 201):
+                try:
+                    body = resp.json()
+                    return ToolCallResult(
+                        call_id=call_id,
+                        content=body.get("content", body),
+                        cost_usdc_micro=body.get("usage", {}).get("cost_usdc_micro", 0),
+                    )
+                except json.JSONDecodeError:
+                    return ToolCallResult(
+                        call_id=call_id,
+                        content=None,
+                        error="Gateway returned invalid JSON",
+                    )
+
+            if resp.status_code == 402 and attempt < self._max_retries:
+                try:
+                    body_402 = resp.json()
+                except json.JSONDecodeError:
+                    return ToolCallResult(
+                        call_id=call_id,
+                        content=None,
+                        error="Gateway returned invalid JSON on 402",
+                    )
+
+                # This will raise RuntimeError if allowance is insufficient, which is expected
+                attestation = self._build_attestation(body_402, session)
+                payment_hdr = self._payment_header(attestation)
+
+                try:
+                    paid_resp = await self._mcp.call(
+                        tool=tool_name,
+                        input=tool_input,
+                        session_id=session.session_id,
+                        agent_sig=agent_sig,
+                        payment_header=payment_hdr,
+                    )
+                except httpx.RequestError as e:
+                    return ToolCallResult(
+                        call_id=call_id,
+                        content=None,
+                        error=f"Network error during payment retry: {str(e)}",
+                    )
+
+                if paid_resp.status_code in (200, 201):
+                    try:
+                        body = paid_resp.json()
+                        # Prefer response cost, fall back to attested amount
+                        return ToolCallResult(
+                            call_id=call_id,
+                            content=body.get("content", body),
+                            cost_usdc_micro=body.get("usage", {}).get(
+                                "cost_usdc_micro", attestation.amount
+                            ),
+                        )
+                    except json.JSONDecodeError:
+                        return ToolCallResult(
+                            call_id=call_id,
+                            content=None,
+                            error="Gateway returned invalid JSON after payment",
+                        )
+
+                # Vendor rejected even after payment — surface as error
+                return ToolCallResult(
+                    call_id=call_id,
+                    content=None,
+                    error=f"Vendor rejected paid request: HTTP {paid_resp.status_code}",
+                )
+
+            # Non-402 error or exhausted retries
+            return ToolCallResult(
+                call_id=call_id,
+                content=None,
+                error=f"HTTP {resp.status_code}: {resp.text[:200]}",
+            )
+
+        return ToolCallResult(call_id=call_id, content=None, error="Max retries exceeded")
+
+    def _build_attestation(
+        self,
+        body_402: dict[str, Any],
+        session: SessionInfo,
+    ) -> X402Attestation:
+        vendor = body_402.get("vendor") or self._manifest.contract_address
+        if not vendor:
+             raise RuntimeError("Vendor missing in 402 response and no contract address in manifest")
+             
+        # Typed guard for amount
+        raw_amount = body_402.get("amount", 0)
+        try:
+            amount = int(raw_amount)
+        except (TypeError, ValueError):
+            raise RuntimeError(f"Invalid amount in 402 response: {raw_amount!r}")
+
+        nonce  = self._nonces.next(session.session_id)
+
+        if session.spent_micro + amount > session.allowance_micro:
+            raise RuntimeError(
+                f"Insufficient session allowance: need {amount} more micro-USDC "
+                f"but only {session.remaining_micro} remaining."
+            )
+
+        sig = self._signer.sign_attestation(
+            session_id=session.session_id,
+            vendor=vendor,
+            amount=amount,
+            nonce=nonce,
+            contract_address=self._manifest.contract_address,
+        )
+        return X402Attestation(
+            session_id=session.session_id,
+            vendor=vendor,
+            amount=amount,
+            nonce=nonce,
+            signature=sig,
+        )
+
+    def _payment_header(self, att: X402Attestation) -> str:
+        return json.dumps({
+            "v":         1,
+            "sessionId": att.session_id,
+            "vendor":    att.vendor,
+            "amount":    att.amount,
+            "nonce":     str(att.nonce),
+            "signature": att.signature,
+        })
+
+    # ── Anthropic tool schema builder ─────────────────────────────────────────
+
+    def _build_tool_schemas(self) -> list[dict[str, Any]]:
+        schemas = []
+        for t in self._manifest.tools:
+            props: dict[str, Any] = {}
+            required: list[str]   = []
+
+            for p in t.parameters:
+                props[p["name"]] = {
+                    # Preserve parameter type instead of hardcoding "string"
+                    "type":        p.get("type", "string"),
+                    "description": p.get("description", ""),
+                }
+                if p.get("required"):
+                    required.append(p["name"])
+
+            if t.has_request_body:
+                props["body"] = {"type": "object", "description": "JSON request body"}
+
+            schemas.append({
+                "name": t.operation_id,
+                "description": (
+                    f"{t.method} {t.path} — "
+                    f"costs ${t.pricing_amount / 1_000_000:.4f} USDC/{t.pricing_model}"
+                ),
+                "input_schema": {
+                    "type":       "object",
+                    "properties": props,
+                    "required":   required,
+                },
+            })
+        return schemas
+
+    # ── Lifecycle ─────────────────────────────────────────────────────────────
+
+    async def aclose(self) -> None:
+        await self._http.aclose()
+
+    async def __aenter__(self) -> "GridAgent":
+        return self
+
+    async def __aexit__(self, *_: Any) -> None:
+        await self.aclose()

grid_agent_sdk-1.0.0/grid_agent/discovery.py

@@ -0,0 +1,92 @@
+"""
+DiscoveryManager — Autonomous on-chain tool discovery via CapabilityRegistry.
+"""
+from __future__ import annotations
+
+from typing import Any, List, Optional
+from web3 import Web3
+from web3.contract import Contract
+
+class DiscoveryManager:
+    """
+    Enables agents to autonomously find and resolve Grid tools using the
+    on-chain CapabilityRegistry.
+    """
+
+    def __init__(self, rpc_url: str, registry_address: str) -> None:
+        self._w3 = Web3(Web3.HTTPProvider(rpc_url))
+        self._registry_abi = [
+            {
+                "name": "listingCount",
+                "type": "function",
+                "stateMutability": "view",
+                "inputs": [],
+                "outputs": [{"name": "", "type": "uint256"}],
+            },
+            {
+                "name": "listings",
+                "type": "function",
+                "stateMutability": "view",
+                "inputs": [{"name": "", "type": "uint256"}],
+                "outputs": [
+                    {"name": "vendor",       "type": "address"},
+                    {"name": "toolId",       "type": "string"},
+                    {"name": "manifestCid",  "type": "string"},
+                    {"name": "gatewayUrl",   "type": "string"},
+                    {"name": "name",         "type": "string"},
+                    {"name": "description",  "type": "string"},
+                    {"name": "tags",         "type": "string[]"},
+                    {"name": "version",      "type": "uint16"},
+                    {"name": "registeredAt", "type": "uint64"},
+                    {"name": "updatedAt",    "type": "uint64"},
+                    {"name": "active",       "type": "bool"},
+                ],
+            },
+        ]
+        self._registry: Contract = self._w3.eth.contract(
+            address=Web3.to_checksum_address(registry_address),
+            abi=self._registry_abi,
+        )
+
+    def list_all_tools(self, filter_tag: Optional[str] = None) -> List[dict[str, Any]]:
+        """
+        Scan the registry for all active tools.
+        In production, this would ideally use a subgraph or an off-chain indexer
+        for performance, but we use direct RPC calls here for the scaffold.
+        """
+        count = self._registry.functions.listingCount().call()
+        tools = []
+        
+        for i in range(1, count + 1):
+            l = self._registry.functions.listings(i).call()
+            # Tuple indices based on Listing struct: 
+            # 0:vendor, 1:toolId, 2:manifestCid, 3:gatewayUrl, 4:name, 5:description, 6:tags, 10:active
+            if not l[10]: # active
+                continue
+                
+            tags = l[6]
+            if filter_tag and filter_tag not in tags:
+                continue
+                
+            tools.append({
+                "listing_id":  i,
+                "vendor":      l[0],
+                "tool_id":     l[1],
+                "manifest_cid": l[2],
+                "gateway_url":  l[3],
+                "name":         l[4],
+                "description":  l[5],
+                "tags":         tags,
+            })
+            
+        return tools
+
+    def resolve_tool(self, tool_id: str) -> Optional[dict[str, Any]]:
+        """
+        Find the latest manifest for a specific tool ID.
+        """
+        tools = self.list_all_tools()
+        for t in tools:
+            if t["tool_id"] == tool_id:
+                return t
+        return None