agent0-sdk 0.2.2__py3-none-any.whl → 0.5__py3-none-any.whl

agent0_sdk/core/models.py

@@ -7,7 +7,7 @@ from __future__ import annotations
 import json
 from dataclasses import dataclass, field
 from enum import Enum
-from typing import Any, Dict, List, Optional, Union
+from typing import Any, Dict, List, Optional, Union, Literal
 from datetime import datetime
 
 
@@ -28,6 +28,7 @@ class EndpointType(Enum):
     ENS = "ENS"
     DID = "DID"
     WALLET = "wallet"
+    OASF = "OASF"
 
 
 class TrustModel(Enum):
@@ -87,23 +88,8 @@ class RegistrationFile:
             }
             endpoints.append(endpoint_dict)
         
-        # Add walletAddress as an endpoint if present
-        if self.walletAddress:
-            # Use stored walletChainId if available, otherwise extract from agentId
-            chain_id_for_wallet = self.walletChainId
-            if chain_id_for_wallet is None:
-                # Extract chain ID from agentId if available, otherwise use 1 as default
-                chain_id_for_wallet = 1  # Default to mainnet
-                if self.agentId and ":" in self.agentId:
-                    try:
-                        chain_id_for_wallet = int(self.agentId.split(":")[1])
-                    except (ValueError, IndexError):
-                        chain_id_for_wallet = 1
-            
-            endpoints.append({
-                "name": "agentWallet",
-                "endpoint": f"eip155:{chain_id_for_wallet}:{self.walletAddress}"
-            })
+        # Note: agentWallet is no longer included in endpoints array.
+        # It's now a reserved on-chain metadata key managed via setAgentWallet().
         
         # Build registrations array
         registrations = []
@@ -124,7 +110,7 @@ class RegistrationFile:
             "registrations": registrations,
             "supportedTrust": [tm.value if isinstance(tm, TrustModel) else tm for tm in self.trustModels],
             "active": self.active,
-            "x402support": self.x402support,
+            "x402Support": self.x402support,  # Use camelCase in JSON output per spec
             "updatedAt": self.updatedAt,
         }
 
@@ -162,7 +148,7 @@ class RegistrationFile:
             endpoints=endpoints,
             trustModels=trust_models,
             active=data.get("active", False),
-            x402support=data.get("x402support", 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())),
         )
@@ -205,6 +191,7 @@ class Feedback:
     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
@@ -269,7 +256,7 @@ class Feedback:
 @dataclass
 class SearchParams:
     """Parameters for agent search."""
-    chains: Optional[List[ChainId]] = None
+    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
@@ -286,6 +273,7 @@ class SearchParams:
     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."""
@@ -302,6 +290,7 @@ class SearchFeedbackParams:
     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
     minScore: Optional[int] = None  # 0-100
     maxScore: Optional[int] = None  # 0-100
     includeRevoked: bool = False

agent0_sdk/core/oasf_validator.py

@@ -0,0 +1,98 @@
+"""
+OASF taxonomy validation utilities.
+"""
+
+import json
+import os
+from pathlib import Path
+from typing import Optional
+
+# Cache for loaded taxonomy data
+_skills_cache: Optional[dict] = None
+_domains_cache: Optional[dict] = None
+
+
+def _get_taxonomy_path(filename: str) -> Path:
+    """Get the path to a taxonomy file."""
+    # Get the directory where this file is located
+    current_dir = Path(__file__).parent
+    # Go up one level to agent0_sdk, then into taxonomies
+    taxonomy_dir = current_dir.parent / "taxonomies"
+    return taxonomy_dir / filename
+
+
+def _load_skills() -> dict:
+    """Load skills taxonomy file with caching."""
+    global _skills_cache
+    if _skills_cache is None:
+        skills_path = _get_taxonomy_path("all_skills.json")
+        try:
+            with open(skills_path, "r", encoding="utf-8") as f:
+                _skills_cache = json.load(f)
+        except FileNotFoundError:
+            raise FileNotFoundError(
+                f"Skills taxonomy file not found: {skills_path}"
+            )
+        except json.JSONDecodeError as e:
+            raise ValueError(
+                f"Invalid JSON in skills taxonomy file: {e}"
+            )
+    return _skills_cache
+
+
+def _load_domains() -> dict:
+    """Load domains taxonomy file with caching."""
+    global _domains_cache
+    if _domains_cache is None:
+        domains_path = _get_taxonomy_path("all_domains.json")
+        try:
+            with open(domains_path, "r", encoding="utf-8") as f:
+                _domains_cache = json.load(f)
+        except FileNotFoundError:
+            raise FileNotFoundError(
+                f"Domains taxonomy file not found: {domains_path}"
+            )
+        except json.JSONDecodeError as e:
+            raise ValueError(
+                f"Invalid JSON in domains taxonomy file: {e}"
+            )
+    return _domains_cache
+
+
+def validate_skill(slug: str) -> bool:
+    """
+    Validate if a skill slug exists in the OASF taxonomy.
+    
+    Args:
+        slug: The skill slug to validate (e.g., "natural_language_processing/natural_language_generation/summarization")
+    
+    Returns:
+        True if the skill exists in the taxonomy, False otherwise
+    
+    Raises:
+        FileNotFoundError: If the taxonomy file cannot be found
+        ValueError: If the taxonomy file is invalid JSON
+    """
+    skills_data = _load_skills()
+    skills = skills_data.get("skills", {})
+    return slug in skills
+
+
+def validate_domain(slug: str) -> bool:
+    """
+    Validate if a domain slug exists in the OASF taxonomy.
+    
+    Args:
+        slug: The domain slug to validate (e.g., "finance_and_business/investment_services")
+    
+    Returns:
+        True if the domain exists in the taxonomy, False otherwise
+    
+    Raises:
+        FileNotFoundError: If the taxonomy file cannot be found
+        ValueError: If the taxonomy file is invalid JSON
+    """
+    domains_data = _load_domains()
+    domains = domains_data.get("domains", {})
+    return slug in domains
+

agent0_sdk/core/sdk.py

@@ -6,10 +6,13 @@ from __future__ import annotations
 
 import asyncio
 import json
+import logging
 import time
-from typing import Any, Dict, List, Optional, Union
+from typing import Any, Dict, List, Optional, Union, Literal
 from datetime import datetime
 
+logger = logging.getLogger(__name__)
+
 from .models import (
     AgentId, ChainId, Address, URI, Timestamp, IdemKey,
     EndpointType, TrustModel, Endpoint, RegistrationFile,
@@ -102,7 +105,8 @@ class SDK:
             web3_client=self.web3_client,
             store=indexingStore,
             embeddings=embeddings,
-            subgraph_client=self.subgraph_client
+            subgraph_client=self.subgraph_client,
+            subgraph_url_overrides=self._subgraph_urls
         )
         
         # Initialize IPFS client based on configuration
@@ -274,7 +278,12 @@ class SDK:
         return Agent(sdk=self, registration_file=registration_file)
 
     def loadAgent(self, agentId: AgentId) -> Agent:
-        """Load an existing agent (hydrates from registration file if registered)."""
+        """Load an existing agent (hydrates from registration file if registered).
+        
+        Note: Agents can be minted with an empty token URI (e.g. IPFS flow where publish fails).
+        In that case we return a partially-hydrated Agent with an empty registration file so the
+        caller can resume publishing and set the URI later.
+        """
         # Convert agentId to string if it's an integer
         agentId = str(agentId)
         
@@ -288,16 +297,22 @@ class SDK:
         
         # Get token URI from contract
         try:
-            token_uri = self.web3_client.call_contract(
-                self.identity_registry, "tokenURI", int(token_id)
+            agent_uri = self.web3_client.call_contract(
+                self.identity_registry, "tokenURI", int(token_id)  # tokenURI is ERC-721 standard, but represents agentURI
             )
         except Exception as e:
             raise ValueError(f"Failed to load agent {agentId}: {e}")
         
-        # Load registration file
-        registration_file = self._load_registration_file(token_uri)
+        # Load registration file (or fall back to a minimal file if agent URI is missing)
+        registration_file = self._load_registration_file(agent_uri)
         registration_file.agentId = agentId
-        registration_file.agentURI = token_uri if token_uri else None
+        registration_file.agentURI = agent_uri if agent_uri else None
+
+        if not agent_uri or not str(agent_uri).strip():
+            logger.warning(
+                f"Agent {agentId} has no agentURI set on-chain yet. "
+                "Returning a partial agent; update info and call registerIPFS() to publish and set URI."
+            )
         
         # Store registry address for proper JSON generation
         registry_address = self._registries.get("IDENTITY")
@@ -311,7 +326,13 @@ class SDK:
         return Agent(sdk=self, registration_file=registration_file)
 
     def _load_registration_file(self, uri: str) -> RegistrationFile:
-        """Load registration file from URI."""
+        """Load registration file from URI.
+        
+        If uri is empty/None/whitespace, returns an empty RegistrationFile to allow resume flows.
+        """
+        if not uri or not str(uri).strip():
+            return RegistrationFile()
+
         if uri.startswith("ipfs://"):
             if not self.ipfs_client:
                 raise ValueError("IPFS client not configured")
@@ -342,21 +363,20 @@ class SDK:
         # For now, we'll leave it empty
         registration_file.operators = []
         
-        # Hydrate metadata from on-chain (agentWallet, agentName, custom metadata)
+        # Hydrate agentWallet from on-chain (now uses getAgentWallet() instead of metadata)
         agent_id = token_id
         try:
-            # Try to get agentWallet from on-chain metadata
-            wallet_bytes = self.web3_client.call_contract(
-                self.identity_registry, "getMetadata", agent_id, "agentWallet"
+            # Get agentWallet using the new dedicated function
+            wallet_address = self.web3_client.call_contract(
+                self.identity_registry, "getAgentWallet", agent_id
             )
-            if wallet_bytes and len(wallet_bytes) > 0:
-                wallet_address = "0x" + wallet_bytes.hex()
+            if wallet_address and wallet_address != "0x0000000000000000000000000000000000000000":
                 registration_file.walletAddress = wallet_address
                 # If wallet is read from on-chain, use current chain ID
                 # (the chain ID from the registration file might be outdated)
                 registration_file.walletChainId = self.chainId
         except Exception as e:
-            # No on-chain wallet, will fall back to registration file
+            # No on-chain wallet set, will fall back to registration file
             pass
         
         try:
@@ -438,7 +458,7 @@ class SDK:
     def searchAgents(
         self,
         params: Union[SearchParams, Dict[str, Any], None] = None,
-        sort: List[str] = None,
+        sort: Union[str, List[str], None] = None,
         page_size: int = 50,
         cursor: Optional[str] = None,
         **kwargs  # Accept search criteria as kwargs for better DX
@@ -466,7 +486,9 @@ class SDK:
         
         if sort is None:
             sort = ["updatedAt:desc"]
-        
+        elif isinstance(sort, str):
+            sort = [sort]
+
         return self.indexer.search_agents(params, sort, page_size, cursor)
 
     # Feedback methods
@@ -588,8 +610,26 @@ class SDK:
         page_size: int = 50,
         cursor: Optional[str] = None,
         sort: Optional[List[str]] = None,
+        chains: Optional[Union[List[ChainId], Literal["all"]]] = None,
     ) -> Dict[str, Any]:
         """Search agents filtered by reputation criteria."""
+        # Handle multi-chain search
+        if chains:
+            # Expand "all" if needed
+            if chains == "all":
+                chains = self.indexer._get_all_configured_chains()
+            
+            # If multiple chains or single chain different from default
+            if isinstance(chains, list) and len(chains) > 0:
+                if len(chains) > 1 or (len(chains) == 1 and chains[0] != self.chainId):
+                    return asyncio.run(
+                        self._search_agents_by_reputation_across_chains(
+                            agents, tags, reviewers, capabilities, skills, tasks, names,
+                            minAverageScore, includeRevoked, page_size, cursor, sort, chains
+                        )
+                    )
+        
+        # Single chain search (existing behavior)
         if not self.subgraph_client:
             raise ValueError("Subgraph client required for searchAgentsByReputation")
         
@@ -664,6 +704,185 @@ class SDK:
         except Exception as e:
             raise ValueError(f"Failed to search agents by reputation: {e}")
     
+    async def _search_agents_by_reputation_across_chains(
+        self,
+        agents: Optional[List[AgentId]],
+        tags: Optional[List[str]],
+        reviewers: Optional[List[Address]],
+        capabilities: Optional[List[str]],
+        skills: Optional[List[str]],
+        tasks: Optional[List[str]],
+        names: Optional[List[str]],
+        minAverageScore: Optional[int],
+        includeRevoked: bool,
+        page_size: int,
+        cursor: Optional[str],
+        sort: Optional[List[str]],
+        chains: List[ChainId],
+    ) -> Dict[str, Any]:
+        """
+        Search agents by reputation across multiple chains in parallel.
+        
+        Similar to indexer._search_agents_across_chains() but for reputation-based search.
+        """
+        import time
+        start_time = time.time()
+        
+        if sort is None:
+            sort = ["createdAt:desc"]
+        
+        order_by = "createdAt"
+        order_direction = "desc"
+        if sort and len(sort) > 0:
+            sort_field = sort[0].split(":")
+            order_by = sort_field[0] if len(sort_field) >= 1 else order_by
+            order_direction = sort_field[1] if len(sort_field) >= 2 else order_direction
+        
+        skip = 0
+        if cursor:
+            try:
+                skip = int(cursor)
+            except ValueError:
+                skip = 0
+        
+        # Define async function for querying a single chain
+        async def query_single_chain(chain_id: int) -> Dict[str, Any]:
+            """Query one chain and return its results with metadata."""
+            try:
+                # Get subgraph client for this chain
+                subgraph_client = self.indexer._get_subgraph_client_for_chain(chain_id)
+                
+                if subgraph_client is None:
+                    logger.warning(f"No subgraph client available for chain {chain_id}")
+                    return {
+                        "chainId": chain_id,
+                        "status": "unavailable",
+                        "agents": [],
+                        "error": f"No subgraph configured for chain {chain_id}"
+                    }
+                
+                # Execute reputation search query
+                try:
+                    agents_data = subgraph_client.search_agents_by_reputation(
+                        agents=agents,
+                        tags=tags,
+                        reviewers=reviewers,
+                        capabilities=capabilities,
+                        skills=skills,
+                        tasks=tasks,
+                        names=names,
+                        minAverageScore=minAverageScore,
+                        includeRevoked=includeRevoked,
+                        first=page_size * 3,  # Fetch extra to allow for filtering/sorting
+                        skip=0,  # We'll handle pagination after aggregation
+                        order_by=order_by,
+                        order_direction=order_direction
+                    )
+                    
+                    logger.info(f"Chain {chain_id}: fetched {len(agents_data)} agents by reputation")
+                except Exception as e:
+                    logger.error(f"Error in search_agents_by_reputation for chain {chain_id}: {e}", exc_info=True)
+                    agents_data = []
+                
+                return {
+                    "chainId": chain_id,
+                    "status": "success",
+                    "agents": agents_data,
+                    "count": len(agents_data),
+                }
+                
+            except Exception as e:
+                logger.error(f"Error querying chain {chain_id} for reputation search: {e}", exc_info=True)
+                return {
+                    "chainId": chain_id,
+                    "status": "error",
+                    "agents": [],
+                    "error": str(e),
+                    "count": 0
+                }
+        
+        # Execute queries in parallel
+        chain_tasks = [query_single_chain(chain_id) for chain_id in chains]
+        chain_results = await asyncio.gather(*chain_tasks)
+        
+        # Aggregate results from all chains
+        all_agents = []
+        successful_chains = []
+        failed_chains = []
+        
+        for result in chain_results:
+            chain_id = result["chainId"]
+            if result["status"] == "success":
+                successful_chains.append(chain_id)
+                agents_count = len(result.get("agents", []))
+                logger.debug(f"Chain {chain_id}: aggregating {agents_count} agents")
+                all_agents.extend(result["agents"])
+            else:
+                failed_chains.append(chain_id)
+                logger.warning(f"Chain {chain_id}: status={result.get('status')}, error={result.get('error', 'N/A')}")
+        
+        logger.debug(f"Total agents aggregated: {len(all_agents)} from {len(successful_chains)} chains")
+        
+        # Transform to AgentSummary objects
+        from .models import AgentSummary
+        results = []
+        for agent_data in all_agents:
+            reg_file = agent_data.get('registrationFile') or {}
+            if not isinstance(reg_file, dict):
+                reg_file = {}
+            
+            agent_summary = AgentSummary(
+                chainId=int(agent_data.get('chainId', 0)),
+                agentId=agent_data.get('id'),
+                name=reg_file.get('name', f"Agent {agent_data.get('id')}"),
+                image=reg_file.get('image'),
+                description=reg_file.get('description', ''),
+                owners=[agent_data.get('owner', '')],
+                operators=agent_data.get('operators', []),
+                mcp=reg_file.get('mcpEndpoint') is not None,
+                a2a=reg_file.get('a2aEndpoint') is not None,
+                ens=reg_file.get('ens'),
+                did=reg_file.get('did'),
+                walletAddress=reg_file.get('agentWallet'),
+                supportedTrusts=reg_file.get('supportedTrusts', []),
+                a2aSkills=reg_file.get('a2aSkills', []),
+                mcpTools=reg_file.get('mcpTools', []),
+                mcpPrompts=reg_file.get('mcpPrompts', []),
+                mcpResources=reg_file.get('mcpResources', []),
+                active=reg_file.get('active', True),
+                x402support=reg_file.get('x402support', False),
+                extras={'averageScore': agent_data.get('averageScore')}
+            )
+            results.append(agent_summary)
+        
+        # Sort by averageScore (descending) if available, otherwise by createdAt
+        results.sort(
+            key=lambda x: (
+                x.extras.get('averageScore') if x.extras.get('averageScore') is not None else 0,
+                x.chainId,
+                x.agentId
+            ),
+            reverse=True
+        )
+        
+        # Apply pagination
+        paginated_results = results[skip:skip + page_size]
+        next_cursor = str(skip + len(paginated_results)) if len(paginated_results) == page_size and skip + len(paginated_results) < len(results) else None
+        
+        elapsed_ms = int((time.time() - start_time) * 1000)
+        
+        return {
+            "items": paginated_results,
+            "nextCursor": next_cursor,
+            "meta": {
+                "chains": chains,
+                "successfulChains": successful_chains,
+                "failedChains": failed_chains,
+                "totalResults": len(results),
+                "timing": {"totalMs": elapsed_ms}
+            }
+        }
+    
     # Feedback methods - delegate to feedback_manager
     def signFeedbackAuth(
         self,
@@ -701,11 +920,10 @@ class SDK:
         agentId: "AgentId",
         feedbackFile: Dict[str, Any],
         idem: Optional["IdemKey"] = None,
-        feedbackAuth: Optional[bytes] = None,
     ) -> "Feedback":
         """Give feedback (maps 8004 endpoint)."""
         return self.feedback_manager.giveFeedback(
-            agentId, feedbackFile, idem, feedbackAuth
+            agentId, feedbackFile, idem
         )
     
     def getFeedback(