grid-agent-sdk 1.0.0__py3-none-any.whl

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/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

grid_agent/providers.py

@@ -0,0 +1,156 @@
+from abc import ABC, abstractmethod
+from typing import Any, List, Dict
+
+class LLMProvider(ABC):
+    """Abstract base class for LLM providers (Anthropic, OpenAI, etc.)"""
+    
+    @abstractmethod
+    def create_message(
+        self, 
+        messages: List[Dict[str, Any]], 
+        tools: List[Dict[str, Any]], 
+        system: str
+    ) -> Any:
+        pass
+
+    @abstractmethod
+    def parse_response(self, response: Any) -> tuple[List[Dict[str, Any]], str | None]:
+        """Returns (new_messages, stop_reason)"""
+        pass
+
+class AnthropicProvider(LLMProvider):
+    def __init__(self, api_key: str, model: str):
+        import anthropic
+        self.client = anthropic.Anthropic(api_key=api_key)
+        self.model = model
+
+    def create_message(self, messages, tools, system):
+        return self.client.messages.create(
+            model=self.model,
+            max_tokens=4096,
+            system=system,
+            tools=tools,
+            messages=messages,
+        )
+
+    def parse_response(self, response):
+        blocks = []
+        for block in response.content:
+            if block.type == "text":
+                blocks.append({"type": "text", "text": block.text})
+            elif block.type == "tool_use":
+                blocks.append({
+                    "type": "tool_use",
+                    "id": block.id,
+                    "name": block.name,
+                    "input": block.input,
+                })
+        return blocks, response.stop_reason
+
+class OpenAIProvider(LLMProvider):
+    def __init__(self, api_key: str, model: str = "gpt-4-turbo"):
+        from openai import OpenAI
+        self.client = OpenAI(api_key=api_key)
+        self.model = model
+
+    def create_message(self, messages, tools, system):
+        # Transform messages to OpenAI format
+        openai_msgs = [{"role": "system", "content": system}]
+        
+        for m in messages:
+            role = m["role"]
+            content = m["content"]
+            
+            if role == "user" and isinstance(content, list):
+                # Check for tool_result blocks
+                tool_results = [b for b in content if b["type"] == "tool_result"]
+                text_blocks = [b for b in content if b["type"] == "text"]
+                
+                # Add text content if present
+                if text_blocks:
+                    openai_msgs.append({
+                        "role": "user",
+                        "content": " ".join(b["text"] for b in text_blocks)
+                    })
+                
+                # Add each tool result as a separate 'tool' role message
+                for tr in tool_results:
+                    openai_msgs.append({
+                        "role": "tool",
+                        "tool_call_id": tr["tool_use_id"],
+                        "content": tr["content"]
+                    })
+            elif role == "assistant" and isinstance(content, list):
+                # Transform assistant tool_use blocks to tool_calls
+                tool_calls = []
+                text = ""
+                for b in content:
+                    if b["type"] == "text":
+                        text += b["text"]
+                    elif b["type"] == "tool_use":
+                        import json
+                        tool_calls.append({
+                            "id": b["id"],
+                            "type": "function",
+                            "function": {
+                                "name": b["name"],
+                                "arguments": json.dumps(b["input"])
+                            }
+                        })
+                
+                msg_obj = {"role": "assistant", "content": text if text else None}
+                if tool_calls:
+                    msg_obj["tool_calls"] = tool_calls
+                openai_msgs.append(msg_obj)
+            else:
+                openai_msgs.append({"role": role, "content": content})
+
+        # Simplified tool schema conversion (OpenAI format)
+        openai_tools = []
+        for t in tools:
+            openai_tools.append({
+                "type": "function",
+                "function": {
+                    "name": t["name"],
+                    "description": t["description"],
+                    "parameters": t["input_schema"]
+                }
+            })
+
+        return self.client.chat.completions.create(
+            model=self.model,
+            messages=openai_msgs,
+            tools=openai_tools if openai_tools else None,
+        )
+
+    def parse_response(self, response):
+        choice = response.choices[0]
+        msg = choice.message
+        blocks = []
+        
+        if msg.content:
+            blocks.append({"type": "text", "text": msg.content})
+            
+        stop_reason = None
+        if choice.finish_reason == "tool_calls":
+            stop_reason = "tool_use"
+            for tc in msg.tool_calls:
+                import json
+                blocks.append({
+                    "type": "tool_use",
+                    "id": tc.id,
+                    "name": tc.function.name,
+                    "input": json.loads(tc.function.arguments),
+                })
+        
+        return blocks, stop_reason
+
+class OpenAICompatibleProvider(OpenAIProvider):
+    """
+    Support for local or open-source models (Ollama, vLLM, LiteLLM)
+    using the OpenAI-compatible chat completions API.
+    """
+    def __init__(self, base_url: str, api_key: str = "sk-no-key-needed", model: str = "local-model"):
+        from openai import OpenAI
+        self.client = OpenAI(api_key=api_key, base_url=base_url)
+        self.model = model

grid_agent/session.py

@@ -0,0 +1,268 @@
+"""
+SessionManager — opens and tracks GridEscrow v2 sessions on L2 Base.
+
+v2 changes:
+  - openSession() takes a 4th `sandbox` bool parameter
+  - Constructor takes feeRecipient + feeBps (no SDK impact, just ABI update)
+"""
+from __future__ import annotations
+
+import time
+from typing import Any
+
+from web3 import Web3
+from web3.contract import Contract
+
+from .types import SessionInfo
+from .wallet import WalletSigner
+
+_ESCROW_ABI: list[dict[str, Any]] = [
+    {
+        "name": "deposit",
+        "type": "function",
+        "stateMutability": "nonpayable",
+        "inputs": [{"name": "amount", "type": "uint96"}],
+        "outputs": [],
+    },
+    {
+        "name": "openSession",
+        "type": "function",
+        "stateMutability": "nonpayable",
+        "inputs": [
+            {"name": "sessionKey", "type": "address"},
+            {"name": "allowance",  "type": "uint96"},
+            {"name": "ttl",        "type": "uint40"},
+            {"name": "sandbox",    "type": "bool"},   # v2: test mode flag
+        ],
+        "outputs": [{"name": "sessionId", "type": "bytes32"}],
+    },
+    {
+        "name": "sessions",
+        "type": "function",
+        "stateMutability": "view",
+        "inputs": [{"name": "", "type": "bytes32"}],
+        "outputs": [
+            {"name": "agent",      "type": "address"},
+            {"name": "sessionKey", "type": "address"},
+            {"name": "allowance",  "type": "uint96"},
+            {"name": "spent",      "type": "uint96"},
+            {"name": "expiry",     "type": "uint40"},
+            {"name": "active",     "type": "bool"},
+            {"name": "sandbox",    "type": "bool"},
+        ],
+    },
+    {
+        "name": "closeSession",
+        "type": "function",
+        "stateMutability": "nonpayable",
+        "inputs": [{"name": "sessionId", "type": "bytes32"}],
+        "outputs": [],
+    },
+    {
+        "name": "balances",
+        "type": "function",
+        "stateMutability": "view",
+        "inputs": [{"name": "", "type": "address"}],
+        "outputs": [{"name": "", "type": "uint96"}],
+    },
+    {
+        "name": "vendorReputation",
+        "type": "function",
+        "stateMutability": "view",
+        "inputs": [{"name": "vendor", "type": "address"}],
+        "outputs": [{"name": "totalVolume", "type": "uint256"}],
+    },
+    {
+        "name": "feeBps",
+        "type": "function",
+        "stateMutability": "view",
+        "inputs": [],
+        "outputs": [{"name": "", "type": "uint16"}],
+    },
+    # Events (for log parsing)
+    {
+        "name": "SessionOpened",
+        "type": "event",
+        "inputs": [
+            {"name": "sessionId",  "type": "bytes32", "indexed": True},
+            {"name": "agent",      "type": "address",  "indexed": True},
+            {"name": "sessionKey", "type": "address",  "indexed": False},
+            {"name": "expiry",     "type": "uint40",   "indexed": False},
+            {"name": "sandbox",    "type": "bool",     "indexed": False},
+        ],
+    },
+]
+
+_ERC20_ABI: list[dict[str, Any]] = [
+    {
+        "name": "approve",
+        "type": "function",
+        "stateMutability": "nonpayable",
+        "inputs": [
+            {"name": "spender", "type": "address"},
+            {"name": "amount",  "type": "uint256"},
+        ],
+        "outputs": [{"name": "", "type": "bool"}],
+    },
+    {
+        "name": "allowance",
+        "type": "function",
+        "stateMutability": "view",
+        "inputs": [
+            {"name": "owner",   "type": "address"},
+            {"name": "spender", "type": "address"},
+        ],
+        "outputs": [{"name": "", "type": "uint256"}],
+    },
+]
+
+USDC_BASE_SEPOLIA = "0x036CbD53842c5426634e7929541eC2318f3dCF7e"
+USDC_BASE_MAINNET = "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913"
+
+
+class SessionManager:
+    """
+    Manages the full on-chain lifecycle of a GridEscrow v2 session.
+
+    Usage (sync — wrap in asyncio.to_thread() from async code):
+        mgr = SessionManager(rpc_url, contract_address, signer)
+        sess = mgr.open(allowance_usdc=5.0, ttl_seconds=3600)
+        # ... tool calls ...
+        mgr.close(sess.session_id)
+    """
+
+    def __init__(
+        self,
+        rpc_url: str,
+        contract_address: str,
+        signer: WalletSigner,
+        usdc_address: str = USDC_BASE_SEPOLIA,
+        sandbox: bool = False,
+    ) -> None:
+        self._w3 = Web3(Web3.HTTPProvider(rpc_url))
+        self._contract: Contract = self._w3.eth.contract(
+            address=Web3.to_checksum_address(contract_address),
+            abi=_ESCROW_ABI,
+        )
+        self._usdc: Contract = self._w3.eth.contract(
+            address=Web3.to_checksum_address(usdc_address),
+            abi=_ERC20_ABI,
+        )
+        self._signer           = signer
+        self._contract_address = contract_address
+        self._sandbox          = sandbox
+
+    # ── Public API ─────────────────────────────────────────────────────────────
+
+    def open(self, allowance_usdc: float, ttl_seconds: int = 3600) -> SessionInfo:
+        """
+        Full session open flow:
+          1. USDC approve (if needed)
+          2. deposit()
+          3. generate fresh session key
+          4. openSession() → sessionId bytes32
+        """
+        allowance_micro      = int(allowance_usdc * 1_000_000)
+        owner                = self._signer.owner_address
+        session_key_address  = self._signer.generate_session_key()
+
+        if not self._sandbox:
+            current = self._usdc.functions.allowance(
+                owner, self._contract_address
+            ).call()
+            if current < allowance_micro:
+                self._send_tx(
+                    self._usdc.functions.approve(self._contract_address, allowance_micro)
+                )
+            self._send_tx(self._contract.functions.deposit(allowance_micro))
+
+        receipt = self._send_tx(
+            self._contract.functions.openSession(
+                Web3.to_checksum_address(session_key_address),
+                allowance_micro,
+                ttl_seconds,
+                self._sandbox,
+            )
+        )
+
+        session_id = self._extract_session_id(receipt)
+        return SessionInfo(
+            session_id=session_id,
+            session_key_address=session_key_address,
+            allowance_micro=allowance_micro,
+            expiry=int(time.time()) + ttl_seconds,
+        )
+
+    def close(self, session_id: str) -> None:
+        session_id_bytes = bytes.fromhex(session_id.removeprefix("0x"))
+        self._send_tx(self._contract.functions.closeSession(session_id_bytes))
+
+    def sync(self, session_id: str) -> SessionInfo:
+        """
+        Synchronize session state from the blockchain.
+        Useful for recovering after a crash or if local state is lost.
+        """
+        session_id_bytes = bytes.fromhex(session_id.removeprefix("0x"))
+        data = self._contract.functions.sessions(session_id_bytes).call()
+        
+        # data format matches the 'sessions' view function output
+        return SessionInfo(
+            session_id=session_id,
+            session_key_address=data[1],
+            allowance_micro=data[2],
+            spent_micro=data[3],
+            expiry=data[4],
+            active=data[5],
+            sandbox=data[6],
+        )
+
+    def on_chain_balance(self) -> int:
+        return self._contract.functions.balances(self._signer.owner_address).call()
+
+    def vendor_reputation(self, vendor_address: str) -> int:
+        """Returns cumulative net USDC (micro-units) settled to this vendor."""
+        return self._contract.functions.vendorReputation(
+            Web3.to_checksum_address(vendor_address)
+        ).call()
+
+    def protocol_fee_bps(self) -> int:
+        return self._contract.functions.feeBps().call()
+
+    # ── Internals ──────────────────────────────────────────────────────────────
+
+    def _send_tx(self, fn: Any) -> Any:
+        owner = self._signer.owner_address
+        nonce = self._w3.eth.get_transaction_count(owner)
+        
+        # EIP-1559 Gas Estimation for Base L2
+        fee_history = self._w3.eth.fee_history(1, "latest", [25])
+        base_fee = fee_history["baseFeePerGas"][-1]
+        priority_fee = fee_history["reward"][0][0]
+        max_fee = (base_fee * 2) + priority_fee
+
+        tx    = fn.build_transaction({
+            "from":     owner,
+            "nonce":    nonce,
+            "maxFeePerGas": max_fee,
+            "maxPriorityFeePerGas": priority_fee,
+            "chainId": self._w3.eth.chain_id,
+        })
+        tx["gas"] = self._w3.eth.estimate_gas(tx)
+        private_key = self._signer._owner.key.hex()  # type: ignore[attr-defined]
+        signed = self._w3.eth.account.sign_transaction(tx, private_key=private_key)
+        tx_hash = self._w3.eth.send_raw_transaction(signed.raw_transaction)
+        return self._w3.eth.wait_for_transaction_receipt(tx_hash, timeout=60)
+
+    def _extract_session_id(self, receipt: Any) -> str:
+        for log in receipt.get("logs", []):
+            topics = log.get("topics", [])
+            if len(topics) >= 2:
+                raw = topics[1]
+                return "0x" + (raw.hex() if isinstance(raw, bytes) else raw)
+        # Deterministic fallback
+        block = self._w3.eth.get_block(receipt["blockNumber"])
+        raw_id = Web3.solidity_keccak(
+            ["address", "address", "uint256"],
+            [self._signer.owner_address, self._signer.session_address, block["timestamp"]],
+        )
+        return "0x" + raw_id.hex()

grid_agent/types.py

@@ -0,0 +1,83 @@
+"""Shared types for the Grid Agent SDK."""
+from __future__ import annotations
+from dataclasses import dataclass, field
+from typing import Any
+
+
+@dataclass
+class GridTool:
+    id: str
+    operation_id: str
+    method: str
+    path: str
+    pricing_amount: int       # USDC micro-units (6 dec)
+    pricing_currency: str
+    pricing_model: str
+    has_request_body: bool
+    parameters: list[dict[str, Any]] = field(default_factory=list)
+
+
+@dataclass
+class GridManifest:
+    name: str
+    version: str
+    base_url: str
+    gateway_url: str
+    contract_address: str
+    tools: list[GridTool]
+
+    @classmethod
+    def from_dict(cls, d: dict[str, Any]) -> "GridManifest":
+        tools = [
+            GridTool(
+                id=t["id"],
+                operation_id=t["operationId"],
+                method=t["method"],
+                path=t["path"],
+                pricing_amount=t["pricing"]["amount"],
+                pricing_currency=t["pricing"]["currency"],
+                pricing_model=t["pricing"]["model"],
+                has_request_body=t.get("hasRequestBody", False),
+                parameters=t.get("parameters", []),
+            )
+            for t in d.get("tools", [])
+        ]
+        return cls(
+            name=d["name"],
+            version=d["version"],
+            base_url=d["baseUrl"],
+            gateway_url=d.get("gatewayUrl", ""),
+            contract_address=d.get("contractAddress", ""),
+            tools=tools,
+        )
+
+
+@dataclass
+class SessionInfo:
+    session_id: str           # bytes32 hex
+    session_key_address: str  # hot wallet address
+    allowance_micro: int      # USDC micro-units earmarked
+    spent_micro: int = 0
+    expiry: int = 0           # unix timestamp
+
+    @property
+    def remaining_micro(self) -> int:
+        return self.allowance_micro - self.spent_micro
+
+
+@dataclass
+class X402Attestation:
+    """Signed payment attestation — matches the EIP-712 schema in GridEscrow."""
+    session_id: str
+    vendor: str
+    amount: int               # USDC micro-units
+    nonce: int
+    signature: str            # hex
+
+
+@dataclass
+class ToolCallResult:
+    call_id: str              # Unique block id for the tool call (used to match results to requests)
+    content: Any
+    cost_usdc_micro: int = 0
+    error: str | None = None

grid_agent/wallet.py

@@ -0,0 +1,152 @@
+"""
+WalletSigner — EIP-712 session key signing for x402 attestations.
+
+The agent holds two keys:
+  - owner_key:   The wallet that deposited USDC and opened the session on-chain.
+  - session_key: An ephemeral hot key that signs x402 attestations off-chain.
+
+Only the session key is used at call time. The owner key is only needed
+to call deposit() / openSession() on the contract.
+"""
+from __future__ import annotations
+
+import os
+import secrets
+import json
+from typing import Any
+
+from eth_account import Account
+from eth_account.messages import encode_typed_data, encode_defunct
+from eth_account.signers.local import LocalAccount
+
+
+# EIP-712 domain matches GridEscrow constructor exactly
+_DOMAIN_TYPE = [
+    {"name": "name",              "type": "string"},
+    {"name": "version",           "type": "string"},
+    {"name": "chainId",           "type": "uint256"},
+    {"name": "verifyingContract", "type": "address"},
+]
+
+_ATTESTATION_TYPE = [
+    {"name": "sessionId", "type": "bytes32"},
+    {"name": "vendor",    "type": "address"},
+    {"name": "amount",    "type": "uint96"},
+    {"name": "nonce",     "type": "uint64"},
+]
+
+
+class WalletSigner:
+    """
+    Manages the agent's owner wallet and ephemeral session key.
+    """
+
+    def __init__(
+        self,
+        owner_private_key: str,
+        chain_id: int = 84532,            # Base Sepolia default
+        session_private_key: str | None = None,
+    ) -> None:
+        self._owner: LocalAccount = Account.from_key(owner_private_key)
+        self._chain_id = chain_id
+        self._session: LocalAccount | None = (
+            Account.from_key(session_private_key) if session_private_key else None
+        )
+        self.__session_private_key = session_private_key
+
+    @classmethod
+    def from_env(cls) -> "WalletSigner":
+        """Construct from GRID_OWNER_KEY and optional GRID_SESSION_KEY env vars."""
+        owner_key = os.environ["GRID_OWNER_KEY"]
+        session_key = os.environ.get("GRID_SESSION_KEY")
+        chain_id = int(os.environ.get("GRID_CHAIN_ID", "84532"))
+        return cls(owner_key, chain_id, session_key)
+
+    # ── Session key ────────────────────────────────────────────────────────────
+
+    def generate_session_key(self) -> str:
+        """
+        Generate a fresh ephemeral session key.
+        Returns the address to register on-chain via openSession().
+        """
+        private_key = "0x" + secrets.token_hex(32)
+        self._session = Account.from_key(private_key)
+        self.__session_private_key = private_key
+        return self._session.address
+
+    def get_session_private_key(self) -> str | None:
+        """Explicitly export the hot key. Handle with extreme care."""
+        return self.__session_private_key
+
+    @property
+    def owner_address(self) -> str:
+        return self._owner.address
+
+    @property
+    def session_address(self) -> str:
+        if not self._session:
+            raise RuntimeError("No session key. Call generate_session_key() first.")
+        return self._session.address
+
+    # ── Signing ────────────────────────────────────────────────────────────────
+
+    def sign_attestation(
+        self,
+        *,
+        session_id: str,
+        vendor: str,
+        amount: int,
+        nonce: int,
+        contract_address: str,
+    ) -> str:
+        """
+        Produce an EIP-712 signature over an x402 attestation.
+        Uses the session key — never the owner key.
+
+        Returns the 65-byte hex signature (r + s + v).
+        """
+        if not self._session:
+            raise RuntimeError("No session key active.")
+
+        structured_data: dict[str, Any] = {
+            "domain": {
+                "name": "GridEscrow",
+                "version": "1",
+                "chainId": self._chain_id,
+                "verifyingContract": contract_address,
+            },
+            "types": {
+                "EIP712Domain": _DOMAIN_TYPE,
+                "X402Attestation": _ATTESTATION_TYPE,
+            },
+            "primaryType": "X402Attestation",
+            "message": {
+                "sessionId": bytes.fromhex(session_id.removeprefix("0x")),
+                "vendor": vendor,
+                "amount": amount,
+                "nonce": nonce,
+            },
+        }
+
+        signable = encode_typed_data(full_message=structured_data)
+        signed = self._session.sign_message(signable)
+        return signed.signature.hex()
+
+    def sign_mcp_call(self, tool: str, session_id: str, input_data: dict[str, Any]) -> str:
+        """
+        Sign the MCP tool call payload with the session key.
+        Used to prove to the Gateway that this specific call is authorised.
+        """
+        if not self._session:
+            raise RuntimeError("No session key active.")
+
+        # Consistent JSON formatting is critical for signature matching
+        message = json.dumps({
+            "tool":      tool,
+            "sessionId": session_id,
+            "input":     input_data,
+        }, separators=(',', ':'), sort_keys=True)
+
+        signable = encode_defunct(text=message)
+        signed = self._session.sign_message(signable)
+        return "0x" + signed.signature.hex()

grid_agent_sdk-1.0.0.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,11 @@
+grid_agent/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+grid_agent/agent.py,sha256=4nJDXJichgQk-anoU2C8NfYazUD5H0-HLCI8s4hRcvA,19911
+grid_agent/discovery.py,sha256=RH8ss_N6Hidzfs1t0ajo_poWa3cBEtjezJ-Uzc7rvc4,3431
+grid_agent/providers.py,sha256=XOaaHW1fWcifJojPsc7JP0UHZ24pyhOcvv_mw1JTu6I,5607
+grid_agent/session.py,sha256=36gZ4I879x0QsUfzNg3STqx-RLtwvqimSqbR7HLuqso,9677
+grid_agent/types.py,sha256=7gEo5UA_3o65n07TQYTPB8pLDxMPICNHQkLFbqnE7mU,2293
+grid_agent/wallet.py,sha256=XCR_UD-ZkRrLFHDjfyMkiHEJqlzJj2oVFsPv84GM86g,5388
+grid_agent_sdk-1.0.0.dist-info/METADATA,sha256=SyWnzyEJtIMARuguQtKWSkM2-p8s5VzXDtgsX58woq8,342
+grid_agent_sdk-1.0.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+grid_agent_sdk-1.0.0.dist-info/top_level.txt,sha256=huV_R8YO8bEKdPOOqQHGxCUyGvJlmj2Diwd5lf03D-g,11
+grid_agent_sdk-1.0.0.dist-info/RECORD,,

grid_agent_sdk-1.0.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

grid_agent_sdk-1.0.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+grid_agent