agent0-sdk 1.4.0__py3-none-any.whl

agent0_sdk/core/ipfs_client.py

@@ -0,0 +1,357 @@
+"""
+IPFS client for decentralized storage with support for multiple providers:
+- Local IPFS nodes
+- Pinata IPFS pinning service
+- Filecoin Pin service
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import subprocess
+import tempfile
+import os
+import time
+from typing import Any, Dict, Optional
+
+try:
+    import ipfshttpclient
+except ImportError:
+    ipfshttpclient = None
+
+logger = logging.getLogger(__name__)
+
+
+class IPFSClient:
+    """Client for IPFS operations supporting multiple providers (local IPFS, Pinata, Filecoin Pin)."""
+
+    def __init__(
+        self, 
+        url: Optional[str] = None, 
+        filecoin_pin_enabled: bool = False, 
+        filecoin_private_key: Optional[str] = None,
+        pinata_enabled: bool = False,
+        pinata_jwt: Optional[str] = None
+    ):
+        """Initialize IPFS client.
+        
+        Args:
+            url: IPFS node URL (e.g., "http://localhost:5001")
+            filecoin_pin_enabled: Enable Filecoin Pin integration
+            filecoin_private_key: Private key for Filecoin Pin operations
+            pinata_enabled: Enable Pinata integration
+            pinata_jwt: JWT token for Pinata authentication
+        """
+        self.url = url
+        self.filecoin_pin_enabled = filecoin_pin_enabled
+        self.filecoin_private_key = filecoin_private_key
+        self.pinata_enabled = pinata_enabled
+        self.pinata_jwt = pinata_jwt
+        self.client = None
+        
+        if pinata_enabled:
+            self._verify_pinata_jwt()
+        elif filecoin_pin_enabled:
+            self._verify_filecoin_pin_installation()
+        elif url and ipfshttpclient:
+            self.client = ipfshttpclient.connect(url)
+        elif url and not ipfshttpclient:
+            raise ImportError(
+                "IPFS dependencies not installed. Install with: pip install ipfshttpclient"
+            )
+
+    def _verify_pinata_jwt(self):
+        """Verify Pinata JWT is provided."""
+        if not self.pinata_jwt:
+            raise ValueError("pinata_jwt is required when pinata_enabled=True")
+        logger.debug("Pinata JWT configured")
+
+    def _verify_filecoin_pin_installation(self):
+        """Verify filecoin-pin CLI is installed."""
+        try:
+            result = subprocess.run(
+                ['filecoin-pin', '--version'], 
+                capture_output=True, 
+                text=True, 
+                check=True
+            )
+            logger.debug(f"Filecoin Pin CLI found: {result.stdout.strip()}")
+        except (subprocess.CalledProcessError, FileNotFoundError):
+            raise RuntimeError(
+                "filecoin-pin CLI not found. "
+                "Install it from: https://github.com/filecoin-project/filecoin-pin?tab=readme-ov-file#cli"
+            )
+
+    def _pin_to_filecoin(self, file_path: str) -> str:
+        """Pin file to Filecoin using filecoin-pin CLI following the official guide."""
+        # Check if environment file exists (as per guide)
+        env_file = os.path.expanduser("~/.filecoin-pin-env")
+        if not os.path.exists(env_file):
+            raise RuntimeError(
+                "Filecoin Pin environment file not found. Please run:\n"
+                "  1. cast wallet new\n"
+                "  2. Create ~/.filecoin-pin-env with PRIVATE_KEY and WALLET_ADDRESS\n"
+                "  3. Get testnet tokens from https://faucet.calibnet.chainsafe-fil.io/\n"
+                "  4. filecoin-pin payments setup --auto (one-time setup)"
+            )
+        
+        # Load environment from file (as per guide)
+        env = os.environ.copy()
+        try:
+            with open(env_file, 'r') as f:
+                for line in f:
+                    if line.startswith('export '):
+                        key, value = line[7:].strip().split('=', 1)
+                        env[key] = value.strip('"\'')
+        except Exception as e:
+            raise RuntimeError(f"Error loading Filecoin Pin environment: {e}")
+        
+        if 'PRIVATE_KEY' not in env:
+            raise RuntimeError("PRIVATE_KEY not found in environment file")
+        
+        try:
+            import time
+            cmd = ['filecoin-pin', 'add', '--bare', file_path]
+            logger.debug(f"Running Filecoin CLI command: {' '.join(cmd)}")
+            
+            start_time = time.time()
+            result = subprocess.run(
+                cmd,
+                capture_output=True,
+                text=True,
+                check=True,
+                env=env
+            )
+            elapsed_time = time.time() - start_time
+            logger.debug(f"Filecoin CLI completed in {elapsed_time:.2f} seconds")
+            
+            # Parse the output to extract Root CID
+            lines = result.stdout.strip().split('\n')
+            for line in lines:
+                if 'Root CID:' in line:
+                    return line.split('Root CID:')[1].strip()
+            
+            # Fallback: return the first line if parsing fails
+            return lines[0] if lines else "unknown"
+            
+        except subprocess.CalledProcessError as e:
+            # Handle specific error cases from the guide
+            stderr_lower = e.stderr.lower()
+            if "insufficient fil" in stderr_lower or "balance" in stderr_lower:
+                raise RuntimeError(
+                    f"Insufficient FIL for gas fees: {e.stderr}\n"
+                    "Get test FIL from: https://faucet.calibnet.chainsafe-fil.io/\n"
+                    "Then run: filecoin-pin payments setup --auto (one-time setup)"
+                )
+            elif "payment" in stderr_lower or "setup" in stderr_lower:
+                raise RuntimeError(
+                    f"Payment setup required: {e.stderr}\n"
+                    "Run: filecoin-pin payments setup --auto (one-time setup)"
+                )
+            else:
+                raise RuntimeError(f"Filecoin Pin 'add' command failed: {e.stderr}")
+
+    def _pin_to_local_ipfs(self, data: str, **kwargs) -> str:
+        """Pin data to local IPFS node."""
+        if not self.client:
+            raise RuntimeError("No IPFS client available")
+        result = self.client.add_str(data, **kwargs)
+        # add_str returns the CID directly as a string
+        return result if isinstance(result, str) else result['Hash']
+
+    def _pin_to_pinata(self, data: str, file_name: str = "file.json") -> str:
+        """Pin data to Pinata using JWT authentication with v3 API."""
+        import requests
+        import tempfile
+        import os
+        
+        # Pinata v3 API endpoint for uploading files
+        url = "https://uploads.pinata.cloud/v3/files"
+        
+        # Pinata authentication using JWT
+        headers = {
+            "Authorization": f"Bearer {self.pinata_jwt}"
+        }
+        
+        # Create a temporary file with the data
+        with tempfile.NamedTemporaryFile(mode='w', suffix='.json', delete=False) as f:
+            f.write(data)
+            temp_path = f.name
+        
+        try:
+            logger.debug("Pinning to Pinata v3 (public)")
+            
+            # Prepare the file for upload with public network setting
+            with open(temp_path, 'rb') as file:
+                files = {
+                    'file': (file_name, file, 'application/json')
+                }
+                
+                # Add network parameter to make file public
+                data = {
+                    'network': 'public'
+                }
+                
+                response = requests.post(url, headers=headers, files=files, data=data)
+            
+            response.raise_for_status()
+            result = response.json()
+            
+            # v3 API returns different structure - CID is nested in data
+            cid = None
+            if 'data' in result and 'cid' in result['data']:
+                cid = result['data']['cid']
+            elif 'cid' in result:
+                cid = result['cid']
+            elif 'IpfsHash' in result:
+                cid = result['IpfsHash']
+                
+            if not cid:
+                error_msg = f"No CID returned from Pinata. Response: {result}"
+                logger.error(error_msg)
+                raise ValueError(error_msg)
+            logger.debug(f"Pinned to Pinata v3: {cid}")
+            return cid
+        except requests.exceptions.HTTPError as e:
+            error_details = ""
+            if hasattr(e, 'response') and e.response is not None:
+                error_details = f" Response: {e.response.text}"
+            error_msg = f"Failed to pin to Pinata: HTTP {e}{error_details}"
+            logger.error(error_msg)
+            raise RuntimeError(error_msg)
+        except Exception as e:
+            error_msg = f"Failed to pin to Pinata: {e}"
+            logger.error(error_msg)
+            raise RuntimeError(error_msg)
+        finally:
+            # Clean up temporary file
+            try:
+                os.unlink(temp_path)
+            except:
+                pass
+
+    def add(self, data: str, **kwargs) -> str:
+        """Add data to IPFS and return CID."""
+        file_name = kwargs.pop("file_name", None)
+        if self.pinata_enabled:
+            return self._pin_to_pinata(data, file_name=file_name or "file.json")
+        elif self.filecoin_pin_enabled:
+            # Create temporary file for Filecoin Pin
+            with tempfile.NamedTemporaryFile(mode='w', suffix='.txt', delete=False) as f:
+                f.write(data)
+                temp_path = f.name
+            
+            try:
+                cid = self._pin_to_filecoin(temp_path)
+                return cid
+            finally:
+                os.unlink(temp_path)
+        else:
+            return self._pin_to_local_ipfs(data, **kwargs)
+
+    def add_file(self, filepath: str, **kwargs) -> str:
+        """Add file to IPFS and return CID."""
+        file_name = kwargs.pop("file_name", None)
+        if self.pinata_enabled:
+            # Read file and send to Pinata
+            with open(filepath, 'r') as f:
+                data = f.read()
+            return self._pin_to_pinata(data, file_name=file_name or "file.json")
+        elif self.filecoin_pin_enabled:
+            return self._pin_to_filecoin(filepath)
+        else:
+            if not self.client:
+                raise RuntimeError("No IPFS client available")
+            result = self.client.add(filepath, **kwargs)
+            return result['Hash']
+
+    def get(self, cid: str) -> str:
+        """Get data from IPFS by CID."""
+        # Extract CID from IPFS URL if needed
+        if cid.startswith("ipfs://"):
+            cid = cid[7:]  # Remove "ipfs://" prefix
+        
+        # Pinata and Filecoin Pin both use IPFS gateways for retrieval
+        if self.pinata_enabled or self.filecoin_pin_enabled:
+            # Use IPFS gateways for retrieval
+            import requests
+            try:
+                # Try multiple gateways for reliability, prioritizing Pinata v3 gateway
+                gateways = [
+                    f"https://gateway.pinata.cloud/ipfs/{cid}",
+                    f"https://ipfs.io/ipfs/{cid}",
+                    f"https://dweb.link/ipfs/{cid}"
+                ]
+                
+                for gateway in gateways:
+                    try:
+                        response = requests.get(gateway, timeout=10)
+                        response.raise_for_status()
+                        return response.text
+                    except Exception:
+                        continue
+                
+                raise RuntimeError(f"Failed to retrieve data from all IPFS gateways")
+            except Exception as e:
+                raise RuntimeError(f"Failed to retrieve data from IPFS gateway: {e}")
+        else:
+            if not self.client:
+                raise RuntimeError("No IPFS client available")
+            return self.client.cat(cid).decode('utf-8')
+
+    def get_json(self, cid: str) -> Dict[str, Any]:
+        """Get JSON data from IPFS by CID."""
+        data = self.get(cid)
+        return json.loads(data)
+
+    def pin(self, cid: str) -> Dict[str, Any]:
+        """Pin a CID to local node."""
+        if self.filecoin_pin_enabled:
+            # Filecoin Pin automatically pins data, so this is a no-op
+            return {"pinned": [cid]}
+        else:
+            if not self.client:
+                raise RuntimeError("No IPFS client available")
+            return self.client.pin.add(cid)
+
+    def unpin(self, cid: str) -> Dict[str, Any]:
+        """Unpin a CID from local node."""
+        if self.filecoin_pin_enabled:
+            # Filecoin Pin doesn't support unpinning in the same way
+            # This is a no-op for Filecoin Pin
+            return {"unpinned": [cid]}
+        else:
+            if not self.client:
+                raise RuntimeError("No IPFS client available")
+            return self.client.pin.rm(cid)
+
+    def add_json(self, data: Dict[str, Any], **kwargs) -> str:
+        """Add JSON data to IPFS and return CID."""
+        json_str = json.dumps(data, indent=2)
+        return self.add(json_str, **kwargs)
+
+    def addRegistrationFile(self, registrationFile: "RegistrationFile", chainId: Optional[int] = None, identityRegistryAddress: Optional[str] = None, **kwargs) -> str:
+        """Add registration file to IPFS and return CID."""
+        data = registrationFile.to_dict(chain_id=chainId, identity_registry_address=identityRegistryAddress)
+        return self.add_json(data, file_name="agent-registration.json", **kwargs)
+
+    def getRegistrationFile(self, cid: str) -> "RegistrationFile":
+        """Get registration file from IPFS by CID."""
+        from .models import RegistrationFile
+        data = self.get_json(cid)
+        return RegistrationFile.from_dict(data)
+
+    def addFeedbackFile(self, feedbackData: Dict[str, Any], **kwargs) -> str:
+        """Add feedback file to IPFS and return CID."""
+        return self.add_json(feedbackData, file_name="feedback.json", **kwargs)
+
+    def getFeedbackFile(self, cid: str) -> Dict[str, Any]:
+        """Get feedback file from IPFS by CID."""
+        return self.get_json(cid)
+
+    def close(self):
+        """Close IPFS client connection."""
+        if hasattr(self.client, 'close'):
+            self.client.close()
+

agent0_sdk/core/models.py

@@ -0,0 +1,303 @@
+"""
+Core data models for the Agent0 SDK.
+"""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import Any, Dict, List, Optional, Union, Literal
+from datetime import datetime
+
+
+# Type aliases
+AgentId = str  # "chainId:tokenId" (e.g., "8453:1234") or just tokenId when chain is implicit
+ChainId = int
+Address = str  # 0x-hex
+URI = str  # https://... or ipfs://...
+CID = str  # IPFS CID (if used)
+Timestamp = int  # unix seconds
+IdemKey = str  # idempotency key for write ops
+
+
+class EndpointType(Enum):
+    """Types of endpoints that agents can advertise."""
+    MCP = "MCP"
+    A2A = "A2A"
+    ENS = "ENS"
+    DID = "DID"
+    WALLET = "wallet"
+    OASF = "OASF"
+
+
+class TrustModel(Enum):
+    """Trust models supported by the SDK."""
+    REPUTATION = "reputation"
+    CRYPTO_ECONOMIC = "crypto-economic"
+    TEE_ATTESTATION = "tee-attestation"
+
+
+@dataclass
+class Endpoint:
+    """Represents an agent endpoint."""
+    type: EndpointType
+    value: str  # endpoint value (URL, name, DID, ENS)
+    meta: Dict[str, Any] = field(default_factory=dict)  # optional metadata
+
+
+@dataclass
+class RegistrationFile:
+    """Agent registration file structure."""
+    agentId: Optional[AgentId] = None  # None until minted
+    agentURI: Optional[URI] = None  # where this file is (or will be) published
+    name: str = ""
+    description: str = ""
+    image: Optional[URI] = None
+    walletAddress: Optional[Address] = None
+    walletChainId: Optional[int] = None  # Chain ID for the wallet address
+    endpoints: List[Endpoint] = field(default_factory=list)
+    trustModels: List[Union[TrustModel, str]] = field(default_factory=list)
+    owners: List[Address] = field(default_factory=list)  # from chain (read-only, hydrated)
+    operators: List[Address] = field(default_factory=list)  # from chain (read-only, hydrated)
+    active: bool = False  # SDK extension flag
+    x402support: bool = False  # Binary flag for x402 payment support
+    metadata: Dict[str, Any] = field(default_factory=dict)  # arbitrary, SDK-managed
+    updatedAt: Timestamp = field(default_factory=lambda: int(datetime.now().timestamp()))
+
+    def __str__(self) -> str:
+        """String representation as JSON."""
+        # Use stored registry info if available
+        chain_id = getattr(self, '_chain_id', None)
+        registry_address = getattr(self, '_registry_address', None)
+        return json.dumps(self.to_dict(chain_id, registry_address), indent=2, default=str)
+    
+    def __repr__(self) -> str:
+        """Developer representation."""
+        return f"RegistrationFile(agentId={self.agentId}, agentURI={self.agentURI}, name={self.name})"
+    
+    def to_dict(self, chain_id: Optional[int] = None, identity_registry_address: Optional[str] = None) -> Dict[str, Any]:
+        """Convert to dictionary for JSON serialization."""
+        # Build endpoints array
+        endpoints = []
+        for endpoint in self.endpoints:
+            endpoint_dict = {
+                "name": endpoint.type.value,
+                "endpoint": endpoint.value,
+                **endpoint.meta
+            }
+            endpoints.append(endpoint_dict)
+        
+        # Note: agentWallet is no longer included in endpoints array.
+        # It's now a reserved on-chain metadata key managed via Agent.setWallet().
+        
+        # Build registrations array
+        registrations = []
+        if self.agentId:
+            agent_id_int = int(self.agentId.split(":")[-1]) if ":" in self.agentId else int(self.agentId)
+            agent_registry = f"eip155:{chain_id}:{identity_registry_address}" if chain_id and identity_registry_address else f"eip155:1:{{identityRegistry}}"
+            registrations.append({
+                "agentId": agent_id_int,
+                "agentRegistry": agent_registry
+            })
+        
+        return {
+            "type": "https://eips.ethereum.org/EIPS/eip-8004#registration-v1",
+            "name": self.name,
+            "description": self.description,
+            "image": self.image,
+            "services": endpoints,
+            "registrations": registrations,
+            "supportedTrust": [tm.value if isinstance(tm, TrustModel) else tm for tm in self.trustModels],
+            "active": self.active,
+            "x402Support": self.x402support,  # Use camelCase in JSON output per spec
+            "updatedAt": self.updatedAt,
+        }
+
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> RegistrationFile:
+        """Create from dictionary."""
+        endpoints = []
+        raw_services = data.get("services", data.get("endpoints", []))
+        for ep_data in raw_services:
+            name = ep_data["name"]
+            # Special handling for agentWallet - it's not a standard endpoint type
+            if name == "agentWallet":
+                # Skip agentWallet endpoints as they're handled separately via walletAddress field
+                continue
+            
+            ep_type = EndpointType(name)
+            ep_value = ep_data["endpoint"]
+            ep_meta = {k: v for k, v in ep_data.items() if k not in ["name", "endpoint"]}
+            endpoints.append(Endpoint(type=ep_type, value=ep_value, meta=ep_meta))
+
+        trust_models = []
+        for tm in data.get("supportedTrust", []):
+            try:
+                trust_models.append(TrustModel(tm))
+            except ValueError:
+                trust_models.append(tm)  # custom string
+
+        return cls(
+            agentId=data.get("agentId"),
+            agentURI=data.get("agentURI"),
+            name=data.get("name", ""),
+            description=data.get("description", ""),
+            image=data.get("image"),
+            walletAddress=data.get("walletAddress"),
+            walletChainId=data.get("walletChainId"),
+            endpoints=endpoints,
+            trustModels=trust_models,
+            active=data.get("active", False),
+            x402support=data.get("x402Support", data.get("x402support", False)),  # Handle both camelCase and lowercase
+            metadata=data.get("metadata", {}),
+            updatedAt=data.get("updatedAt", int(datetime.now().timestamp())),
+        )
+
+
+@dataclass
+class AgentSummary:
+    """Summary information for agent discovery and search."""
+    chainId: ChainId
+    agentId: AgentId
+    name: str
+    image: Optional[URI]
+    description: str
+    owners: List[Address]
+    operators: List[Address]
+    mcp: bool
+    a2a: bool
+    ens: Optional[str]
+    did: Optional[str]
+    walletAddress: Optional[Address]
+    supportedTrusts: List[str]  # normalized string keys
+    a2aSkills: List[str]
+    mcpTools: List[str]
+    mcpPrompts: List[str]
+    mcpResources: List[str]
+    active: bool
+    x402support: bool = False
+    extras: Dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass
+class Feedback:
+    """Feedback data structure."""
+    id: tuple  # (agentId, clientAddress, feedbackIndex) - tuple for efficiency
+    agentId: AgentId
+    reviewer: Address
+    # ReputationRegistry Jan 2026: decimal value computed as (value:int256 / 10^valueDecimals).
+    # SDK exposes ONLY the computed value.
+    value: Optional[float]
+    tags: List[str] = field(default_factory=list)
+    text: Optional[str] = None
+    context: Optional[Dict[str, Any]] = None
+    proofOfPayment: Optional[Dict[str, Any]] = None
+    fileURI: Optional[URI] = None
+    endpoint: Optional[str] = None  # Endpoint URI associated with feedback
+    createdAt: Timestamp = field(default_factory=lambda: int(datetime.now().timestamp()))
+    answers: List[Dict[str, Any]] = field(default_factory=list)
+    isRevoked: bool = False
+    
+    # Off-chain only fields (not stored on blockchain)
+    capability: Optional[str] = None  # MCP capability: "prompts", "resources", "tools", "completions"
+    name: Optional[str] = None  # MCP tool/resource name
+    skill: Optional[str] = None  # A2A skill
+    task: Optional[str] = None  # A2A task
+    
+    def __post_init__(self):
+        """Validate and set ID after initialization."""
+        if isinstance(self.id, str):
+            # Convert string ID to tuple
+            parsed_id = self.from_id_string(self.id)
+            self.id = parsed_id
+        elif not isinstance(self.id, tuple) or len(self.id) != 3:
+            raise ValueError(f"Feedback ID must be tuple of (agentId, clientAddress, feedbackIndex), got: {self.id}")
+    
+    @property
+    def id_string(self) -> str:
+        """Get string representation of ID for external APIs."""
+        return f"{self.id[0]}:{self.id[1]}:{self.id[2]}"
+    
+    @classmethod
+    def create_id(cls, agentId: AgentId, clientAddress: Address, feedbackIndex: int) -> tuple:
+        """Create feedback ID tuple with normalized address."""
+        # Normalize address to lowercase for consistency
+        # Ethereum addresses are case-insensitive, but we store them in lowercase
+        if isinstance(clientAddress, str) and (clientAddress.startswith("0x") or clientAddress.startswith("0X")):
+            normalized_address = "0x" + clientAddress[2:].lower()
+        else:
+            normalized_address = clientAddress.lower() if isinstance(clientAddress, str) else str(clientAddress).lower()
+        return (agentId, normalized_address, feedbackIndex)
+    
+    @classmethod
+    def from_id_string(cls, id_string: str) -> tuple:
+        """Parse feedback ID from string.
+        
+        Format: agentId:clientAddress:feedbackIndex
+        Note: agentId may contain colons (e.g., "11155111:123"), so we need to split from the right.
+        """
+        parts = id_string.rsplit(":", 2)  # Split from right, max 2 splits
+        if len(parts) != 3:
+            raise ValueError(f"Invalid feedback ID format: {id_string}")
+        
+        try:
+            feedback_index = int(parts[2])
+        except ValueError:
+            raise ValueError(f"Invalid feedback index: {parts[2]}")
+        
+        # Normalize address to lowercase for consistency
+        client_address = parts[1]
+        if isinstance(client_address, str) and (client_address.startswith("0x") or client_address.startswith("0X")):
+            normalized_address = "0x" + client_address[2:].lower()
+        else:
+            normalized_address = client_address.lower() if isinstance(client_address, str) else str(client_address).lower()
+        
+        return (parts[0], normalized_address, feedback_index)
+
+
+@dataclass
+class SearchParams:
+    """Parameters for agent search."""
+    chains: Optional[Union[List[ChainId], Literal["all"]]] = None
+    name: Optional[str] = None  # case-insensitive substring
+    description: Optional[str] = None  # semantic; vector distance < threshold
+    owners: Optional[List[Address]] = None
+    operators: Optional[List[Address]] = None
+    mcp: Optional[bool] = None
+    a2a: Optional[bool] = None
+    ens: Optional[str] = None  # exact, case-insensitive
+    did: Optional[str] = None  # exact
+    walletAddress: Optional[Address] = None
+    supportedTrust: Optional[List[str]] = None
+    a2aSkills: Optional[List[str]] = None
+    mcpTools: Optional[List[str]] = None
+    mcpPrompts: Optional[List[str]] = None
+    mcpResources: Optional[List[str]] = None
+    active: Optional[bool] = True
+    x402support: Optional[bool] = None
+    deduplicate_cross_chain: bool = False  # Deduplicate same agent across chains
+
+    def to_dict(self) -> Dict[str, Any]:
+        """Convert to dictionary, filtering out None values."""
+        return {k: v for k, v in self.__dict__.items() if v is not None}
+
+
+@dataclass
+class SearchFeedbackParams:
+    """Parameters for feedback search."""
+    agents: Optional[List[AgentId]] = None
+    tags: Optional[List[str]] = None
+    reviewers: Optional[List[Address]] = None
+    capabilities: Optional[List[str]] = None
+    skills: Optional[List[str]] = None
+    tasks: Optional[List[str]] = None
+    names: Optional[List[str]] = None  # MCP tool/resource/prompt names
+    endpoint: Optional[str] = None  # Filter by endpoint URI
+    minValue: Optional[float] = None
+    maxValue: Optional[float] = None
+    includeRevoked: bool = False
+    
+    def to_dict(self) -> Dict[str, Any]:
+        """Convert to dictionary, filtering out None values."""
+        return {k: v for k, v in self.__dict__.items() if v is not None}