memoryintelligence 1.0.0__py3-none-any.whl

memoryintelligence/memory_client.py

@@ -0,0 +1,688 @@
+"""
+Memory Intelligence SDK - Client
+================================
+
+The main client for interacting with Memory Intelligence.
+Designed around the six core problem statements:
+
+1. Privacy-Personalization Paradox → retention_policy="meaning_only"
+2. Black Box Accountability → explain=True on all operations
+3. Proprietary Data Paralysis → EdgeClient for on-prem
+4. Context Cost Catastrophe → Compressed meaning retrieval
+5. Knowledge Silo Epidemic → Scope isolation with cryptographic boundaries
+6. Attribution Extinction → provenance_mode="authorship"
+
+Usage:
+    from memoryintelligence import MemoryClient
+    
+    mi = MemoryClient(api_key="mi_sk_...")
+    
+    # Process content → meaning
+    umo = mi.process("Meeting notes from today", user_ulid="01ABC...")
+    
+    # Search meaning
+    results = mi.search("What did we discuss?", user_ulid="01ABC...")
+    
+    # Match for recommendations
+    score = mi.match(user_ulid, candidate_ulid, explain=True)
+    
+    # Delete for GDPR
+    mi.delete(user_ulid="01ABC...")
+
+Author: Memory Intelligence Team
+Version: 1.0.0
+"""
+
+import httpx
+import logging
+from datetime import datetime
+from typing import Any, Dict, List, Optional, Union
+from pathlib import Path
+
+from .mi_types import (
+    # Enums
+    Scope,
+    RetentionPolicy,
+    PIIHandling,
+    ProvenanceMode,
+    ExplainLevel,
+    # Response types
+    MeaningObject,
+    SearchResponse,
+    SearchResult,
+    MatchResult,
+    DeleteResult,
+    VerifyResult,
+    Explanation,
+    ExplainHuman,
+    ExplainAudit,
+    Entity,
+    Topic,
+    SVOTriple,
+    Provenance,
+    PIIDetection,
+    # Config types
+    ProcessConfig,
+    SearchConfig,
+    MatchConfig,
+    # Errors
+    MIError,
+    AuthenticationError,
+    RateLimitError,
+    ScopeViolationError,
+    PIIViolationError,
+    GovernanceError,
+)
+
+logger = logging.getLogger(__name__)
+
+
+# ============================================================================
+# API Configuration
+# ============================================================================
+
+DEFAULT_API_URL = "https://api.memoryintelligence.dev"
+DEFAULT_TIMEOUT = 30.0
+SDK_VERSION = "1.0.0"
+
+
+# ============================================================================
+# Main Client
+# ============================================================================
+
+class MemoryClient:
+    """
+    Main client for Memory Intelligence SDK.
+    
+    Provides six core operations aligned to developer pain points:
+    
+    - process() → Convert raw content to meaning (Privacy-Personalization)
+    - search() → Find relevant memories (Context Cost)
+    - match() → Compare memories for relevance (Personalization)
+    - explain() → Get explanation for any UMO (Black Box)
+    - delete() → Remove all user data (Compliance)
+    - verify_provenance() → Verify authorship/timestamp (Attribution)
+    
+    Args:
+        api_key: Your MI API key (starts with "mi_sk_")
+        org_ulid: Organization ULID (optional, derived from key)
+        base_url: API endpoint (default: production)
+        timeout: Request timeout in seconds
+    
+    Example:
+        mi = MemoryClient(api_key="mi_sk_live_abc123...")
+        
+        # Process with meaning-only retention (default)
+        umo = mi.process("Important insight", user_ulid="01ABC...")
+        
+        # Search with explanation
+        results = mi.search("What do I know about X?", user_ulid="01ABC...", explain=True)
+    """
+    
+    def __init__(
+        self,
+        api_key: str,
+        org_ulid: Optional[str] = None,
+        base_url: str = DEFAULT_API_URL,
+        timeout: float = DEFAULT_TIMEOUT,
+    ):
+        if not api_key or not api_key.startswith("mi_sk_"):
+            raise AuthenticationError(
+                "Invalid API key format. Keys should start with 'mi_sk_'"
+            )
+        
+        self.api_key = api_key
+        self.org_ulid = org_ulid
+        self.base_url = base_url.rstrip("/")
+        self.timeout = timeout
+        
+        # HTTP client with auth headers
+        self._client = httpx.Client(
+            base_url=self.base_url,
+            timeout=self.timeout,
+            headers={
+                "Authorization": f"Bearer {self.api_key}",
+                "X-MI-SDK-Version": SDK_VERSION,
+                "Content-Type": "application/json",
+            }
+        )
+        
+        logger.info(f"MemoryClient initialized (org={org_ulid})")
+    
+    def __enter__(self):
+        return self
+    
+    def __exit__(self, exc_type, exc_val, exc_tb):
+        self.close()
+    
+    def close(self):
+        """Close the HTTP client."""
+        self._client.close()
+    
+    # ========================================================================
+    # CORE OPERATION 1: PROCESS
+    # ========================================================================
+    
+    def process(
+        self,
+        content: str,
+        user_ulid: str,
+        *,
+        retention_policy: RetentionPolicy = RetentionPolicy.MEANING_ONLY,
+        pii_handling: PIIHandling = PIIHandling.EXTRACT_AND_REDACT,
+        provenance_mode: ProvenanceMode = ProvenanceMode.STANDARD,
+        scope: Scope = Scope.USER,
+        scope_id: Optional[str] = None,
+        source: str = "api",
+        metadata: Optional[Dict[str, Any]] = None,
+    ) -> MeaningObject:
+        """
+        Process raw content into a Meaning Object.
+        
+        This is the core operation: content goes in, meaning comes out,
+        raw content is discarded (by default).
+        
+        Args:
+            content: Raw text content to process
+            user_ulid: Owner's ULID
+            retention_policy: What to retain (default: meaning_only)
+            pii_handling: How to handle PII (default: extract_and_redact)
+            provenance_mode: Provenance tracking level (default: standard)
+            scope: Governance scope (default: user)
+            scope_id: Scope identifier (e.g., client_ulid for Scope.CLIENT)
+            source: Source identifier (e.g., "slack", "email")
+            metadata: Additional context
+        
+        Returns:
+            MeaningObject with entities, topics, embedding, provenance
+        
+        Raises:
+            PIIViolationError: If PII detected and pii_handling=REJECT
+            ScopeViolationError: If scope_id required but not provided
+            AuthenticationError: Invalid API key
+            RateLimitError: Rate limit exceeded
+        
+        Example:
+            # Basic processing (meaning-only, PII redacted)
+            umo = mi.process("Sarah said budget is approved", user_ulid="01ABC...")
+            
+            # With client scope isolation
+            umo = mi.process(
+                meeting_notes,
+                user_ulid="01ABC...",
+                scope=Scope.CLIENT,
+                scope_id=client_ulid
+            )
+            
+            # With authorship provenance
+            umo = mi.process(
+                article_text,
+                user_ulid="01ABC...",
+                provenance_mode=ProvenanceMode.AUTHORSHIP
+            )
+        """
+        # Validate scope_id requirement
+        if scope in (Scope.CLIENT, Scope.PROJECT, Scope.TEAM) and not scope_id:
+            raise ScopeViolationError(
+                f"scope_id required for {scope.value} scope"
+            )
+        
+        payload = {
+            "content": content,
+            "user_ulid": user_ulid,
+            "retention_policy": retention_policy.value,
+            "pii_handling": pii_handling.value,
+            "provenance_mode": provenance_mode.value,
+            "scope": scope.value,
+            "scope_id": scope_id,
+            "source": source,
+            "metadata": metadata or {},
+        }
+        
+        if self.org_ulid:
+            payload["org_ulid"] = self.org_ulid
+        
+        response = self._request("POST", "/v1/process", json=payload)
+        return self._parse_meaning_object(response)
+    
+    # ========================================================================
+    # CORE OPERATION 2: SEARCH
+    # ========================================================================
+    
+    def search(
+        self,
+        query: str,
+        user_ulid: str,
+        *,
+        scope: Scope = Scope.USER,
+        scope_id: Optional[str] = None,
+        explain: Union[bool, ExplainLevel] = False,
+        limit: int = 10,
+        offset: int = 0,
+        date_from: Optional[datetime] = None,
+        date_to: Optional[datetime] = None,
+        topics: Optional[List[str]] = None,
+        entities: Optional[List[str]] = None,
+        budget_tokens: Optional[int] = None,
+    ) -> SearchResponse:
+        """
+        Search for relevant meaning objects.
+        
+        Multi-signal ranking: semantic + temporal + entity + graph.
+        Returns compressed meaning (95% smaller than raw).
+        
+        Args:
+            query: Natural language search query
+            user_ulid: Searcher's ULID
+            scope: Search scope (default: user)
+            scope_id: Scope identifier for scoped searches
+            explain: Include explanation (default: False)
+            limit: Maximum results (default: 10)
+            offset: Pagination offset
+            date_from: Filter by date range start
+            date_to: Filter by date range end
+            topics: Filter by topics
+            entities: Filter by entities
+            budget_tokens: Maximum tokens in response (for cost control)
+        
+        Returns:
+            SearchResponse with ranked results and explanations
+        
+        Example:
+            # Basic search
+            results = mi.search("budget discussions", user_ulid="01ABC...")
+            
+            # Scoped search with explanation
+            results = mi.search(
+                "What are Acme's concerns?",
+                user_ulid="01ABC...",
+                scope=Scope.CLIENT,
+                scope_id=acme_ulid,
+                explain=True
+            )
+            
+            # Token-budgeted search
+            results = mi.search(
+                "summarize last month",
+                user_ulid="01ABC...",
+                budget_tokens=500
+            )
+        """
+        if scope in (Scope.CLIENT, Scope.PROJECT, Scope.TEAM) and not scope_id:
+            raise ScopeViolationError(
+                f"scope_id required for {scope.value} scope"
+            )
+        
+        # Normalize explain parameter
+        if isinstance(explain, bool):
+            explain_level = ExplainLevel.FULL if explain else ExplainLevel.NONE
+        else:
+            explain_level = explain
+        
+        payload = {
+            "query": query,
+            "user_ulid": user_ulid,
+            "scope": scope.value,
+            "scope_id": scope_id,
+            "explain": explain_level.value,
+            "limit": limit,
+            "offset": offset,
+            "budget_tokens": budget_tokens,
+        }
+        
+        if date_from:
+            payload["date_from"] = date_from.isoformat()
+        if date_to:
+            payload["date_to"] = date_to.isoformat()
+        if topics:
+            payload["topics"] = topics
+        if entities:
+            payload["entities"] = entities
+        if self.org_ulid:
+            payload["org_ulid"] = self.org_ulid
+        
+        response = self._request("POST", "/v1/search", json=payload)
+        return self._parse_search_response(response, query, scope)
+    
+    # ========================================================================
+    # CORE OPERATION 3: MATCH
+    # ========================================================================
+    
+    def match(
+        self,
+        source_ulid: str,
+        candidate_ulid: str,
+        *,
+        explain: Union[bool, ExplainLevel] = False,
+        threshold: float = 0.7,
+    ) -> MatchResult:
+        """
+        Compare two meaning objects for relevance.
+        
+        Used for recommendations: "Is this content relevant to this user?"
+        
+        Args:
+            source_ulid: User or memory ULID (the "who")
+            candidate_ulid: Candidate memory ULID (the "what")
+            explain: Include explanation (default: False)
+            threshold: Match threshold (default: 0.7)
+        
+        Returns:
+            MatchResult with score and explanation
+        
+        Example:
+            # Check if post is relevant to user
+            match = mi.match(user_ulid, post_ulid, explain=True)
+            
+            if match.match:
+                print(f"Relevant! {match.explain.human.summary}")
+        """
+        if isinstance(explain, bool):
+            explain_level = ExplainLevel.FULL if explain else ExplainLevel.NONE
+        else:
+            explain_level = explain
+        
+        payload = {
+            "source_ulid": source_ulid,
+            "candidate_ulid": candidate_ulid,
+            "explain": explain_level.value,
+            "threshold": threshold,
+        }
+        
+        if self.org_ulid:
+            payload["org_ulid"] = self.org_ulid
+        
+        response = self._request("POST", "/v1/match", json=payload)
+        return self._parse_match_result(response, source_ulid, candidate_ulid)
+    
+    # ========================================================================
+    # CORE OPERATION 4: EXPLAIN
+    # ========================================================================
+    
+    def explain(
+        self,
+        umo_id: str,
+        *,
+        level: ExplainLevel = ExplainLevel.FULL,
+    ) -> Explanation:
+        """
+        Get detailed explanation for any meaning object.
+        
+        Returns human-readable + machine-verifiable explanation.
+        
+        Args:
+            umo_id: ULID of the meaning object
+            level: Explanation level (default: full)
+        
+        Returns:
+            Explanation with human and audit components
+        
+        Example:
+            # Get explanation for a recommendation
+            explanation = mi.explain(umo_id)
+            print(explanation.human.summary)
+            print(explanation.audit.hash_chain)
+        """
+        payload = {
+            "umo_id": umo_id,
+            "level": level.value,
+        }
+        
+        if self.org_ulid:
+            payload["org_ulid"] = self.org_ulid
+        
+        response = self._request("GET", f"/v1/explain/{umo_id}", params=payload)
+        return self._parse_explanation(response)
+    
+    # ========================================================================
+    # CORE OPERATION 5: DELETE
+    # ========================================================================
+    
+    def delete(
+        self,
+        user_ulid: str,
+        *,
+        scope: Scope = Scope.ALL,
+        scope_id: Optional[str] = None,
+    ) -> DeleteResult:
+        """
+        Delete all meaning for a user/scope.
+        
+        GDPR compliance in one API call. Provenance proves deletion.
+        
+        Args:
+            user_ulid: User whose data to delete
+            scope: Scope to delete (default: ALL)
+            scope_id: Specific scope to delete (for partial deletion)
+        
+        Returns:
+            DeleteResult with count and audit proof
+        
+        Example:
+            # Full GDPR deletion
+            result = mi.delete(user_ulid="01ABC...")
+            print(f"Deleted {result.deleted_count} memories")
+            
+            # Delete only one client's data
+            result = mi.delete(
+                user_ulid="01ABC...",
+                scope=Scope.CLIENT,
+                scope_id=client_ulid
+            )
+        """
+        payload = {
+            "user_ulid": user_ulid,
+            "scope": scope.value,
+            "scope_id": scope_id,
+        }
+        
+        if self.org_ulid:
+            payload["org_ulid"] = self.org_ulid
+        
+        response = self._request("DELETE", "/v1/delete", json=payload)
+        
+        return DeleteResult(
+            deleted_count=response.get("deleted_count", 0),
+            user_ulid=user_ulid,
+            scope=scope,
+            scope_id=scope_id,
+            audit_proof=response.get("audit_proof", {}),
+        )
+    
+    # ========================================================================
+    # CORE OPERATION 6: VERIFY PROVENANCE
+    # ========================================================================
+    
+    def verify_provenance(
+        self,
+        content_hash: str,
+    ) -> VerifyResult:
+        """
+        Verify provenance of content.
+        
+        Check who created content first, verify hash chain integrity.
+        
+        Args:
+            content_hash: Semantic hash of content to verify
+        
+        Returns:
+            VerifyResult with authorship and timestamp proof
+        
+        Example:
+            # Verify authorship before using content
+            result = mi.verify_provenance(content_hash)
+            
+            if result.valid:
+                print(f"Original author: {result.original_author_ulid}")
+                print(f"First published: {result.first_published}")
+        """
+        response = self._request(
+            "GET", 
+            f"/v1/provenance/verify/{content_hash}"
+        )
+        
+        return VerifyResult(
+            valid=response.get("valid", False),
+            semantic_hash=response.get("semantic_hash", content_hash),
+            timestamp_anchor=datetime.fromisoformat(
+                response.get("timestamp_anchor", datetime.utcnow().isoformat())
+            ),
+            original_author_ulid=response.get("original_author_ulid"),
+            first_published=datetime.fromisoformat(response["first_published"]) 
+                if response.get("first_published") else None,
+            hash_chain_valid=response.get("hash_chain_valid", True),
+            audit_proof=response.get("audit_proof", {}),
+        )
+    
+    # ========================================================================
+    # INTERNAL METHODS
+    # ========================================================================
+    
+    def _request(
+        self,
+        method: str,
+        path: str,
+        **kwargs
+    ) -> Dict[str, Any]:
+        """Make authenticated request to MI API."""
+        try:
+            response = self._client.request(method, path, **kwargs)
+            
+            if response.status_code == 401:
+                raise AuthenticationError("Invalid or expired API key")
+            elif response.status_code == 429:
+                error = RateLimitError("Rate limit exceeded")
+                error.retry_after = int(response.headers.get("Retry-After", 60))
+                raise error
+            elif response.status_code == 403:
+                raise ScopeViolationError(
+                    response.json().get("detail", "Access denied")
+                )
+            
+            response.raise_for_status()
+            return response.json()
+            
+        except httpx.HTTPStatusError as e:
+            raise MIError(f"API error: {e}")
+        except httpx.RequestError as e:
+            raise MIError(f"Request failed: {e}")
+    
+    def _parse_meaning_object(self, data: Dict[str, Any]) -> MeaningObject:
+        """Parse API response into MeaningObject."""
+        return MeaningObject(
+            umo_id=data["umo_id"],
+            user_ulid=data["user_ulid"],
+            entities=[
+                Entity(
+                    text=e["text"],
+                    type=e["type"],
+                    confidence=e.get("confidence", 1.0),
+                    first_seen=datetime.fromisoformat(e["first_seen"]) if e.get("first_seen") else None,
+                    resolved_ulid=e.get("resolved_ulid"),
+                )
+                for e in data.get("entities", [])
+            ],
+            topics=[
+                Topic(
+                    name=t["name"],
+                    confidence=t.get("confidence", 1.0),
+                    parent=t.get("parent"),
+                )
+                for t in data.get("topics", [])
+            ],
+            svo_triples=[
+                SVOTriple(
+                    subject=s["subject"],
+                    verb=s["verb"],
+                    object=s["object"],
+                    confidence=s.get("confidence", 1.0),
+                )
+                for s in data.get("svo_triples", [])
+            ],
+            key_phrases=data.get("key_phrases", []),
+            summary=data.get("summary"),
+            embedding=data.get("embedding"),
+            embedding_model=data.get("embedding_model", ""),
+            sentiment_label=data.get("sentiment_label"),
+            sentiment_score=data.get("sentiment_score", 0.0),
+            timestamp=datetime.fromisoformat(data["timestamp"]) if data.get("timestamp") else None,
+            ingested_at=datetime.fromisoformat(data.get("ingested_at", datetime.utcnow().isoformat())),
+            recency_score=data.get("recency_score", 1.0),
+            quality_score=data.get("quality_score", 0.0),
+            validation_status=data.get("validation_status", "pending"),
+            provenance=Provenance(
+                semantic_hash=data["provenance"]["semantic_hash"],
+                timestamp_anchor=datetime.fromisoformat(data["provenance"]["timestamp_anchor"]),
+                hash_chain=data["provenance"]["hash_chain"],
+                lineage=data["provenance"].get("lineage", []),
+                model_version=data["provenance"].get("model_version", ""),
+            ) if data.get("provenance") else None,
+            pii=PIIDetection(
+                detected=data["pii"]["detected"],
+                types=data["pii"].get("types", []),
+                count=data["pii"].get("count", 0),
+                handling_applied=PIIHandling(data["pii"].get("handling_applied", "detect_only")),
+            ) if data.get("pii") else None,
+            scope=Scope(data.get("scope", "user")),
+            scope_id=data.get("scope_id"),
+        )
+    
+    def _parse_search_response(
+        self, 
+        data: Dict[str, Any],
+        query: str,
+        scope: Scope
+    ) -> SearchResponse:
+        """Parse API response into SearchResponse."""
+        results = []
+        for r in data.get("results", []):
+            umo = self._parse_meaning_object(r["umo"])
+            explain = self._parse_explanation(r["explain"]) if r.get("explain") else None
+            results.append(SearchResult(
+                umo=umo,
+                score=r["score"],
+                explain=explain,
+            ))
+        
+        return SearchResponse(
+            results=results,
+            query=query,
+            scope=scope,
+            total_count=data.get("total_count", len(results)),
+            audit_proof=data.get("audit_proof"),
+        )
+    
+    def _parse_match_result(
+        self,
+        data: Dict[str, Any],
+        source_ulid: str,
+        candidate_ulid: str
+    ) -> MatchResult:
+        """Parse API response into MatchResult."""
+        return MatchResult(
+            score=data["score"],
+            match=data["match"],
+            source_ulid=source_ulid,
+            candidate_ulid=candidate_ulid,
+            explain=self._parse_explanation(data["explain"]) if data.get("explain") else None,
+        )
+    
+    def _parse_explanation(self, data: Dict[str, Any]) -> Explanation:
+        """Parse explanation data."""
+        return Explanation(
+            human=ExplainHuman(
+                summary=data.get("human", {}).get("summary", ""),
+                key_reasons=data.get("human", {}).get("key_reasons", []),
+                what_changed=data.get("human", {}).get("what_changed"),
+            ),
+            audit=ExplainAudit(
+                semantic_score=data.get("audit", {}).get("semantic_score", 0.0),
+                temporal_score=data.get("audit", {}).get("temporal_score", 0.0),
+                entity_score=data.get("audit", {}).get("entity_score", 0.0),
+                graph_score=data.get("audit", {}).get("graph_score", 0.0),
+                topic_match=data.get("audit", {}).get("topic_match", []),
+                model_version=data.get("audit", {}).get("model_version", ""),
+                hash_chain=data.get("audit", {}).get("hash_chain", ""),
+                reproducible=data.get("audit", {}).get("reproducible", True),
+            ),
+        )