xache 5.0.0__py3-none-any.whl

xache/services/collective.py

@@ -0,0 +1,174 @@
+"""Collective Service - Contribute and query heuristics per LLD §2.5"""
+
+from typing import List, Optional
+from ..types import (
+    ContributeHeuristicRequest,
+    ContributeHeuristicResponse,
+    QueryCollectiveResponse,
+    HeuristicMatch,
+    HeuristicMetrics,
+)
+
+
+class CollectiveService:
+    """Collective service for heuristic marketplace"""
+
+    def __init__(self, client):
+        self.client = client
+
+    async def contribute(
+        self,
+        pattern: str,
+        pattern_hash: str,
+        domain: str,
+        tags: List[str],
+        metrics: HeuristicMetrics,
+        encrypted_content_ref: str,
+        context_type: Optional[str] = None,
+        metadata: Optional[dict] = None,
+    ) -> ContributeHeuristicResponse:
+        """
+        Contribute a heuristic to the collective per LLD §2.5
+        Cost: $0.001 (automatic 402 payment)
+
+        Args:
+            pattern: Pattern text (10-500 chars)
+            pattern_hash: Hash of pattern for deduplication
+            domain: Domain (e.g., 'javascript', 'python', 'devops')
+            tags: Tags for categorization (1-10 tags)
+            metrics: Heuristic metrics (success_rate, sample_size, confidence)
+            encrypted_content_ref: Reference to encrypted content in R2
+            context_type: Optional context type
+            metadata: Optional metadata
+        """
+        self._validate_contribute_request(
+            pattern, pattern_hash, domain, tags, metrics, encrypted_content_ref
+        )
+
+        response = await self.client.request_with_payment(
+            "POST",
+            "/v1/collective/contribute",
+            {
+                "pattern": pattern,
+                "patternHash": pattern_hash,
+                "domain": domain,
+                "tags": tags,
+                "metrics": {
+                    "successRate": metrics.success_rate,
+                    "sampleSize": metrics.sample_size,
+                    "confidence": metrics.confidence,
+                },
+                "encryptedContentRef": encrypted_content_ref,
+                "contextType": context_type,
+                "metadata": metadata,
+            },
+        )
+
+        if not response.success or not response.data:
+            raise Exception("Heuristic contribution failed")
+
+        data = response.data
+        return ContributeHeuristicResponse(
+            heuristic_id=data["heuristicId"],
+            pattern=data["pattern"],
+            domain=data["domain"],
+            tags=data["tags"],
+            receipt_id=data["receiptId"],
+        )
+
+    async def query(
+        self,
+        query_text: str,
+        domain: str = None,
+        limit: int = 10,
+    ) -> QueryCollectiveResponse:
+        """
+        Query the collective for relevant heuristics per LLD §2.5
+        Cost: $0.01 + royalties (automatic 402 payment)
+        """
+        self._validate_query_request(query_text, limit)
+
+        response = await self.client.request_with_payment(
+            "POST",
+            "/v1/collective/query",
+            {
+                "queryText": query_text,
+                "domain": domain,
+                "limit": limit,
+            },
+        )
+
+        if not response.success or not response.data:
+            raise Exception("Collective query failed")
+
+        data = response.data
+        matches = [
+            HeuristicMatch(**match) for match in data["matches"]
+        ]
+
+        return QueryCollectiveResponse(
+            matches=matches,
+            total_cost=data["totalCost"],
+            royalties_usd=data["royaltiesUSD"],
+            receipt_id=data["receiptId"],
+        )
+
+    def _validate_contribute_request(
+        self,
+        pattern: str,
+        pattern_hash: str,
+        domain: str,
+        tags: List[str],
+        metrics: HeuristicMetrics,
+        encrypted_content_ref: str,
+    ):
+        """Validate contribution request"""
+        # Validate pattern
+        if not pattern or len(pattern) < 10:
+            raise ValueError("pattern must be at least 10 characters")
+        if len(pattern) > 500:
+            raise ValueError("pattern must be at most 500 characters")
+
+        # Validate patternHash (required per LLD §2.4)
+        if not pattern_hash or not isinstance(pattern_hash, str):
+            raise ValueError("pattern_hash is required and must be a string")
+
+        # Validate domain
+        if not domain:
+            raise ValueError("domain is required")
+
+        # Validate tags
+        if not tags or len(tags) == 0:
+            raise ValueError("tags must be a non-empty list")
+        if len(tags) > 10:
+            raise ValueError("tags must have at most 10 items")
+
+        # Validate metrics (required per LLD §2.4)
+        if not metrics or not isinstance(metrics, HeuristicMetrics):
+            raise ValueError("metrics is required and must be a HeuristicMetrics instance")
+
+        if not isinstance(metrics.success_rate, (int, float)):
+            raise ValueError("metrics.success_rate must be a number")
+        if metrics.success_rate < 0 or metrics.success_rate > 1:
+            raise ValueError("metrics.success_rate must be between 0 and 1")
+
+        if not isinstance(metrics.sample_size, int) or metrics.sample_size < 1:
+            raise ValueError("metrics.sample_size must be a positive integer")
+
+        if not isinstance(metrics.confidence, (int, float)):
+            raise ValueError("metrics.confidence must be a number")
+        if metrics.confidence < 0 or metrics.confidence > 1:
+            raise ValueError("metrics.confidence must be between 0 and 1")
+
+        # Validate encryptedContentRef (required per LLD §2.4)
+        if not encrypted_content_ref or not isinstance(encrypted_content_ref, str):
+            raise ValueError("encrypted_content_ref is required and must be a string")
+
+    def _validate_query_request(self, query_text: str, limit: int):
+        """Validate query request"""
+        if not query_text or len(query_text) < 5:
+            raise ValueError("query_text must be at least 5 characters")
+        if len(query_text) > 500:
+            raise ValueError("query_text must be at most 500 characters")
+        if limit < 1 or limit > 50:
+            raise ValueError("limit must be between 1 and 50")

xache/services/extraction.py

@@ -0,0 +1,173 @@
+"""
+Extraction Service - AI-powered memory extraction from conversations
+"""
+
+from typing import List, Optional, Dict, Any
+from dataclasses import dataclass
+
+
+@dataclass
+class ExtractedMemory:
+    """Extracted memory from conversation"""
+    content: str
+    type: str  # 'preference', 'fact', 'pattern', 'error_fix', 'insight'
+    context: str
+    confidence: float
+    source_text: Optional[str] = None
+    metadata: Optional[Dict[str, Any]] = None
+
+
+@dataclass
+class ExtractionResult:
+    """Result from memory extraction"""
+    memories: List[ExtractedMemory]
+    total_extracted: int
+    stored_count: int
+    skipped_count: int
+    processing_time_ms: int
+
+
+@dataclass
+class ExtractMemoriesRequest:
+    """Request for memory extraction"""
+    conversation: str
+    context: Optional[str] = None
+    types: Optional[List[str]] = None
+    auto_store: bool = True
+    min_confidence: float = 0.7
+
+
+class ExtractionService:
+    """
+    Extraction service for AI-powered memory extraction
+
+    Automatically extracts valuable memories from conversations,
+    including user preferences, facts, patterns, error fixes, and insights.
+    """
+
+    def __init__(self, client):
+        self.client = client
+
+    async def extract(self, request: ExtractMemoriesRequest) -> ExtractionResult:
+        """
+        Extract memories from a conversation
+
+        Args:
+            request: Extraction request with conversation and options
+
+        Returns:
+            Extraction result with extracted memories
+
+        Example:
+            ```python
+            from xache.services.extraction import ExtractMemoriesRequest
+
+            result = await client.extraction.extract(ExtractMemoriesRequest(
+                conversation="User: I prefer dark mode for all apps.\\nAssistant: ...",
+                context="user-preferences",
+                auto_store=True,
+                min_confidence=0.8
+            ))
+
+            print(f"Extracted {result.total_extracted} memories")
+            for m in result.memories:
+                print(f"  [{m.type}] {m.content} (confidence: {m.confidence})")
+            ```
+        """
+        body = {
+            "conversation": request.conversation,
+            "autoStore": request.auto_store,
+            "minConfidence": request.min_confidence,
+        }
+
+        if request.context:
+            body["context"] = request.context
+        if request.types:
+            body["types"] = request.types
+
+        response = await self.client.request("POST", "/v1/extraction/extract", body)
+
+        if not response.success or not response.data:
+            raise Exception(
+                response.error.get("message", "Failed to extract memories")
+                if response.error
+                else "Failed to extract memories"
+            )
+
+        data = response.data
+        return ExtractionResult(
+            memories=[
+                ExtractedMemory(
+                    content=m["content"],
+                    type=m["type"],
+                    context=m.get("context", ""),
+                    confidence=m["confidence"],
+                    source_text=m.get("sourceText"),
+                    metadata=m.get("metadata"),
+                )
+                for m in data.get("memories", [])
+            ],
+            total_extracted=data.get("totalExtracted", 0),
+            stored_count=data.get("storedCount", 0),
+            skipped_count=data.get("skippedCount", 0),
+            processing_time_ms=data.get("processingTimeMs", 0),
+        )
+
+    async def analyze(self, conversation: str) -> Dict[str, Any]:
+        """
+        Analyze a conversation without storing memories
+
+        Args:
+            conversation: Conversation text to analyze
+
+        Returns:
+            Analysis result with potential memories
+
+        Example:
+            ```python
+            analysis = await client.extraction.analyze(
+                "User: I always use vim keybindings..."
+            )
+
+            print(f"Found {len(analysis['potentialMemories'])} potential memories")
+            ```
+        """
+        response = await self.client.request(
+            "POST", "/v1/extraction/analyze", {"conversation": conversation}
+        )
+
+        if not response.success or not response.data:
+            raise Exception(
+                response.error.get("message", "Failed to analyze conversation")
+                if response.error
+                else "Failed to analyze conversation"
+            )
+
+        return response.data
+
+    async def get_types(self) -> List[Dict[str, Any]]:
+        """
+        Get supported memory types for extraction
+
+        Returns:
+            List of supported memory types with descriptions
+
+        Example:
+            ```python
+            types = await client.extraction.get_types()
+            for t in types:
+                print(f"{t['type']}: {t['description']}")
+            ```
+        """
+        response = await self.client.request(
+            "GET", "/v1/extraction/types", skip_auth=True
+        )
+
+        if not response.success or not response.data:
+            raise Exception(
+                response.error.get("message", "Failed to get extraction types")
+                if response.error
+                else "Failed to get extraction types"
+            )
+
+        return response.data.get("types", [])

xache/services/facilitator.py

@@ -0,0 +1,296 @@
+"""
+Facilitator Service - x402 v2 facilitator selection and management
+"""
+
+from typing import List, Optional, Dict, Any, Literal
+from dataclasses import dataclass, field
+import time
+
+
+# Type aliases
+NetworkId = Literal['base', 'base-sepolia', 'solana', 'solana-devnet']
+PaymentScheme = Literal['exact']
+ChainType = Literal['evm', 'solana']
+
+
+@dataclass
+class FacilitatorConfig:
+    """Facilitator configuration"""
+    id: str
+    name: str
+    chains: List[ChainType]
+    networks: List[NetworkId]
+    schemes: List[PaymentScheme]
+    priority: int
+    healthy: bool = True
+    avg_latency_ms: Optional[int] = None
+    last_health_check: Optional[int] = None
+
+
+@dataclass
+class FacilitatorPreferences:
+    """User preferences for facilitator selection"""
+    preferred_facilitators: List[str] = field(default_factory=list)
+    avoid_networks: List[NetworkId] = field(default_factory=list)
+    max_latency_ms: Optional[int] = None
+    preferred_chain: Optional[ChainType] = None
+
+
+@dataclass
+class FacilitatorSelection:
+    """Selected facilitator with reasoning"""
+    facilitator: FacilitatorConfig
+    reason: Literal['preference', 'priority', 'latency', 'fallback']
+    alternatives: List[FacilitatorConfig] = field(default_factory=list)
+
+
+class FacilitatorService:
+    """
+    Facilitator service for x402 v2 payment facilitator selection
+
+    Manages facilitator preferences and selection for payment processing.
+    Uses a hardcoded registry of available facilitators.
+    """
+
+    def __init__(self, client):
+        self.client = client
+        self._preferences = FacilitatorPreferences()
+        self._cached_facilitators: List[FacilitatorConfig] = []
+        self._last_fetch_time: int = 0
+        self._cache_duration_ms = 300000  # 5 minutes
+
+    def set_preferences(self, preferences: Dict[str, Any]) -> None:
+        """
+        Set facilitator preferences for payment routing
+
+        Args:
+            preferences: Dict with optional keys:
+                - preferred_facilitators: List of facilitator IDs
+                - avoid_networks: List of networks to avoid
+                - max_latency_ms: Maximum acceptable latency
+                - preferred_chain: 'evm' or 'solana'
+
+        Example:
+            ```python
+            client.facilitators.set_preferences({
+                'preferred_facilitators': ['cdp'],
+                'preferred_chain': 'solana',
+                'max_latency_ms': 5000,
+            })
+            ```
+        """
+        if 'preferred_facilitators' in preferences:
+            self._preferences.preferred_facilitators = preferences['preferred_facilitators']
+        if 'avoid_networks' in preferences:
+            self._preferences.avoid_networks = preferences['avoid_networks']
+        if 'max_latency_ms' in preferences:
+            self._preferences.max_latency_ms = preferences['max_latency_ms']
+        if 'preferred_chain' in preferences:
+            self._preferences.preferred_chain = preferences['preferred_chain']
+
+    def get_preferences(self) -> FacilitatorPreferences:
+        """Get current facilitator preferences"""
+        return self._preferences
+
+    def clear_preferences(self) -> None:
+        """Clear facilitator preferences"""
+        self._preferences = FacilitatorPreferences()
+
+    def get_default_facilitator(self) -> FacilitatorConfig:
+        """
+        Get the default CDP facilitator configuration
+        This is the built-in facilitator for Coinbase Developer Platform
+        """
+        return FacilitatorConfig(
+            id='cdp',
+            name='Coinbase Developer Platform',
+            chains=['evm', 'solana'],
+            networks=['base', 'base-sepolia', 'solana', 'solana-devnet'],
+            schemes=['exact'],
+            priority=100,
+            healthy=True,
+        )
+
+    async def list(self, force_refresh: bool = False) -> List[FacilitatorConfig]:
+        """
+        List all available facilitators
+        Returns the default CDP facilitator. Cached for performance.
+
+        Args:
+            force_refresh: Force refresh (ignored - using hardcoded registry)
+
+        Returns:
+            List of facilitator configurations
+
+        Example:
+            ```python
+            facilitators = await client.facilitators.list()
+
+            for f in facilitators:
+                print(f"{f.name}: {f.chains}")
+            ```
+        """
+        now = int(time.time() * 1000)
+
+        # Check cache
+        if (
+            self._cached_facilitators
+            and not force_refresh
+            and (now - self._last_fetch_time) < self._cache_duration_ms
+        ):
+            return self._cached_facilitators
+
+        # Return default facilitator (CDP)
+        # In future, this could fetch from a /v1/facilitators endpoint
+        self._cached_facilitators = [self.get_default_facilitator()]
+        self._last_fetch_time = now
+
+        return self._cached_facilitators
+
+    async def get(self, facilitator_id: str) -> Optional[FacilitatorConfig]:
+        """
+        Get facilitator by ID
+
+        Args:
+            facilitator_id: Facilitator identifier
+
+        Returns:
+            Facilitator configuration or None if not found
+
+        Example:
+            ```python
+            facilitator = await client.facilitators.get("cdp")
+            if facilitator:
+                print(f"Found: {facilitator.name}")
+            ```
+        """
+        facilitators = await self.list()
+        return next(
+            (f for f in facilitators if f.id == facilitator_id), None
+        )
+
+    async def select(
+        self,
+        chain: ChainType,
+        network: Optional[NetworkId] = None,
+        scheme: PaymentScheme = 'exact',
+    ) -> Optional[FacilitatorSelection]:
+        """
+        Select optimal facilitator based on criteria
+
+        Args:
+            chain: Blockchain chain (evm, solana)
+            network: Network ID (base, base-sepolia, solana-devnet, etc.)
+            scheme: Payment scheme (exact)
+
+        Returns:
+            Selected facilitator with reason, or None if no match
+
+        Example:
+            ```python
+            selection = await client.facilitators.select(
+                chain="evm",
+                network="base-sepolia"
+            )
+
+            if selection:
+                print(f"Selected: {selection.facilitator.name}")
+                print(f"Reason: {selection.reason}")
+            ```
+        """
+        facilitators = await self.list()
+
+        # Filter by requirements
+        candidates = [
+            f for f in facilitators
+            if chain in f.chains
+            and (network is None or network in f.networks)
+            and scheme in f.schemes
+            and f.healthy is not False
+        ]
+
+        if not candidates:
+            return None
+
+        # Apply preferences
+        if self._preferences.avoid_networks:
+            candidates = [
+                f for f in candidates
+                if not any(n in f.networks for n in self._preferences.avoid_networks)
+            ]
+
+        if self._preferences.preferred_facilitators:
+            preferred = [
+                f for f in candidates
+                if f.id in self._preferences.preferred_facilitators
+            ]
+            if preferred:
+                candidates = preferred
+
+        if self._preferences.max_latency_ms:
+            within_latency = [
+                f for f in candidates
+                if f.avg_latency_ms is None or f.avg_latency_ms <= self._preferences.max_latency_ms
+            ]
+            if within_latency:
+                candidates = within_latency
+
+        # Sort by priority (descending) then latency (ascending)
+        def sort_key(f: FacilitatorConfig):
+            latency = f.avg_latency_ms if f.avg_latency_ms is not None else float('inf')
+            return (-f.priority, latency)
+
+        candidates.sort(key=sort_key)
+
+        selected = candidates[0]
+        alternatives = candidates[1:]
+
+        # Determine selection reason
+        reason: Literal['preference', 'priority', 'latency', 'fallback'] = 'priority'
+        if selected.id in self._preferences.preferred_facilitators:
+            reason = 'preference'
+        elif len(candidates) > 1 and selected.avg_latency_ms is not None:
+            reason = 'latency'
+        elif len(candidates) == 1:
+            reason = 'fallback'
+
+        return FacilitatorSelection(
+            facilitator=selected,
+            reason=reason,
+            alternatives=alternatives,
+        )
+
+    async def supports(
+        self,
+        facilitator_id: str,
+        chain: ChainType,
+        network: NetworkId,
+        scheme: PaymentScheme = 'exact',
+    ) -> bool:
+        """
+        Check if a specific facilitator supports the given requirements
+
+        Args:
+            facilitator_id: Facilitator ID
+            chain: Chain type
+            network: Network ID
+            scheme: Payment scheme
+
+        Returns:
+            True if supported
+        """
+        facilitator = await self.get(facilitator_id)
+        if not facilitator:
+            return False
+
+        return (
+            chain in facilitator.chains
+            and network in facilitator.networks
+            and scheme in facilitator.schemes
+            and facilitator.healthy is not False
+        )
+
+    def clear_cache(self):
+        """Clear facilitator cache to force refresh on next list()"""
+        self._cached_facilitators = []
+        self._last_fetch_time = 0