observer_sdk.py

"""
Observer Protocol SDK for Python / FastAPI

Provides reputation checks and middleware for agent-to-agent payments.
Works with x402, Lightning, L402, and any payment rail.
"""

import httpx
from typing import Optional, Dict, Any, Callable
from functools import wraps
import time

DEFAULT_BASE_URL = "https://api.agenticterminal.ai"
DEFAULT_FALLBACK = "review"


class ReputationData:
    """Reputation data object for dependency injection."""
    
    def __init__(self, data: Dict[str, Any]):
        self._data = data
        self.agent_id = data.get("agent_id") or data.get("wallet_address")
        self.verified = data.get("verified", False)
        self.reputation_score = data.get("reputation_score", 0)
        self.trust_tier = data.get("trust_tier", "unknown")
        self.payment_history = data.get("payment_history")
        self.risk_signals = data.get("risk_signals", {})
        self.suggested_action = data.get("suggested_action", "review")
        self._error = data.get("_error")
    
    def __repr__(self):
        return f"<ReputationData tier={self.trust_tier} score={self.reputation_score}>"


class ObserverClient:
    """
    Observer Protocol client for reputation checks.
    
    Usage:
        observer = ObserverClient()
        reputation = await observer.get_reputation("agent-123")
    """
    
    def __init__(self, api_key: Optional[str] = None, base_url: Optional[str] = None):
        self.api_key = api_key
        self.base_url = base_url or DEFAULT_BASE_URL
        self._cache: Dict[str, Dict[str, Any]] = {}
    
    def _get_cache(self, key: str) -> Optional[Dict[str, Any]]:
        """Get cached data if not expired."""
        cached = self._cache.get(key)
        if cached and cached["expires"] > time.time():
            return cached["data"]
        return None
    
    def _set_cache(self, key: str, data: Dict[str, Any], ttl_seconds: int):
        """Cache data with TTL."""
        self._cache[key] = {
            "data": data,
            "expires": time.time() + ttl_seconds
        }
    
    async def get_reputation(self, agent_id: str) -> Dict[str, Any]:
        """
        Get reputation for an agent by ID.
        
        Args:
            agent_id: The Observer Protocol agent ID
            
        Returns:
            Reputation data dictionary
        """
        cache_key = f"agent:{agent_id}"
        cached = self._get_cache(cache_key)
        if cached:
            return cached
        
        headers = {}
        if self.api_key:
            headers["Authorization"] = f"Bearer {self.api_key}"
        
        try:
            async with httpx.AsyncClient() as client:
                response = await client.get(
                    f"{self.base_url}/observer/reputation/{agent_id}",
                    headers=headers,
                    timeout=10.0
                )
            
            if response.status_code == 404:
                fallback = {
                    "agent_id": agent_id,
                    "verified": False,
                    "reputation_score": 0,
                    "trust_tier": "unknown",
                    "payment_history": None,
                    "risk_signals": {"known_bad": False},
                    "suggested_action": "review",
                    "cache_ttl_seconds": 60
                }
                self._set_cache(cache_key, fallback, 60)
                return fallback
            
            response.raise_for_status()
            data = response.json()
            self._set_cache(cache_key, data, data.get("cache_ttl_seconds", 300))
            return data
            
        except Exception as e:
            # Network error - return review fallback
            return {
                "agent_id": agent_id,
                "verified": False,
                "reputation_score": 0,
                "trust_tier": "unknown",
                "payment_history": None,
                "risk_signals": {"known_bad": False},
                "suggested_action": "review",
                "cache_ttl_seconds": 60,
                "_error": str(e)
            }
    
    async def get_reputation_by_wallet(self, address: str) -> Dict[str, Any]:
        """
        Get reputation for an agent by wallet address.
        
        Args:
            address: EVM wallet address
            
        Returns:
            Reputation data dictionary
        """
        cache_key = f"wallet:{address.lower()}"
        cached = self._get_cache(cache_key)
        if cached:
            return cached
        
        headers = {}
        if self.api_key:
            headers["Authorization"] = f"Bearer {self.api_key}"
        
        try:
            async with httpx.AsyncClient() as client:
                response = await client.get(
                    f"{self.base_url}/observer/reputation/wallet/{address}",
                    headers=headers,
                    timeout=10.0
                )
            
            if response.status_code == 404:
                fallback = {
                    "wallet_address": address,
                    "verified": False,
                    "reputation_score": 0,
                    "trust_tier": "unknown",
                    "payment_history": None,
                    "risk_signals": {"known_bad": False},
                    "suggested_action": "review",
                    "cache_ttl_seconds": 60
                }
                self._set_cache(cache_key, fallback, 60)
                return fallback
            
            response.raise_for_status()
            data = response.json()
            self._set_cache(cache_key, data, data.get("cache_ttl_seconds", 300))
            return data
            
        except Exception as e:
            return {
                "wallet_address": address,
                "verified": False,
                "reputation_score": 0,
                "trust_tier": "unknown",
                "payment_history": None,
                "risk_signals": {"known_bad": False},
                "suggested_action": "review",
                "cache_ttl_seconds": 60,
                "_error": str(e)
            }
    
    async def reputation_middleware(self, request, call_next):
        """
        ASGI middleware for reputation checking.
        
        Usage with FastAPI:
            app.middleware("http")(observer.reputation_middleware)
        """
        from starlette.requests import Request
        
        # Extract agent identity from headers
        agent_id = request.headers.get("x-observer-agent-id")
        wallet_address = request.headers.get("x-agent-wallet")
        
        # For POST requests, check body for x402 payment proof
        x402_from = None
        if request.method == "POST":
            try:
                body = await request.json()
                x402_from = body.get("from") or body.get("payment", {}).get("from")
            except:
                pass
        
        identity = None
        identity_type = None
        
        if agent_id:
            identity = agent_id
            identity_type = "agent"
        elif wallet_address:
            identity = wallet_address
            identity_type = "wallet"
        elif x402_from:
            identity = x402_from
            identity_type = "wallet"
        
        # Fetch reputation if identity found
        reputation = None
        if identity:
            try:
                if identity_type == "agent":
                    reputation = await self.get_reputation(identity)
                else:
                    reputation = await self.get_reputation_by_wallet(identity)
            except Exception:
                reputation = {"suggested_action": "review", "trust_tier": "unknown"}
        
        # Attach to request state
        request.state.observer_reputation = ReputationData(reputation) if reputation else None
        
        response = await call_next(request)
        return response


def require_reputation(min_tier: str = "unknown", policy: str = "lenient"):
    """
    FastAPI dependency for requiring minimum reputation tier.
    
    Usage:
        @app.get("/api/data")
        async def get_data(reputation: ReputationData = Depends(require_reputation(min_tier="active"))):
            return {"data": "..."}
    
    Trust tiers (lowest to highest): unknown < new < active < established < trusted
    """
    from fastapi import Request, HTTPException
    
    TIER_ORDER = ["unknown", "new", "active", "established", "trusted"]
    
    async def dependency(request: Request) -> ReputationData:
        reputation = getattr(request.state, "observer_reputation", None)
        
        if reputation is None:
            # No reputation data - check if we need to fetch it
            raise HTTPException(
                status_code=400,
                detail="Reputation check required. Add ObserverClient middleware."
            )
        
        # Check tier requirement
        current_idx = TIER_ORDER.index(reputation.trust_tier) if reputation.trust_tier in TIER_ORDER else 0
        min_idx = TIER_ORDER.index(min_tier) if min_tier in TIER_ORDER else 0
        
        if current_idx < min_idx:
            raise HTTPException(
                status_code=403,
                detail=f"Insufficient reputation tier. Required: {min_tier}, Got: {reputation.trust_tier}"
            )
        
        # Check suggested action
        if reputation.suggested_action == "reject":
            raise HTTPException(
                status_code=403,
                detail="Access denied: Agent reputation insufficient"
            )
        
        if reputation.suggested_action == "review" and policy == "strict":
            raise HTTPException(
                status_code=402,
                detail={
                    "error": "Payment requires review",
                    "reason": "Agent not verified in Observer Protocol",
                    "registration_url": "https://agenticterminal.ai/observer/register"
                }
            )
        
        return reputation
    
    return dependency


# Convenience function for simple usage
def create_middleware(api_key: Optional[str] = None, base_url: Optional[str] = None):
    """Create a middleware function for simple usage."""
    client = ObserverClient(api_key=api_key, base_url=base_url)
    return client.reputation_middleware