xache 5.1.0__py3-none-any.whl → 5.2.0__py3-none-any.whl

xache/__init__.py

@@ -25,7 +25,7 @@ Example:
     ```
 """
 
-__version__ = "5.0.0"
+__version__ = "5.2.0"
 
 # Main client
 from .client import XacheClient
@@ -75,6 +75,21 @@ from .services import (
     CollectiveService,
     BudgetService,
     ReceiptsService,
+    ExtractionService,
+)
+
+# Extraction types
+from .services.extraction import (
+    LLMProvider,
+    LLMApiFormat,
+    LLMConfig,
+    LLMConfigApiKey,
+    LLMConfigEndpoint,
+    LLMConfigXacheManaged,
+    ExtractedMemory,
+    ExtractionMetadata,
+    ExtractionResult,
+    ExtractionOptions,
 )
 
 # Utilities
@@ -130,6 +145,18 @@ __all__ = [
     "CollectiveService",
     "BudgetService",
     "ReceiptsService",
+    "ExtractionService",
+    # Extraction types
+    "LLMProvider",
+    "LLMApiFormat",
+    "LLMConfig",
+    "LLMConfigApiKey",
+    "LLMConfigEndpoint",
+    "LLMConfigXacheManaged",
+    "ExtractedMemory",
+    "ExtractionMetadata",
+    "ExtractionResult",
+    "ExtractionOptions",
     # Utilities
     "RetryPolicy",
     "with_retry",

xache/services/extraction.py

@@ -1,173 +1,473 @@
 """
 Extraction Service - AI-powered memory extraction from conversations
+Supports 10 major LLM providers plus custom endpoints
 """
 
-from typing import List, Optional, Dict, Any
-from dataclasses import dataclass
+from typing import List, Optional, Dict, Any, Union, Literal
+from dataclasses import dataclass, field
+
+
+# LLM Provider type - matches TypeScript SDK
+LLMProvider = Literal[
+    'anthropic', 'openai', 'google', 'mistral', 'groq',
+    'together', 'fireworks', 'cohere', 'xai', 'deepseek'
+]
+
+# LLM API format for custom endpoints
+LLMApiFormat = Literal['openai', 'anthropic', 'cohere']
+
+
+@dataclass
+class LLMConfigApiKey:
+    """LLM config for api-key mode - use your own API key with major providers"""
+    type: Literal['api-key'] = 'api-key'
+    provider: LLMProvider = 'anthropic'
+    api_key: str = ''
+    model: Optional[str] = None
+
+
+@dataclass
+class LLMConfigEndpoint:
+    """LLM config for endpoint mode - custom/self-hosted endpoints"""
+    type: Literal['endpoint'] = 'endpoint'
+    url: str = ''
+    auth_token: Optional[str] = None
+    model: Optional[str] = None
+    format: LLMApiFormat = 'openai'
+
+
+@dataclass
+class LLMConfigXacheManaged:
+    """LLM config for xache-managed mode - Xache provides the LLM"""
+    type: Literal['xache-managed'] = 'xache-managed'
+    provider: Literal['anthropic', 'openai'] = 'anthropic'
+    model: Optional[str] = None
+
+
+# Union type for LLM config
+LLMConfig = Union[LLMConfigApiKey, LLMConfigEndpoint, LLMConfigXacheManaged]
 
 
 @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
+    type: str  # 'preference', 'fact', 'pattern', 'relationship', etc.
+    data: Dict[str, Any] = field(default_factory=dict)
+    reasoning: Optional[str] = None
+    confidence: float = 1.0
+
+
+@dataclass
+class ExtractionMetadata:
+    """Metadata about the extraction operation"""
+    extraction_time: int = 0
+    llm_provider: str = ''
+    llm_model: str = ''
+    total_extractions: int = 0
+    stored_count: int = 0
+    payment_receipt_id: Optional[str] = None
 
 
 @dataclass
 class ExtractionResult:
     """Result from memory extraction"""
-    memories: List[ExtractedMemory]
-    total_extracted: int
-    stored_count: int
-    skipped_count: int
-    processing_time_ms: int
+    extractions: List[ExtractedMemory] = field(default_factory=list)
+    stored: Optional[List[str]] = None
+    metadata: ExtractionMetadata = field(default_factory=ExtractionMetadata)
 
 
 @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 ExtractionOptions:
+    """Options for extraction"""
+    confidence_threshold: Optional[float] = None
+    context_hint: Optional[str] = None
+    auto_store: bool = False
+    subject: Optional[Dict[str, Any]] = None
 
 
 class ExtractionService:
     """
     Extraction service for AI-powered memory extraction
 
-    Automatically extracts valuable memories from conversations,
-    including user preferences, facts, patterns, error fixes, and insights.
+    Supports three LLM modes:
+    1. api-key: Use your own API key with major providers (10 supported)
+       - anthropic, openai, google, mistral, groq
+       - together, fireworks, cohere, xai, deepseek
+       - Cost: $0.002 per extraction
+
+    2. endpoint: Use custom/self-hosted endpoints
+       - Ollama, OpenRouter, vLLM, Modal, Replicate, etc.
+       - Supports openai, anthropic, cohere API formats
+       - Cost: $0.002 per extraction
+
+    3. xache-managed: Xache provides the LLM
+       - Requires PII-scrubbed traces
+       - Cost: $0.011 per extraction
+
+    Example:
+        ```python
+        from xache.services.extraction import LLMConfigApiKey
+
+        # Using your own Anthropic key
+        result = await client.extraction.extract(
+            trace="User: I prefer dark mode\\nAgent: I'll remember that",
+            llm_config=LLMConfigApiKey(
+                provider='anthropic',
+                api_key='sk-ant-...',
+            ),
+            options=ExtractionOptions(
+                confidence_threshold=0.8,
+                auto_store=True,
+            )
+        )
+
+        print(f"Extracted {len(result.extractions)} memories")
+        ```
     """
 
+    # Supported providers for api-key mode
+    SUPPORTED_PROVIDERS: List[str] = [
+        'anthropic', 'openai', 'google', 'mistral', 'groq',
+        'together', 'fireworks', 'cohere', 'xai', 'deepseek'
+    ]
+
+    # Supported API formats for endpoint mode
+    SUPPORTED_FORMATS: List[str] = ['openai', 'anthropic', 'cohere']
+
     def __init__(self, client):
         self.client = client
 
-    async def extract(self, request: ExtractMemoriesRequest) -> ExtractionResult:
+    def _build_llm_config_dict(self, llm_config: LLMConfig) -> Dict[str, Any]:
+        """Convert dataclass to API-compatible dict"""
+        if isinstance(llm_config, LLMConfigApiKey):
+            config = {
+                'type': 'api-key',
+                'provider': llm_config.provider,
+                'apiKey': llm_config.api_key,
+            }
+            if llm_config.model:
+                config['model'] = llm_config.model
+            return config
+
+        elif isinstance(llm_config, LLMConfigEndpoint):
+            config = {
+                'type': 'endpoint',
+                'url': llm_config.url,
+                'format': llm_config.format,
+            }
+            if llm_config.auth_token:
+                config['authToken'] = llm_config.auth_token
+            if llm_config.model:
+                config['model'] = llm_config.model
+            return config
+
+        elif isinstance(llm_config, LLMConfigXacheManaged):
+            config = {
+                'type': 'xache-managed',
+                'provider': llm_config.provider,
+            }
+            if llm_config.model:
+                config['model'] = llm_config.model
+            return config
+
+        else:
+            # Assume it's already a dict
+            return llm_config
+
+    async def extract(
+        self,
+        trace: Union[str, Dict[str, Any]],
+        llm_config: LLMConfig,
+        options: Optional[ExtractionOptions] = None,
+    ) -> ExtractionResult:
         """
-        Extract memories from a conversation
+        Extract memories from agent trace using specified LLM
 
         Args:
-            request: Extraction request with conversation and options
+            trace: The conversation trace (string or object)
+            llm_config: LLM configuration (api-key, endpoint, or xache-managed)
+            options: Extraction options
 
         Returns:
-            Extraction result with extracted memories
+            ExtractionResult with extracted memories
 
         Example:
             ```python
-            from xache.services.extraction import ExtractMemoriesRequest
+            # Using OpenAI
+            result = await client.extraction.extract(
+                trace="User: I always use vim keybindings...",
+                llm_config=LLMConfigApiKey(
+                    provider='openai',
+                    api_key='sk-...',
+                    model='gpt-4-turbo',
+                ),
+                options=ExtractionOptions(auto_store=True),
+            )
 
-            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
-            ))
+            # Using custom endpoint (Ollama)
+            result = await client.extraction.extract(
+                trace=conversation,
+                llm_config=LLMConfigEndpoint(
+                    url='http://localhost:11434/v1/chat/completions',
+                    model='llama2',
+                    format='openai',
+                ),
+            )
 
-            print(f"Extracted {result.total_extracted} memories")
-            for m in result.memories:
-                print(f"  [{m.type}] {m.content} (confidence: {m.confidence})")
+            # Using Xache-managed LLM
+            result = await client.extraction.extract(
+                trace=scrubbed_trace,  # Must be PII-scrubbed
+                llm_config=LLMConfigXacheManaged(
+                    provider='anthropic',
+                ),
+            )
             ```
         """
-        body = {
-            "conversation": request.conversation,
-            "autoStore": request.auto_store,
-            "minConfidence": request.min_confidence,
+        body: Dict[str, Any] = {
+            'trace': trace,
+            'llmConfig': self._build_llm_config_dict(llm_config),
         }
 
-        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 options:
+            opts: Dict[str, Any] = {}
+            if options.confidence_threshold is not None:
+                opts['confidenceThreshold'] = options.confidence_threshold
+            if options.context_hint:
+                opts['contextHint'] = options.context_hint
+            if options.auto_store:
+                opts['autoStore'] = options.auto_store
+            if options.subject:
+                opts['subject'] = options.subject
+            if opts:
+                body['options'] = opts
+
+        response = await self.client.request('POST', '/v1/extract', body)
 
         if not response.success or not response.data:
             raise Exception(
-                response.error.get("message", "Failed to extract memories")
+                response.error.get('message', 'Failed to extract memories')
                 if response.error
-                else "Failed to extract memories"
+                else 'Failed to extract memories'
             )
 
         data = response.data
+
+        # Parse extractions
+        extractions = []
+        for m in data.get('extractions', []):
+            extractions.append(ExtractedMemory(
+                type=m.get('type', 'unknown'),
+                data=m.get('data', {}),
+                reasoning=m.get('reasoning'),
+                confidence=m.get('confidence', 1.0),
+            ))
+
+        # Parse metadata
+        meta = data.get('metadata', {})
+        metadata = ExtractionMetadata(
+            extraction_time=meta.get('extractionTime', 0),
+            llm_provider=meta.get('llmProvider', ''),
+            llm_model=meta.get('llmModel', ''),
+            total_extractions=meta.get('totalExtractions', 0),
+            stored_count=meta.get('storedCount', 0),
+            payment_receipt_id=meta.get('paymentReceiptId'),
+        )
+
         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),
+            extractions=extractions,
+            stored=data.get('stored'),
+            metadata=metadata,
         )
 
-    async def analyze(self, conversation: str) -> Dict[str, Any]:
+    async def extract_with_anthropic(
+        self,
+        trace: Union[str, Dict[str, Any]],
+        api_key: str,
+        model: Optional[str] = None,
+        auto_store: bool = False,
+        confidence_threshold: Optional[float] = None,
+        context_hint: Optional[str] = None,
+    ) -> ExtractionResult:
         """
-        Analyze a conversation without storing memories
+        Convenience method: Extract memories using Anthropic
 
         Args:
-            conversation: Conversation text to analyze
-
-        Returns:
-            Analysis result with potential memories
+            trace: Conversation trace
+            api_key: Your Anthropic API key
+            model: Model name (default: claude-sonnet-4-20250514)
+            auto_store: Whether to auto-store extracted memories
+            confidence_threshold: Minimum confidence threshold
+            context_hint: Context hint for extraction
 
         Example:
             ```python
-            analysis = await client.extraction.analyze(
-                "User: I always use vim keybindings..."
+            result = await client.extraction.extract_with_anthropic(
+                trace="User: I prefer dark mode...",
+                api_key="sk-ant-...",
+                auto_store=True,
             )
-
-            print(f"Found {len(analysis['potentialMemories'])} potential memories")
             ```
         """
-        response = await self.client.request(
-            "POST", "/v1/extraction/analyze", {"conversation": conversation}
+        return await self.extract(
+            trace=trace,
+            llm_config=LLMConfigApiKey(
+                provider='anthropic',
+                api_key=api_key,
+                model=model,
+            ),
+            options=ExtractionOptions(
+                auto_store=auto_store,
+                confidence_threshold=confidence_threshold,
+                context_hint=context_hint,
+            ),
         )
 
-        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"
-            )
+    async def extract_with_openai(
+        self,
+        trace: Union[str, Dict[str, Any]],
+        api_key: str,
+        model: Optional[str] = None,
+        auto_store: bool = False,
+        confidence_threshold: Optional[float] = None,
+        context_hint: Optional[str] = None,
+    ) -> ExtractionResult:
+        """
+        Convenience method: Extract memories using OpenAI
+
+        Args:
+            trace: Conversation trace
+            api_key: Your OpenAI API key
+            model: Model name (default: gpt-4-turbo)
+            auto_store: Whether to auto-store extracted memories
+            confidence_threshold: Minimum confidence threshold
+            context_hint: Context hint for extraction
 
-        return response.data
+        Example:
+            ```python
+            result = await client.extraction.extract_with_openai(
+                trace="User: I prefer dark mode...",
+                api_key="sk-...",
+                model="gpt-4-turbo",
+                auto_store=True,
+            )
+            ```
+        """
+        return await self.extract(
+            trace=trace,
+            llm_config=LLMConfigApiKey(
+                provider='openai',
+                api_key=api_key,
+                model=model,
+            ),
+            options=ExtractionOptions(
+                auto_store=auto_store,
+                confidence_threshold=confidence_threshold,
+                context_hint=context_hint,
+            ),
+        )
 
-    async def get_types(self) -> List[Dict[str, Any]]:
+    async def extract_with_endpoint(
+        self,
+        trace: Union[str, Dict[str, Any]],
+        url: str,
+        model: str,
+        auth_token: Optional[str] = None,
+        format: LLMApiFormat = 'openai',
+        auto_store: bool = False,
+        confidence_threshold: Optional[float] = None,
+        context_hint: Optional[str] = None,
+    ) -> ExtractionResult:
         """
-        Get supported memory types for extraction
+        Extract memories using custom endpoint (Ollama, OpenRouter, vLLM, etc.)
 
-        Returns:
-            List of supported memory types with descriptions
+        Args:
+            trace: Conversation trace
+            url: Endpoint URL
+            model: Model name
+            auth_token: Optional auth token
+            format: API format (openai, anthropic, cohere)
+            auto_store: Whether to auto-store extracted memories
+            confidence_threshold: Minimum confidence threshold
+            context_hint: Context hint for extraction
 
         Example:
             ```python
-            types = await client.extraction.get_types()
-            for t in types:
-                print(f"{t['type']}: {t['description']}")
+            # Ollama
+            result = await client.extraction.extract_with_endpoint(
+                trace="User: I prefer dark mode...",
+                url="http://localhost:11434/v1/chat/completions",
+                model="llama2",
+                format="openai",
+            )
+
+            # OpenRouter
+            result = await client.extraction.extract_with_endpoint(
+                trace="User: ...",
+                url="https://openrouter.ai/api/v1/chat/completions",
+                model="anthropic/claude-3-sonnet",
+                auth_token="sk-or-...",
+                format="openai",
+            )
             ```
         """
-        response = await self.client.request(
-            "GET", "/v1/extraction/types", skip_auth=True
+        return await self.extract(
+            trace=trace,
+            llm_config=LLMConfigEndpoint(
+                url=url,
+                model=model,
+                auth_token=auth_token,
+                format=format,
+            ),
+            options=ExtractionOptions(
+                auto_store=auto_store,
+                confidence_threshold=confidence_threshold,
+                context_hint=context_hint,
+            ),
         )
 
-        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"
-            )
+    async def extract_with_xache_llm(
+        self,
+        trace: Union[str, Dict[str, Any]],
+        provider: Literal['anthropic', 'openai'] = 'anthropic',
+        model: Optional[str] = None,
+        auto_store: bool = False,
+        confidence_threshold: Optional[float] = None,
+        context_hint: Optional[str] = None,
+    ) -> ExtractionResult:
+        """
+        Extract memories using Xache-managed LLM
+
+        IMPORTANT: Traces must be scrubbed of PII before calling this method.
+
+        Args:
+            trace: PII-scrubbed conversation trace
+            provider: Xache-managed provider (anthropic or openai)
+            model: Optional model override
+            auto_store: Whether to auto-store extracted memories
+            confidence_threshold: Minimum confidence threshold
+            context_hint: Context hint for extraction
 
-        return response.data.get("types", [])
+        Example:
+            ```python
+            # Scrub PII first
+            scrubbed = scrub_trace(raw_trace)
+
+            result = await client.extraction.extract_with_xache_llm(
+                trace=scrubbed,
+                provider="anthropic",
+                auto_store=True,
+            )
+            ```
+        """
+        return await self.extract(
+            trace=trace,
+            llm_config=LLMConfigXacheManaged(
+                provider=provider,
+                model=model,
+            ),
+            options=ExtractionOptions(
+                auto_store=auto_store,
+                confidence_threshold=confidence_threshold,
+                context_hint=context_hint,
+            ),
+        )

{xache-5.1.0.dist-info → xache-5.2.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: xache
-Version: 5.1.0
+Version: 5.2.0
 Summary: Official Python SDK for Xache Protocol
 Home-page: https://github.com/xache-ai/xache-protocol
 Author: Xache Protocol

{xache-5.1.0.dist-info → xache-5.2.0.dist-info}/RECORD

@@ -1,4 +1,4 @@
-xache/__init__.py,sha256=RFenUVyM4Mt5ycz_OvqYNg2oZVwrOF9EogK3jZ_yEpE,2989
+xache/__init__.py,sha256=K1QXmT5R7nbiTwDwQUz53J1vN6n73NNUA4yVdqCMfFs,3559
 xache/client.py,sha256=ABjFJFnrv4KmY5ihBXK5YC8sg50s48tGdDUSKq7Vd8g,10217
 xache/errors.py,sha256=sHLjfKGw1JxN3TdV_bswG9erH2vVAOFPzvOkWb1k0EI,5007
 xache/types.py,sha256=YpepxdWdWbkCRzRWQX9wckCL1R6zjHswrWTrI3CnrB4,9479
@@ -10,7 +10,7 @@ xache/payment/handler.py,sha256=X3RL1mvjHCn5FbloOjiNUv_CythRlJU0Vo524lx4DLg,8901
 xache/services/__init__.py,sha256=ERuZXa7R-Iv0oFBknxJiBO5nJC-oCtIut_4VITw_uOE,775
 xache/services/budget.py,sha256=6sZ3nojb888a3k774XPnJHfdkqIC2Y1BxJKt8zy76V0,10599
 xache/services/collective.py,sha256=utYLIHv3tuOYHbdYJYXqIy1hS-aYIRems744CsCUIUw,6229
-xache/services/extraction.py,sha256=5KElr4ldBR3kcOofvz4d3NwAuTvKVskZ-NTQ7BI2ChY,5317
+xache/services/extraction.py,sha256=wtqsFMqCQUrY9idXYktkPdkdgKyZGuO8OdCuKBWjlUg,15412
 xache/services/facilitator.py,sha256=FlJh6YvPd1xiCdt6Y8Y9NpbmJI0o92Dcp3ZgzeR14bM,11512
 xache/services/identity.py,sha256=gOs5fN9juyoBfXQVm-G4whyUMJ6Oha2VmP_i3mQw0G0,13478
 xache/services/memory.py,sha256=ng9_cwL4jE4c3gdlwQDZyqaBdQgwtqApEwj0LkZYWRY,13290
@@ -24,7 +24,7 @@ xache/utils/__init__.py,sha256=8VrQm0QnyqxdplpCG7BDRiAVdBGWrjUs9ipH2zsJOBM,106
 xache/utils/cache.py,sha256=9zhE9dIXFTofj7jz1TX-FkAqmclqoYXTe4FwwGLeKT4,5479
 xache/utils/http.py,sha256=rIQCYvYrziNrNfEbOnIKbCOGGf7bcdTvZrrU_W6CcZA,6547
 xache/utils/retry.py,sha256=OJYBGozKIoteCvKw50dqd4ThhOo-WisorcKa8Tr6mnE,2860
-xache-5.1.0.dist-info/METADATA,sha256=Epfq9BxGeZ913xE5fWrvMoiBaJvesUQ-fVJEX5FcAdA,8469
-xache-5.1.0.dist-info/WHEEL,sha256=wUyA8OaulRlbfwMtmQsvNngGrxQHAvkKcvRmdizlJi0,92
-xache-5.1.0.dist-info/top_level.txt,sha256=FBWE4IVb7zoLS9arsdrl97QVETlwFvYGAx6xEJZOEUU,6
-xache-5.1.0.dist-info/RECORD,,
+xache-5.2.0.dist-info/METADATA,sha256=Er8B6d8cJ2_qkmkJTrlZFK8UvNlf6jYeyFwTTeRXJBg,8469
+xache-5.2.0.dist-info/WHEEL,sha256=wUyA8OaulRlbfwMtmQsvNngGrxQHAvkKcvRmdizlJi0,92
+xache-5.2.0.dist-info/top_level.txt,sha256=FBWE4IVb7zoLS9arsdrl97QVETlwFvYGAx6xEJZOEUU,6
+xache-5.2.0.dist-info/RECORD,,