agent0-sdk 1.4.2__py3-none-any.whl → 1.5.0b1__py3-none-any.whl

agent0_sdk/core/models.py

@@ -165,8 +165,11 @@ class AgentSummary:
     description: str
     owners: List[Address]
     operators: List[Address]
-    mcp: bool
-    a2a: bool
+    # Endpoint strings (new unified search + Jan 2026 schema)
+    mcp: Optional[str] = None
+    a2a: Optional[str] = None
+    web: Optional[str] = None
+    email: Optional[str] = None
     ens: Optional[str]
     did: Optional[str]
     walletAddress: Optional[Address]
@@ -175,8 +178,18 @@ class AgentSummary:
     mcpTools: List[str]
     mcpPrompts: List[str]
     mcpResources: List[str]
+    oasfSkills: List[str] = field(default_factory=list)
+    oasfDomains: List[str] = field(default_factory=list)
     active: bool
     x402support: bool = False
+    createdAt: Optional[int] = None
+    updatedAt: Optional[int] = None
+    lastActivity: Optional[int] = None
+    agentURI: Optional[str] = None
+    agentURIType: Optional[str] = None
+    feedbackCount: Optional[int] = None
+    averageValue: Optional[float] = None
+    semanticScore: Optional[float] = None
     extras: Dict[str, Any] = field(default_factory=dict)
 
 
@@ -257,32 +270,100 @@ class Feedback:
 
 
 @dataclass
-class SearchParams:
-    """Parameters for agent search."""
+class FeedbackFilters:
+    hasFeedback: Optional[bool] = None
+    hasNoFeedback: Optional[bool] = None
+    includeRevoked: Optional[bool] = None
+    minValue: Optional[float] = None
+    maxValue: Optional[float] = None
+    minCount: Optional[int] = None
+    maxCount: Optional[int] = None
+    fromReviewers: Optional[List[Address]] = None
+    endpoint: Optional[str] = None
+    hasResponse: Optional[bool] = None
+    tag1: Optional[str] = None
+    tag2: Optional[str] = None
+    tag: Optional[str] = None
+
+
+DateLike = Union[datetime, str, int]
+
+
+@dataclass
+class SearchFilters:
+    # Chain / identity
     chains: Optional[Union[List[ChainId], Literal["all"]]] = None
-    name: Optional[str] = None  # case-insensitive substring
-    description: Optional[str] = None  # semantic; vector distance < threshold
+    agentIds: Optional[List[AgentId]] = None
+
+    # Text
+    name: Optional[str] = None
+    description: Optional[str] = None
+
+    # Owners / operators
     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
+
+    # Endpoint existence
+    hasRegistrationFile: Optional[bool] = None
+    hasWeb: Optional[bool] = None
+    hasMCP: Optional[bool] = None
+    hasA2A: Optional[bool] = None
+    hasOASF: Optional[bool] = None
+    hasEndpoints: Optional[bool] = None
+
+    # Endpoint substring contains
+    webContains: Optional[str] = None
+    mcpContains: Optional[str] = None
+    a2aContains: Optional[str] = None
+    ensContains: Optional[str] = None
+    didContains: Optional[str] = None
+
+    # Wallet
     walletAddress: Optional[Address] = None
+
+    # Capability arrays (ANY semantics)
     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
+    oasfSkills: Optional[List[str]] = None
+    oasfDomains: Optional[List[str]] = None
+
+    # Status
+    active: Optional[bool] = None
     x402support: Optional[bool] = None
-    deduplicate_cross_chain: bool = False  # Deduplicate same agent across chains
+
+    # Time filters
+    registeredAtFrom: Optional[DateLike] = None
+    registeredAtTo: Optional[DateLike] = None
+    updatedAtFrom: Optional[DateLike] = None
+    updatedAtTo: Optional[DateLike] = None
+
+    # Metadata filters (two-phase)
+    hasMetadataKey: Optional[str] = None
+    metadataValue: Optional[Dict[str, str]] = None  # { key, value }
+
+    # Semantic search
+    keyword: Optional[str] = None
+
+    # Feedback filters (two-phase)
+    feedback: Optional[FeedbackFilters] = None
 
     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 SearchOptions:
+    sort: Optional[List[str]] = None
+    pageSize: Optional[int] = None
+    cursor: Optional[str] = None
+    semanticMinScore: Optional[float] = None
+    semanticTopK: Optional[int] = None
+
+
 @dataclass
 class SearchFeedbackParams:
     """Parameters for feedback search."""

agent0_sdk/core/sdk.py

@@ -16,7 +16,7 @@ logger = logging.getLogger(__name__)
 from .models import (
     AgentId, ChainId, Address, URI, Timestamp, IdemKey,
     EndpointType, TrustModel, Endpoint, RegistrationFile,
-    AgentSummary, Feedback, SearchParams
+    AgentSummary, Feedback, SearchFilters, SearchOptions, FeedbackFilters
 )
 from .web3_client import Web3Client
 from .contracts import (
@@ -460,10 +460,8 @@ class SDK:
 
     def searchAgents(
         self,
-        params: Union[SearchParams, Dict[str, Any], None] = None,
-        sort: Union[str, List[str], None] = None,
-        page_size: int = 50,
-        cursor: Optional[str] = None,
+        filters: Union[SearchFilters, Dict[str, Any], None] = None,
+        options: Union[SearchOptions, Dict[str, Any], None] = None,
         **kwargs  # Accept search criteria as kwargs for better DX
     ) -> Dict[str, Any]:
         """Search for agents.
@@ -479,309 +477,32 @@ class SDK:
             # With pagination
             sdk.searchAgents(name="Test", page_size=10)
         """
-        # If kwargs provided, use them instead of params
-        if kwargs and params is None:
-            params = SearchParams(**kwargs)
-        elif params is None:
-            params = SearchParams()
-        elif isinstance(params, dict):
-            params = SearchParams(**params)
-        
-        if sort is None:
-            sort = ["updatedAt:desc"]
-        elif isinstance(sort, str):
-            sort = [sort]
-
-        return self.indexer.search_agents(params, sort, page_size, cursor)
+        # Allow kwargs to populate filters for better DX.
+        if kwargs and filters is None:
+            if isinstance(kwargs.get("feedback"), dict):
+                kwargs["feedback"] = FeedbackFilters(**kwargs["feedback"])
+            filters = SearchFilters(**kwargs)
+        elif filters is None:
+            filters = SearchFilters()
+        elif isinstance(filters, dict):
+            if isinstance(filters.get("feedback"), dict):
+                filters["feedback"] = FeedbackFilters(**filters["feedback"])
+            filters = SearchFilters(**filters)
+
+        if options is None:
+            options = SearchOptions()
+        elif isinstance(options, dict):
+            options = SearchOptions(**options)
+
+        if options.sort is None:
+            options.sort = ["updatedAt:desc"]
+
+        if options.pageSize is None:
+            options.pageSize = 50
+
+        return self.indexer.search_agents(filters, options)
 
     # Feedback methods are defined later in this class (single authoritative API).
-
-    def searchAgentsByReputation(
-        self,
-        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,
-        minAverageValue: Optional[float] = None,
-        includeRevoked: bool = False,
-        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,
-                            minAverageValue, includeRevoked, page_size, cursor, sort, chains
-                        )
-                    )
-        
-        # Single chain search (existing behavior)
-        if not self.subgraph_client:
-            raise ValueError("Subgraph client required for searchAgentsByReputation")
-        
-        if sort is None:
-            sort = ["createdAt:desc"]
-        
-        skip = 0
-        if cursor:
-            try:
-                skip = int(cursor)
-            except ValueError:
-                skip = 0
-        
-        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
-        
-        try:
-            agents_data = self.subgraph_client.search_agents_by_reputation(
-                agents=agents,
-                tags=tags,
-                reviewers=reviewers,
-                capabilities=capabilities,
-                skills=skills,
-                tasks=tasks,
-                names=names,
-                minAverageValue=minAverageValue,
-                includeRevoked=includeRevoked,
-                first=page_size,
-                skip=skip,
-                order_by=order_by,
-                order_direction=order_direction
-            )
-            
-            from .models import AgentSummary
-            results = []
-            for agent_data in agents_data:
-                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', reg_file.get('x402support', False)),
-                    extras={'averageValue': agent_data.get('averageValue')}
-                )
-                results.append(agent_summary)
-            
-            next_cursor = str(skip + len(results)) if len(results) == page_size else None
-            return {"items": results, "nextCursor": next_cursor}
-            
-        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]],
-        minAverageValue: Optional[float],
-        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,
-                        minAverageValue=minAverageValue,
-                        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', reg_file.get('x402support', False)),
-                extras={'averageValue': agent_data.get('averageValue')}
-            )
-            results.append(agent_summary)
-        
-        # Sort by averageValue (descending) if available, otherwise by createdAt
-        results.sort(
-            key=lambda x: (
-                x.extras.get('averageValue') if x.extras.get('averageValue') 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 prepareFeedbackFile(self, input: Dict[str, Any]) -> Dict[str, Any]:

agent0_sdk/core/semantic_search_client.py

@@ -0,0 +1,66 @@
+"""
+Semantic search client (external endpoint).
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import List, Optional
+
+import requests
+
+
+@dataclass
+class SemanticSearchResult:
+    chainId: int
+    agentId: str
+    score: float
+
+
+class SemanticSearchClient:
+    def __init__(
+        self,
+        base_url: str = "https://semantic-search.ag0.xyz",
+        timeout_seconds: float = 10.0,
+    ):
+        self.base_url = base_url.rstrip("/")
+        self.timeout_seconds = timeout_seconds
+
+    def search(self, query: str, *, min_score: Optional[float] = None, top_k: Optional[int] = None) -> List[SemanticSearchResult]:
+        if not query or not query.strip():
+            return []
+
+        body = {"query": query.strip()}
+        if min_score is not None:
+            body["minScore"] = min_score
+        if top_k is not None:
+            body["topK"] = top_k
+
+        resp = requests.post(
+            f"{self.base_url}/api/v1/search",
+            json=body,
+            headers={"Content-Type": "application/json"},
+            timeout=self.timeout_seconds,
+        )
+        resp.raise_for_status()
+        data = resp.json()
+
+        results = data.get("results") if isinstance(data, dict) else data
+        if not isinstance(results, list):
+            return []
+
+        out: List[SemanticSearchResult] = []
+        for r in results:
+            if not isinstance(r, dict):
+                continue
+            try:
+                chain_id = int(r.get("chainId"))
+                agent_id = str(r.get("agentId"))
+                score = float(r.get("score"))
+            except Exception:
+                continue
+            if ":" not in agent_id:
+                continue
+            out.append(SemanticSearchResult(chainId=chain_id, agentId=agent_id, score=score))
+        return out
+