xache 5.0.0__py3-none-any.whl

xache/services/receipts.py

@@ -0,0 +1,202 @@
+"""Receipts Service - Access receipts and Merkle proofs"""
+
+from typing import List, Dict, Any, Optional
+from ..types import Receipt, ReceiptWithProof, UsageAnalytics
+
+
+class ReceiptsService:
+    """Receipt service for transaction records"""
+
+    def __init__(self, client):
+        self.client = client
+
+    async def list(
+        self,
+        limit: int = 50,
+        offset: int = 0,
+    ) -> Dict[str, Any]:
+        """
+        List receipts for authenticated agent (free)
+
+        Example:
+            ```python
+            result = await client.receipts.list(limit=20, offset=0)
+            for receipt in result["receipts"]:
+                print(f"{receipt.operation}: ${receipt.amount_usd}")
+            ```
+        """
+        self._validate_list_options(limit, offset)
+
+        response = await self.client.request(
+            "GET",
+            f"/v1/receipts?limit={limit}&offset={offset}",
+        )
+
+        if not response.success or not response.data:
+            raise Exception("Failed to list receipts")
+
+        data = response.data
+        receipts = [Receipt(**r) for r in data["receipts"]]
+
+        return {
+            "receipts": receipts,
+            "total": data["total"],
+            "limit": data["limit"],
+            "offset": data["offset"],
+        }
+
+    async def get_proof(self, receipt_id: str) -> ReceiptWithProof:
+        """Get Merkle proof for a receipt (free)"""
+        if not receipt_id:
+            raise ValueError("receipt_id is required")
+
+        response = await self.client.request(
+            "GET",
+            f"/v1/receipts/{receipt_id}/proof",
+        )
+
+        if not response.success or not response.data:
+            raise Exception("Failed to get receipt proof")
+
+        data = response.data
+        return ReceiptWithProof(
+            receipt_id=data["receiptId"],
+            merkle_proof=data["merkleProof"],
+            merkle_root=data["merkleRoot"],
+        )
+
+    async def get_analytics(
+        self,
+        start_date: Optional[str] = None,
+        end_date: Optional[str] = None,
+    ) -> UsageAnalytics:
+        """Get usage analytics (free)"""
+        params = []
+        if start_date:
+            params.append(f"startDate={start_date}")
+        if end_date:
+            params.append(f"endDate={end_date}")
+
+        query_string = "&".join(params)
+        path = f"/v1/analytics/usage?{query_string}" if query_string else "/v1/analytics/usage"
+
+        response = await self.client.request("GET", path)
+
+        if not response.success or not response.data:
+            raise Exception("Failed to get usage analytics")
+
+        data = response.data
+        return UsageAnalytics(
+            operations=data["operations"],
+            total_spent=data["totalSpent"],
+            period=data["period"],
+        )
+
+    async def get_by_operation(
+        self, operation: str, limit: int = 50
+    ) -> List[Receipt]:
+        """Get receipts for specific operation type"""
+        result = await self.list(limit=100)
+        return [r for r in result["receipts"] if r.operation == operation][:limit]
+
+    def _validate_list_options(self, limit: int, offset: int):
+        """Validate list options"""
+        if limit < 1 or limit > 100:
+            raise ValueError("limit must be between 1 and 100")
+        if offset < 0:
+            raise ValueError("offset must be non-negative")
+
+    # ========== Merkle Anchors ==========
+
+    async def list_anchors(
+        self,
+        from_date: Optional[str] = None,
+        to_date: Optional[str] = None,
+        limit: int = 100,
+    ) -> Dict[str, Any]:
+        """
+        List Merkle root anchors with chain status.
+        Shows hourly batches of receipts anchored to blockchain.
+
+        Args:
+            from_date: Start date (ISO format, default: 24 hours ago)
+            to_date: End date (ISO format, default: now)
+            limit: Maximum anchors to return (default: 100)
+
+        Returns:
+            Anchor list with chain status
+
+        Example:
+            ```python
+            result = await client.receipts.list_anchors(
+                from_date="2024-01-01T00:00:00Z",
+                to_date="2024-01-31T23:59:59Z",
+                limit=50
+            )
+
+            for anchor in result['anchors']:
+                print(f"{anchor['hour']}: {anchor['receipt_count']} receipts")
+                if anchor['base']:
+                    print(f"  Base TX: {anchor['base']['tx_hash']}")
+                if anchor['solana']:
+                    print(f"  Solana TX: {anchor['solana']['tx_hash']}")
+                if anchor['dual_anchored']:
+                    print("  ✓ Dual-anchored")
+            ```
+        """
+        params = []
+        if from_date:
+            params.append(f"from={from_date}")
+        if to_date:
+            params.append(f"to={to_date}")
+        params.append(f"limit={limit}")
+
+        query_string = "&".join(params)
+        path = f"/v1/anchors?{query_string}"
+
+        response = await self.client.request("GET", path, skip_auth=True)
+
+        if not response.success or not response.data:
+            raise Exception(
+                response.error.get("message", "Failed to list anchors")
+                if response.error
+                else "Failed to list anchors"
+            )
+
+        data = response.data
+        return {
+            "anchors": [
+                {
+                    "hour": a["hour"],
+                    "merkle_root": a["merkleRoot"],
+                    "receipt_count": a["receiptCount"],
+                    "base": (
+                        {
+                            "tx_hash": a["base"]["txHash"],
+                            "gas_used": a["base"].get("gasUsed"),
+                            "status": a["base"]["status"],
+                            "anchored_at": a["base"].get("anchoredAt"),
+                        }
+                        if a.get("base")
+                        else None
+                    ),
+                    "solana": (
+                        {
+                            "tx_hash": a["solana"]["txHash"],
+                            "gas_used": a["solana"].get("gasUsed"),
+                            "status": a["solana"]["status"],
+                            "anchored_at": a["solana"].get("anchoredAt"),
+                        }
+                        if a.get("solana")
+                        else None
+                    ),
+                    "dual_anchored": a.get("dualAnchored", False),
+                }
+                for a in data.get("anchors", [])
+            ],
+            "total": data.get("total", 0),
+            "period": {
+                "from": data["period"]["from"],
+                "to": data["period"]["to"],
+            },
+        }

xache/services/reputation.py

@@ -0,0 +1,274 @@
+"""Reputation Service - Query reputation scores and domain expertise per HLD §2.2"""
+
+from typing import List, Optional
+from ..types import ReputationSnapshot, DomainReputation, TopAgent, DID
+
+
+class ReputationService:
+    """Reputation service for reputation tracking and leaderboards"""
+
+    def __init__(self, client):
+        self.client = client
+
+    async def get_reputation(self, agent_did: Optional[DID] = None) -> ReputationSnapshot:
+        """
+        Get current reputation snapshot for the authenticated agent
+        Free (no payment required)
+
+        Args:
+            agent_did: Optional agent DID (defaults to authenticated agent)
+
+        Returns:
+            Current reputation snapshot with all scores
+
+        Example:
+            ```python
+            reputation = await client.reputation.get_reputation()
+
+            print(f"Overall Score: {reputation.overall}")
+            print(f"Memory Quality: {reputation.memory_quality}")
+            print(f"Contribution Success: {reputation.contrib_success}")
+            print(f"Economic Value: {reputation.economic_value}")
+            ```
+        """
+        endpoint = f"/v1/reputation/{agent_did}" if agent_did else "/v1/reputation"
+
+        response = await self.client.request("GET", endpoint)
+
+        if not response.success or not response.data:
+            raise Exception("Failed to get reputation")
+
+        data = response.data
+        return ReputationSnapshot(
+            agent_did=data["agentDID"],
+            timestamp=data["timestamp"],
+            overall=data["overall"],
+            memory_quality=data.get("memoryQuality", 0),
+            contrib_success=data.get("contribSuccess", 0),
+            economic_value=data.get("economicValue", 0),
+            network_influence=data.get("networkInfluence", 0),
+            reliability=data.get("reliability", 0),
+            specialization=data.get("specialization", []),
+            weights=data.get("weights", {}),
+        )
+
+    async def get_history(
+        self, agent_did: Optional[DID] = None, limit: int = 30
+    ) -> List[ReputationSnapshot]:
+        """
+        Get reputation history for the authenticated agent
+        Free (no payment required)
+
+        Args:
+            agent_did: Optional agent DID (defaults to authenticated agent)
+            limit: Number of historical snapshots to retrieve (1-100, default: 30)
+
+        Returns:
+            List of historical reputation snapshots
+
+        Example:
+            ```python
+            history = await client.reputation.get_history(limit=10)
+
+            print(f"Retrieved {len(history)} historical snapshots")
+            for i, snapshot in enumerate(history):
+                print(f"{i + 1}. {snapshot.timestamp}: {snapshot.overall}")
+            ```
+        """
+        # Validate limit
+        self._validate_limit(limit)
+
+        endpoint = (
+            f"/v1/reputation/{agent_did}/history?limit={limit}"
+            if agent_did
+            else f"/v1/reputation/history?limit={limit}"
+        )
+
+        response = await self.client.request("GET", endpoint)
+
+        if not response.success or not response.data:
+            raise Exception("Failed to get reputation history")
+
+        return [
+            ReputationSnapshot(
+                agent_did=item["agentDID"],
+                timestamp=item["timestamp"],
+                overall=item["overall"],
+                memory_quality=item.get("memoryQuality", 0),
+                contrib_success=item.get("contribSuccess", 0),
+                economic_value=item.get("economicValue", 0),
+                network_influence=item.get("networkInfluence", 0),
+                reliability=item.get("reliability", 0),
+                specialization=item.get("specialization", []),
+                weights=item.get("weights", {}),
+            )
+            for item in response.data
+        ]
+
+    async def get_top_agents(self, limit: int = 10) -> List[TopAgent]:
+        """
+        Get top agents by reputation score (leaderboard)
+        Free (no payment required)
+
+        Args:
+            limit: Number of top agents to retrieve (1-100, default: 10)
+
+        Returns:
+            List of top agents sorted by reputation score
+
+        Example:
+            ```python
+            top_agents = await client.reputation.get_top_agents(10)
+
+            print("Top 10 Agents:")
+            for i, agent in enumerate(top_agents):
+                print(f"{i + 1}. {agent.agent_did}")
+                print(f"   Score: {agent.reputation_score}")
+                print(f"   Operations: {agent.operation_count}")
+                print(f"   Earned: {agent.total_earned_usd}")
+            ```
+        """
+        # Validate limit
+        self._validate_limit(limit)
+
+        response = await self.client.request(
+            "GET", f"/v1/reputation/leaderboard?limit={limit}", skip_auth=True
+        )
+
+        if not response.success or not response.data:
+            raise Exception("Failed to get top agents")
+
+        # API returns {leaderboard: [...], total: N}
+        leaderboard = response.data.get("leaderboard", response.data)
+        if isinstance(leaderboard, dict):
+            leaderboard = leaderboard.get("leaderboard", [])
+
+        return [
+            TopAgent(
+                agent_did=item["agentDID"],
+                wallet_address=item.get("walletAddress", ""),
+                reputation_score=item["reputationScore"],
+                operation_count=item.get("operationCount", 0),
+                total_earned_usd=item.get("totalEarnedUSD", "0"),
+            )
+            for item in leaderboard
+        ]
+
+    async def get_domain_reputation(
+        self, domain: str, agent_did: Optional[DID] = None
+    ) -> Optional[DomainReputation]:
+        """
+        Get domain-specific reputation for an agent
+        Free (no payment required)
+
+        Args:
+            domain: Domain name (e.g., 'javascript', 'python', 'devops')
+            agent_did: Optional agent DID (defaults to authenticated agent)
+
+        Returns:
+            Domain-specific reputation or None if no reputation in domain
+
+        Example:
+            ```python
+            python_rep = await client.reputation.get_domain_reputation('python')
+
+            if python_rep:
+                print("Python Domain Reputation:")
+                print(f"  Score: {python_rep.score}")
+                print(f"  Contributions: {python_rep.contribution_count}")
+                print(f"  Success Rate: {python_rep.success_rate}")
+                print(f"  Total Earned: {python_rep.total_earned_usd}")
+            else:
+                print("No reputation in Python domain yet")
+            ```
+        """
+        # Validate domain
+        self._validate_domain(domain)
+
+        endpoint = (
+            f"/v1/reputation/{agent_did}/domain/{domain}"
+            if agent_did
+            else f"/v1/reputation/domain/{domain}"
+        )
+
+        response = await self.client.request("GET", endpoint)
+
+        if not response.success:
+            raise Exception("Failed to get domain reputation")
+
+        if not response.data:
+            return None
+
+        data = response.data
+        return DomainReputation(
+            domain=data["domain"],
+            score=data["score"],
+            contribution_count=data["contributionCount"],
+            success_rate=data["successRate"],
+            total_earned_usd=data["totalEarnedUSD"],
+        )
+
+    async def get_all_domain_reputations(
+        self, agent_did: Optional[DID] = None
+    ) -> List[DomainReputation]:
+        """
+        Get all domain reputations for an agent
+        Free (no payment required)
+
+        Args:
+            agent_did: Optional agent DID (defaults to authenticated agent)
+
+        Returns:
+            List of domain reputations
+
+        Example:
+            ```python
+            domains = await client.reputation.get_all_domain_reputations()
+
+            print("Domain Expertise:")
+            for domain in domains:
+                print(f"{domain.domain}: {domain.score} ({domain.contribution_count} contributions)")
+            ```
+        """
+        endpoint = (
+            f"/v1/reputation/{agent_did}/domains"
+            if agent_did
+            else "/v1/reputation/domains"
+        )
+
+        response = await self.client.request("GET", endpoint)
+
+        if not response.success or not response.data:
+            raise Exception("Failed to get domain reputations")
+
+        return [
+            DomainReputation(
+                domain=item["domain"],
+                score=item["score"],
+                contribution_count=item["contributionCount"],
+                success_rate=item["successRate"],
+                total_earned_usd=item["totalEarnedUSD"],
+            )
+            for item in response.data
+        ]
+
+    def _validate_limit(self, limit: int):
+        """Validate limit parameter"""
+        if not isinstance(limit, int):
+            raise ValueError("limit must be an integer")
+        if limit < 1 or limit > 100:
+            raise ValueError("limit must be between 1 and 100")
+
+    def _validate_domain(self, domain: str):
+        """Validate domain parameter"""
+        if not domain or not isinstance(domain, str):
+            raise ValueError("domain is required and must be a string")
+        if len(domain) < 2:
+            raise ValueError("domain must be at least 2 characters")
+        if len(domain) > 50:
+            raise ValueError("domain must be at most 50 characters")
+        # Domain should only contain lowercase letters, numbers, and hyphens
+        if not all(c.islower() or c.isdigit() or c == "-" for c in domain):
+            raise ValueError(
+                "domain must only contain lowercase letters, numbers, and hyphens"
+            )