agent0-sdk 1.0.1__py3-none-any.whl → 1.2.0__py3-none-any.whl

agent0_sdk/core/ipfs_client.py

@@ -160,7 +160,7 @@ class IPFSClient:
         # 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) -> str:
+    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
@@ -185,7 +185,7 @@ class IPFSClient:
             # Prepare the file for upload with public network setting
             with open(temp_path, 'rb') as file:
                 files = {
-                    'file': ('registration.json', file, 'application/json')
+                    'file': (file_name, file, 'application/json')
                 }
                 
                 # Add network parameter to make file public
@@ -233,8 +233,9 @@ class IPFSClient:
 
     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)
+            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:
@@ -251,11 +252,12 @@ class IPFSClient:
 
     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)
+            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:
@@ -332,7 +334,7 @@ class IPFSClient:
     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, **kwargs)
+        return self.add_json(data, file_name="agent-registration.json", **kwargs)
 
     def getRegistrationFile(self, cid: str) -> "RegistrationFile":
         """Get registration file from IPFS by CID."""
@@ -342,7 +344,7 @@ class IPFSClient:
 
     def addFeedbackFile(self, feedbackData: Dict[str, Any], **kwargs) -> str:
         """Add feedback file to IPFS and return CID."""
-        return self.add_json(feedbackData, **kwargs)
+        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."""

agent0_sdk/core/models.py

@@ -185,7 +185,9 @@ class Feedback:
     id: tuple  # (agentId, clientAddress, feedbackIndex) - tuple for efficiency
     agentId: AgentId
     reviewer: Address
-    score: Optional[int]  # 0-100
+    # 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
@@ -291,8 +293,8 @@ class SearchFeedbackParams:
     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
+    minValue: Optional[float] = None
+    maxValue: Optional[float] = None
     includeRevoked: bool = False
     
     def to_dict(self) -> Dict[str, Any]:

agent0_sdk/core/sdk.py

@@ -491,111 +491,8 @@ class SDK:
 
         return self.indexer.search_agents(params, sort, page_size, cursor)
 
-    # Feedback methods
-    def prepareFeedback(
-        self,
-        agentId: AgentId,
-        score: Optional[int] = None,  # 0-100
-        tags: List[str] = None,
-        text: Optional[str] = None,
-        capability: Optional[str] = None,
-        name: Optional[str] = None,
-        skill: Optional[str] = None,
-        task: Optional[str] = None,
-        context: Optional[Dict[str, Any]] = None,
-        proofOfPayment: Optional[Dict[str, Any]] = None,
-        extra: Optional[Dict[str, Any]] = None,
-    ) -> Dict[str, Any]:
-        """Prepare feedback file (local file/object)."""
-        return self.feedback_manager.prepareFeedback(
-            agentId=agentId,
-            score=score,
-            tags=tags,
-            text=text,
-            capability=capability,
-            name=name,
-            skill=skill,
-            task=task,
-            context=context,
-            proofOfPayment=proofOfPayment,
-            extra=extra
-        )
-
-    def giveFeedback(
-        self,
-        agentId: AgentId,
-        feedbackFile: Dict[str, Any],
-        idem: Optional[IdemKey] = None,
-        feedback_auth: Optional[bytes] = None,
-    ) -> Feedback:
-        """Give feedback (maps 8004 endpoint)."""
-        return self.feedback_manager.giveFeedback(
-            agentId=agentId,
-            feedbackFile=feedbackFile,
-            idem=idem,
-            feedback_auth=feedback_auth
-        )
-
-    def getFeedback(self, feedbackId: str) -> Feedback:
-        """Get single feedback by ID string."""
-        # Parse feedback ID
-        agentId, clientAddress, feedbackIndex = Feedback.from_id_string(feedbackId)
-        return self.feedback_manager.getFeedback(agentId, clientAddress, feedbackIndex)
-
-    def searchFeedback(
-        self,
-        agentId: AgentId,
-        reviewers: Optional[List[Address]] = None,
-        tags: Optional[List[str]] = None,
-        capabilities: Optional[List[str]] = None,
-        skills: Optional[List[str]] = None,
-        tasks: Optional[List[str]] = None,
-        names: Optional[List[str]] = None,
-        minScore: Optional[int] = None,
-        maxScore: Optional[int] = None,
-        include_revoked: bool = False,
-        first: int = 100,
-        skip: int = 0,
-    ) -> List[Feedback]:
-        """Search feedback for an agent."""
-        return self.feedback_manager.searchFeedback(
-            agentId=agentId,
-            clientAddresses=reviewers,
-            tags=tags,
-            capabilities=capabilities,
-            skills=skills,
-            tasks=tasks,
-            names=names,
-            minScore=minScore,
-            maxScore=maxScore,
-            include_revoked=include_revoked,
-            first=first,
-            skip=skip
-        )
-
-    def revokeFeedback(
-        self,
-        feedbackId: str,
-        reason: Optional[str] = None,
-        idem: Optional[IdemKey] = None,
-    ) -> Dict[str, Any]:
-        """Revoke feedback."""
-        # Parse feedback ID
-        agentId, clientAddress, feedbackIndex = Feedback.from_id_string(feedbackId)
-        return self.feedback_manager.revokeFeedback(agentId, feedbackIndex)
-
-    def appendResponse(
-        self,
-        feedbackId: str,
-        response: Dict[str, Any],
-        idem: Optional[IdemKey] = None,
-    ) -> Feedback:
-        """Append a response/follow-up to existing feedback."""
-        # Parse feedback ID
-        agentId, clientAddress, feedbackIndex = Feedback.from_id_string(feedbackId)
-        return self.feedback_manager.appendResponse(agentId, clientAddress, feedbackIndex, response)
+    # Feedback methods are defined later in this class (single authoritative API).
 
-    
     def searchAgentsByReputation(
         self,
         agents: Optional[List[AgentId]] = None,
@@ -605,7 +502,7 @@ class SDK:
         skills: Optional[List[str]] = None,
         tasks: Optional[List[str]] = None,
         names: Optional[List[str]] = None,
-        minAverageScore: Optional[int] = None,  # 0-100
+        minAverageValue: Optional[float] = None,
         includeRevoked: bool = False,
         page_size: int = 50,
         cursor: Optional[str] = None,
@@ -625,7 +522,7 @@ class SDK:
                     return asyncio.run(
                         self._search_agents_by_reputation_across_chains(
                             agents, tags, reviewers, capabilities, skills, tasks, names,
-                            minAverageScore, includeRevoked, page_size, cursor, sort, chains
+                            minAverageValue, includeRevoked, page_size, cursor, sort, chains
                         )
                     )
         
@@ -659,7 +556,7 @@ class SDK:
                 skills=skills,
                 tasks=tasks,
                 names=names,
-                minAverageScore=minAverageScore,
+                minAverageValue=minAverageValue,
                 includeRevoked=includeRevoked,
                 first=page_size,
                 skip=skip,
@@ -694,7 +591,7 @@ class SDK:
                     mcpResources=reg_file.get('mcpResources', []),
                     active=reg_file.get('active', True),
                     x402support=reg_file.get('x402support', False),
-                    extras={'averageScore': agent_data.get('averageScore')}
+                    extras={'averageValue': agent_data.get('averageValue')}
                 )
                 results.append(agent_summary)
             
@@ -713,7 +610,7 @@ class SDK:
         skills: Optional[List[str]],
         tasks: Optional[List[str]],
         names: Optional[List[str]],
-        minAverageScore: Optional[int],
+        minAverageValue: Optional[float],
         includeRevoked: bool,
         page_size: int,
         cursor: Optional[str],
@@ -771,7 +668,7 @@ class SDK:
                         skills=skills,
                         tasks=tasks,
                         names=names,
-                        minAverageScore=minAverageScore,
+                        minAverageValue=minAverageValue,
                         includeRevoked=includeRevoked,
                         first=page_size * 3,  # Fetch extra to allow for filtering/sorting
                         skip=0,  # We'll handle pagination after aggregation
@@ -851,14 +748,14 @@ class SDK:
                 mcpResources=reg_file.get('mcpResources', []),
                 active=reg_file.get('active', True),
                 x402support=reg_file.get('x402support', False),
-                extras={'averageScore': agent_data.get('averageScore')}
+                extras={'averageValue': agent_data.get('averageValue')}
             )
             results.append(agent_summary)
         
-        # Sort by averageScore (descending) if available, otherwise by createdAt
+        # Sort by averageValue (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.extras.get('averageValue') if x.extras.get('averageValue') is not None else 0,
                 x.chainId,
                 x.agentId
             ),
@@ -884,46 +781,35 @@ class SDK:
         }
     
     # Feedback methods - delegate to feedback_manager
-    def signFeedbackAuth(
-        self,
-        agentId: "AgentId",
-        clientAddress: "Address",
-        indexLimit: Optional[int] = None,
-        expiryHours: int = 24,
-    ) -> bytes:
-        """Sign feedback authorization for a client."""
-        return self.feedback_manager.signFeedbackAuth(
-            agentId, clientAddress, indexLimit, expiryHours
-        )
-    
-    def prepareFeedback(
-        self,
-        agentId: "AgentId",
-        score: Optional[int] = None,  # 0-100
-        tags: List[str] = None,
-        text: Optional[str] = None,
-        capability: Optional[str] = None,
-        name: Optional[str] = None,
-        skill: Optional[str] = None,
-        task: Optional[str] = None,
-        context: Optional[Dict[str, Any]] = None,
-        proofOfPayment: Optional[Dict[str, Any]] = None,
-        extra: Optional[Dict[str, Any]] = None,
-    ) -> Dict[str, Any]:
-        """Prepare feedback file (local file/object) according to spec."""
-        return self.feedback_manager.prepareFeedback(
-            agentId, score, tags, text, capability, name, skill, task, context, proofOfPayment, extra
-        )
+    def prepareFeedbackFile(self, input: Dict[str, Any]) -> Dict[str, Any]:
+        """Prepare an off-chain feedback file payload.
+        
+        This is intentionally off-chain-only; it does not attempt to represent
+        the on-chain fields (value/tag1/tag2/endpoint-on-chain).
+        """
+        return self.feedback_manager.prepareFeedbackFile(input)
     
     def giveFeedback(
         self,
         agentId: "AgentId",
-        feedbackFile: Dict[str, Any],
-        idem: Optional["IdemKey"] = None,
+        value: Union[int, float, str],
+        tag1: Optional[str] = None,
+        tag2: Optional[str] = None,
+        endpoint: Optional[str] = None,
+        feedbackFile: Optional[Dict[str, Any]] = None,
     ) -> "Feedback":
-        """Give feedback (maps 8004 endpoint)."""
+        """Give feedback (on-chain first; optional off-chain file upload).
+        
+        - If feedbackFile is None: submit on-chain only (no upload even if IPFS is configured).
+        - If feedbackFile is provided: requires IPFS configured; uploads and commits URI/hash on-chain.
+        """
         return self.feedback_manager.giveFeedback(
-            agentId, feedbackFile, idem
+            agentId=agentId,
+            value=value,
+            tag1=tag1,
+            tag2=tag2,
+            endpoint=endpoint,
+            feedbackFile=feedbackFile,
         )
     
     def getFeedback(
@@ -936,6 +822,37 @@ class SDK:
         return self.feedback_manager.getFeedback(
             agentId, clientAddress, feedbackIndex
         )
+
+    def searchFeedback(
+        self,
+        agentId: "AgentId",
+        reviewers: Optional[List["Address"]] = None,
+        tags: Optional[List[str]] = None,
+        capabilities: Optional[List[str]] = None,
+        skills: Optional[List[str]] = None,
+        tasks: Optional[List[str]] = None,
+        names: Optional[List[str]] = None,
+        minValue: Optional[float] = None,
+        maxValue: Optional[float] = None,
+        include_revoked: bool = False,
+        first: int = 100,
+        skip: int = 0,
+    ) -> List["Feedback"]:
+        """Search feedback for an agent."""
+        return self.feedback_manager.searchFeedback(
+            agentId=agentId,
+            clientAddresses=reviewers,
+            tags=tags,
+            capabilities=capabilities,
+            skills=skills,
+            tasks=tasks,
+            names=names,
+            minValue=minValue,
+            maxValue=maxValue,
+            include_revoked=include_revoked,
+            first=first,
+            skip=skip,
+        )
     
     def revokeFeedback(
         self,

agent0_sdk/core/subgraph_client.py

@@ -260,7 +260,7 @@ class SubgraphClient:
                     orderDirection: desc
                 ) {{
                     id
-                    score
+                    value
                     feedbackIndex
                     tag1
                     tag2
@@ -326,8 +326,7 @@ class SubgraphClient:
                     agentId
                 }}
                 totalFeedback
-                averageScore
-                scoreDistribution
+                averageFeedbackValue
                 totalValidations
                 completedValidations
                 averageValidationScore
@@ -416,7 +415,7 @@ class SubgraphClient:
                 agent { id agentId chainId }
                 clientAddress
                 feedbackIndex
-                score
+                value
                 tag1
                 tag2
                 endpoint
@@ -516,11 +515,11 @@ class SubgraphClient:
             # Join all tag alternatives (each already contains complete filter set)
             tag_filter_condition = ", ".join([f"{{ {item} }}" for item in tag_where_items])
         
-        if params.minScore is not None:
-            where_conditions.append(f'score_gte: {params.minScore}')
+        if params.minValue is not None:
+            where_conditions.append(f'value_gte: "{params.minValue}"')
         
-        if params.maxScore is not None:
-            where_conditions.append(f'score_lte: {params.maxScore}')
+        if params.maxValue is not None:
+            where_conditions.append(f'value_lte: "{params.maxValue}"')
         
         # Feedback file filters
         feedback_file_filters = []
@@ -566,7 +565,7 @@ class SubgraphClient:
                 agent {{ id agentId chainId }}
                 clientAddress
                 feedbackIndex
-                score
+                value
                 tag1
                 tag2
                 endpoint
@@ -616,7 +615,7 @@ class SubgraphClient:
         skills: Optional[List[str]] = None,
         tasks: Optional[List[str]] = None,
         names: Optional[List[str]] = None,
-        minAverageScore: Optional[int] = None,  # 0-100
+        minAverageValue: Optional[float] = None,
         includeRevoked: bool = False,
         first: int = 100,
         skip: int = 0,
@@ -633,7 +632,7 @@ class SubgraphClient:
             capabilities: List of capabilities to filter feedback by
             skills: List of skills to filter feedback by
             tasks: List of tasks to filter feedback by
-            minAverageScore: Minimum average score (0-100) for included agents
+            minAverageValue: Minimum average value for included agents
             includeRevoked: Whether to include revoked feedback in calculations
             first: Number of results to return
             skip: Number of results to skip
@@ -641,7 +640,7 @@ class SubgraphClient:
             order_direction: Sort direction (asc/desc)
             
         Returns:
-            List of agents with averageScore field calculated from filtered feedback
+            List of agents with averageValue field calculated from filtered feedback
         """
         # Build feedback filter
         feedback_filters = []
@@ -790,7 +789,7 @@ class SubgraphClient:
                     createdAt
                 }}
                 feedback(where: {feedback_where_for_agents}) {{
-                    score
+                    value
                     isRevoked
                     feedbackFile {{
                         capability
@@ -813,37 +812,33 @@ class SubgraphClient:
             
             agents_result = result.get('agents', [])
             
-            # Calculate average scores
+            # Calculate average values
             for agent in agents_result:
                 feedbacks = agent.get('feedback', [])
                 if feedbacks:
-                    scores = [int(fb['score']) for fb in feedbacks if fb.get('score', 0) > 0]
-                    if scores:
-                        avg_score = sum(scores) / len(scores)
-                        agent['averageScore'] = avg_score
-                    else:
-                        agent['averageScore'] = None
+                    values = [float(fb["value"]) for fb in feedbacks if fb.get("value") is not None]
+                    agent["averageValue"] = (sum(values) / len(values)) if values else None
                 else:
-                    agent['averageScore'] = None
+                    agent["averageValue"] = None
             
-            # Filter by minAverageScore
-            if minAverageScore is not None:
+            # Filter by minAverageValue
+            if minAverageValue is not None:
                 agents_result = [
                     agent for agent in agents_result
-                    if agent.get('averageScore') is not None and agent['averageScore'] >= minAverageScore
+                    if agent.get("averageValue") is not None and agent["averageValue"] >= minAverageValue
                 ]
             
             # For reputation search, filter logic:
-            # - If specific agents were requested, return them even if averageScore is None
+            # - If specific agents were requested, return them even if averageValue is None
             #   (the user explicitly asked for these agents, so return them)
             # - If general search (no specific agents), only return agents with reputation data
             if agents is None or len(agents) == 0:
                 # General search - only return agents with reputation
                 agents_result = [
                     agent for agent in agents_result
-                    if agent.get('averageScore') is not None
+                    if agent.get("averageValue") is not None
                 ]
-            # else: specific agents requested - return all requested agents (even if averageScore is None)
+            # else: specific agents requested - return all requested agents (even if averageValue is None)
             
             return agents_result
             

agent0_sdk/core/value_encoding.py

@@ -0,0 +1,91 @@
+"""
+Value encoding utilities for ReputationRegistry (Jan 2026).
+
+On-chain representation: (value:int256, valueDecimals:uint8)
+Human representation:    value / 10^valueDecimals
+"""
+
+from __future__ import annotations
+
+import logging
+from decimal import Decimal, ROUND_HALF_UP, getcontext
+from typing import Tuple, Union
+
+logger = logging.getLogger(__name__)
+
+# Plenty of headroom for scaling and clamping checks
+getcontext().prec = 120
+
+MAX_DECIMALS = 18
+# Solidity constant (raw int256 magnitude)
+MAX_ABS_VALUE_RAW = 10**50
+
+
+def encode_feedback_value(input_value: Union[int, float, str, Decimal]) -> Tuple[int, int, str]:
+    """
+    Encode a user-facing value into the on-chain (value, valueDecimals) pair.
+
+    Rules:
+    - str: parsed using Decimal (no float casting). If >18 decimals, it is rounded half-up to 18 decimals.
+    - float: accepted and rounded half-up to 18 decimals (never rejected).
+    - int/Decimal: treated similarly; Decimal preserves precision.
+
+    Returns: (value_raw:int, value_decimals:int, normalized:str)
+    """
+    if isinstance(input_value, Decimal):
+        dec = input_value
+        normalized = format(dec, "f")
+    elif isinstance(input_value, int):
+        dec = Decimal(input_value)
+        normalized = str(input_value)
+    elif isinstance(input_value, float):
+        # Avoid binary float artifacts by going through Decimal(str(x)), then quantize to 18 places.
+        dec = Decimal(str(input_value)).quantize(Decimal("1e-18"), rounding=ROUND_HALF_UP)
+        normalized = format(dec, "f")
+    elif isinstance(input_value, str):
+        s = input_value.strip()
+        if s == "":
+            raise ValueError("value cannot be an empty string")
+        dec = Decimal(s)
+        # Expand to plain decimal string (no exponent) for determining decimals
+        normalized = format(dec, "f")
+    else:
+        raise TypeError(f"value must be int|float|str|Decimal, got {type(input_value)}")
+
+    # Determine decimals from the normalized representation.
+    # This preserves trailing zeros for string inputs like "1.2300".
+    if "." in normalized:
+        decimals = len(normalized.split(".", 1)[1])
+    else:
+        decimals = 0
+
+    if decimals > MAX_DECIMALS:
+        dec = dec.quantize(Decimal("1e-18"), rounding=ROUND_HALF_UP)
+        normalized = format(dec, "f")  # keeps fixed 18 decimals
+        decimals = MAX_DECIMALS
+
+    scale = Decimal(10) ** decimals
+    raw_decimal = dec * scale
+    raw_int = int(raw_decimal.to_integral_value(rounding=ROUND_HALF_UP))
+
+    if abs(raw_int) > MAX_ABS_VALUE_RAW:
+        raw_int = MAX_ABS_VALUE_RAW if raw_int > 0 else -MAX_ABS_VALUE_RAW
+        clamped = Decimal(raw_int) / (Decimal(10) ** decimals)
+        normalized = format(clamped, "f")
+        logger.warning(
+            "Feedback value %r exceeds on-chain max magnitude; clamped to %s (decimals=%s)",
+            input_value,
+            normalized,
+            decimals,
+        )
+
+    return raw_int, decimals, normalized
+
+
+def decode_feedback_value(value_raw: int, value_decimals: int) -> float:
+    """Decode (value, valueDecimals) into a Python float."""
+    if value_decimals < 0:
+        raise ValueError("valueDecimals cannot be negative")
+    return float(Decimal(value_raw) / (Decimal(10) ** int(value_decimals)))
+
+