memoryintelligence 1.0.0__py3-none-any.whl

memoryintelligence/__init__.py

@@ -0,0 +1,153 @@
+"""
+Memory Intelligence SDK
+=======================
+
+The official Python SDK for Memory Intelligence.
+
+Quick Start:
+    from memoryintelligence import MemoryClient
+    
+    mi = MemoryClient(api_key="mi_sk_...")
+    
+    # Process content → meaning (raw content discarded)
+    umo = mi.process("Important meeting notes", user_ulid="01ABC...")
+    
+    # Search with explanation
+    results = mi.search("What did we discuss?", user_ulid="01ABC...", explain=True)
+    
+    # Match for recommendations
+    match = mi.match(user_ulid, candidate_ulid, explain=True)
+    
+    # Delete for GDPR
+    mi.delete(user_ulid="01ABC...")
+
+For regulated industries (HIPAA, legal, finance):
+    from memoryintelligence import EdgeClient
+    
+    mi = EdgeClient(
+        endpoint="https://mi.internal.yourcompany.com",
+        api_key="mi_sk_...",
+        hipaa_mode=True
+    )
+    
+    # Process locally—data never leaves your infrastructure
+    umo = mi.process(clinical_note, patient_ulid="01ABC...")
+
+Core Operations:
+    - process()  → Convert raw content to meaning
+    - search()   → Find relevant memories
+    - match()    → Compare memories for relevance
+    - explain()  → Get explanation for any UMO
+    - delete()   → Remove all user data
+    - verify_provenance() → Verify authorship/timestamp
+
+Version: 1.0.0
+Author: Memory Intelligence Team
+"""
+
+__version__ = "1.0.0"
+__author__ = "Memory Intelligence Team"
+
+# ============================================================================
+# Public API
+# ============================================================================
+
+# Main clients
+from .memory_client import MemoryClient
+from .edge_client import EdgeClient, connect_edge
+
+# Enums
+from .mi_types import (
+    Scope,
+    RetentionPolicy,
+    PIIHandling,
+    ProvenanceMode,
+    ExplainLevel,
+)
+
+# Response types
+from .mi_types import (
+    MeaningObject,
+    SearchResponse,
+    SearchResult,
+    MatchResult,
+    DeleteResult,
+    VerifyResult,
+    Explanation,
+    ExplainHuman,
+    ExplainAudit,
+    Entity,
+    Topic,
+    SVOTriple,
+    Provenance,
+    PIIDetection,
+)
+
+# Config types
+from .mi_types import (
+    ProcessConfig,
+    SearchConfig,
+    MatchConfig,
+)
+
+# Exceptions
+from .mi_types import (
+    MIError,
+    AuthenticationError,
+    RateLimitError,
+    ScopeViolationError,
+    PIIViolationError,
+    GovernanceError,
+    ProvenenaceError,
+)
+
+# ============================================================================
+# Convenience exports
+# ============================================================================
+
+__all__ = [
+    # Version
+    "__version__",
+    
+    # Clients
+    "MemoryClient",
+    "EdgeClient",
+    "connect_edge",
+    
+    # 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",
+    
+    # Exceptions
+    "MIError",
+    "AuthenticationError",
+    "RateLimitError",
+    "ScopeViolationError",
+    "PIIViolationError",
+    "GovernanceError",
+    "ProvenenaceError",
+]

memoryintelligence/edge_client.py

@@ -0,0 +1,384 @@
+"""
+Memory Intelligence SDK - Edge Client
+=====================================
+
+On-premises / VPC deployment for regulated industries.
+Data never leaves your infrastructure—only metering crosses the network.
+
+Problem Solved: Proprietary Data Paralysis
+    - HIPAA: Clinical notes processed locally
+    - Legal: Attorney-client privileged documents
+    - Finance: Trading data, internal communications
+    - Competitive: Trade secrets, internal strategy
+
+Architecture:
+    ┌─────────────────────────────────────────────────────────┐
+    │                  YOUR INFRASTRUCTURE                     │
+    │                                                          │
+    │  ┌──────────────┐         ┌──────────────────────────┐  │
+    │  │  Your App    │         │  MI Edge Container       │  │
+    │  │              │ ──────> │  - 12-phase pipeline     │  │
+    │  │  EdgeClient  │         │  - NER engine            │  │
+    │  │              │ <────── │  - Embedding engine      │  │
+    │  └──────────────┘         │  - Provenance ledger     │  │
+    │                           └──────────────────────────┘  │
+    │                                      │                   │
+    └──────────────────────────────────────│───────────────────┘
+                                           │ Metering only
+                                           ▼
+                              ┌───────────────────────┐
+                              │  MI Cloud (optional)  │
+                              │  - Usage tracking     │
+                              │  - License validation │
+                              └───────────────────────┘
+
+Usage:
+    from memoryintelligence import EdgeClient
+    
+    # Connect to your on-prem MI container
+    mi = EdgeClient(
+        endpoint="https://mi.internal.yourcompany.com",
+        api_key="mi_sk_...",  # For metering only
+        hipaa_mode=True
+    )
+    
+    # Process locally—data never leaves
+    umo = mi.process(clinical_note, patient_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 .mi_types import (
+    Scope,
+    RetentionPolicy,
+    PIIHandling,
+    ProvenanceMode,
+    ExplainLevel,
+    MeaningObject,
+    SearchResponse,
+    MatchResult,
+    DeleteResult,
+    Explanation,
+    MIError,
+    AuthenticationError,
+)
+from .memory_client import MemoryClient
+
+logger = logging.getLogger(__name__)
+
+
+class EdgeClient(MemoryClient):
+    """
+    Edge deployment client for regulated industries.
+    
+    All processing happens in your infrastructure.
+    Only metering/licensing data crosses the network (optional).
+    
+    Key Features:
+        - HIPAA mode: Enhanced PHI detection, audit logging
+        - Air-gapped mode: No network calls at all
+        - Federated aggregation: Query across deployments without sharing data
+    
+    Args:
+        endpoint: Your internal MI container endpoint
+        api_key: MI API key (for metering, can be disabled)
+        hipaa_mode: Enable HIPAA-compliant processing
+        air_gapped: Disable all external network calls
+        metering_enabled: Whether to report usage to MI cloud
+    
+    Example:
+        # Standard edge deployment
+        mi = EdgeClient(
+            endpoint="https://mi.internal.yourcompany.com",
+            api_key="mi_sk_...",
+            hipaa_mode=True
+        )
+        
+        # Air-gapped (no external calls)
+        mi = EdgeClient(
+            endpoint="https://mi.internal.yourcompany.com",
+            air_gapped=True
+        )
+    """
+    
+    def __init__(
+        self,
+        endpoint: str,
+        api_key: Optional[str] = None,
+        hipaa_mode: bool = False,
+        air_gapped: bool = False,
+        metering_enabled: bool = True,
+        timeout: float = 30.0,
+    ):
+        self.endpoint = endpoint.rstrip("/")
+        self.hipaa_mode = hipaa_mode
+        self.air_gapped = air_gapped
+        self.metering_enabled = metering_enabled and not air_gapped
+        
+        # For air-gapped mode, API key is optional
+        if not air_gapped and not api_key:
+            raise AuthenticationError(
+                "API key required for metered edge deployment. "
+                "Use air_gapped=True for offline mode."
+            )
+        
+        self.api_key = api_key
+        self.timeout = timeout
+        
+        # Edge client connects to internal endpoint
+        self._client = httpx.Client(
+            base_url=self.endpoint,
+            timeout=self.timeout,
+            headers={
+                "X-MI-Edge-Mode": "true",
+                "X-MI-HIPAA-Mode": str(hipaa_mode).lower(),
+                "Content-Type": "application/json",
+            }
+        )
+        
+        # Separate client for metering (if enabled)
+        if self.metering_enabled and api_key:
+            self._metering_client = httpx.Client(
+                base_url="https://api.memoryintelligence.dev",
+                timeout=5.0,  # Fast timeout for metering
+                headers={
+                    "Authorization": f"Bearer {api_key}",
+                    "X-MI-Edge-Metering": "true",
+                }
+            )
+        else:
+            self._metering_client = None
+        
+        logger.info(
+            f"EdgeClient initialized (endpoint={endpoint}, "
+            f"hipaa={hipaa_mode}, air_gapped={air_gapped})"
+        )
+    
+    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 = "edge",
+        metadata: Optional[Dict[str, Any]] = None,
+    ) -> MeaningObject:
+        """
+        Process content locally in your infrastructure.
+        
+        In HIPAA mode:
+            - Enhanced PHI detection (ICD-10, medical terms)
+            - All PHI hashed, never stored
+            - Audit log proves data never left
+        
+        Args:
+            content: Raw content (processed locally, never transmitted)
+            user_ulid: Owner ULID (can be patient ULID in HIPAA mode)
+            retention_policy: What to retain (meaning_only recommended)
+            pii_handling: PHI/PII handling (hash recommended for HIPAA)
+            ... (same as MemoryClient.process)
+        
+        Returns:
+            MeaningObject with entities, embedding, provenance
+            
+        Note:
+            In HIPAA mode, the response includes phi_status showing
+            what PHI was detected and how it was handled.
+        """
+        # Override PII handling in HIPAA mode
+        if self.hipaa_mode:
+            pii_handling = PIIHandling.HASH
+            provenance_mode = ProvenanceMode.AUDIT
+        
+        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 {},
+            "hipaa_mode": self.hipaa_mode,
+        }
+        
+        # Process locally
+        response = self._request("POST", "/v1/process", json=payload)
+        result = self._parse_meaning_object(response)
+        
+        # Report usage (async, non-blocking, fails silently)
+        if self.metering_enabled:
+            self._report_usage("process", user_ulid)
+        
+        return result
+    
+    def aggregate(
+        self,
+        query: str,
+        scope: Scope = Scope.ORGANIZATION,
+        return_format: str = "statistics_only",
+        minimum_cohort_size: int = 50,
+    ) -> Dict[str, Any]:
+        """
+        Aggregate insights across records without exposing individual data.
+        
+        Federated querying with differential privacy for regulated data.
+        
+        Args:
+            query: Natural language query for aggregation
+            scope: Aggregation scope (typically ORGANIZATION)
+            return_format: "statistics_only" (no individual records)
+            minimum_cohort_size: K-anonymity threshold
+        
+        Returns:
+            Aggregated statistics with privacy guarantees
+        
+        Example:
+            insights = mi.aggregate(
+                "Patients with chest pain who responded to nitroglycerin",
+                scope=Scope.ORGANIZATION,
+                minimum_cohort_size=50
+            )
+            
+            # Returns:
+            # {
+            #     "count": 1247,
+            #     "avg_response_time": "4.2 minutes",
+            #     "audit_proof": {"no_phi_returned": True, ...}
+            # }
+        """
+        payload = {
+            "query": query,
+            "scope": scope.value,
+            "return_format": return_format,
+            "minimum_cohort_size": minimum_cohort_size,
+            "hipaa_mode": self.hipaa_mode,
+        }
+        
+        response = self._request("POST", "/v1/aggregate", json=payload)
+        
+        # Report usage
+        if self.metering_enabled:
+            self._report_usage("aggregate", "aggregate")
+        
+        return response
+    
+    def verify_phi_handling(self, umo_id: str) -> Dict[str, Any]:
+        """
+        Verify how PHI was handled for a specific UMO.
+        
+        Returns audit proof showing:
+        - What PHI types were detected
+        - How each was handled (hashed, redacted)
+        - Proof that raw PHI was never stored/transmitted
+        
+        Args:
+            umo_id: ULID of the processed memory
+        
+        Returns:
+            PHI handling audit proof
+        
+        Example:
+            proof = mi.verify_phi_handling(umo_id)
+            
+            # Returns:
+            # {
+            #     "phi_detected": ["PERSON", "DATE", "MRN"],
+            #     "handling_method": "hash",
+            #     "raw_phi_stored": False,
+            #     "raw_phi_transmitted": False,
+            #     "audit_hash": "sha256:...",
+            #     "timestamp": "2025-12-26T..."
+            # }
+        """
+        response = self._request("GET", f"/v1/phi/verify/{umo_id}")
+        return response
+    
+    def export_audit_log(
+        self,
+        start_date: datetime,
+        end_date: datetime,
+        format: str = "json",
+    ) -> Dict[str, Any]:
+        """
+        Export audit log for compliance review.
+        
+        Returns complete processing audit trail for the date range.
+        
+        Args:
+            start_date: Audit period start
+            end_date: Audit period end
+            format: Export format ("json", "csv")
+        
+        Returns:
+            Audit log with all processing events
+        """
+        payload = {
+            "start_date": start_date.isoformat(),
+            "end_date": end_date.isoformat(),
+            "format": format,
+        }
+        
+        response = self._request("POST", "/v1/audit/export", json=payload)
+        return response
+    
+    def _report_usage(self, operation: str, user_ulid: str):
+        """Report usage to MI cloud for metering (non-blocking)."""
+        if not self._metering_client:
+            return
+        
+        try:
+            self._metering_client.post(
+                "/v1/metering/report",
+                json={
+                    "operation": operation,
+                    "user_ulid": user_ulid,
+                    "timestamp": datetime.utcnow().isoformat(),
+                    "hipaa_mode": self.hipaa_mode,
+                }
+            )
+        except Exception as e:
+            # Metering failures should never block processing
+            logger.debug(f"Metering report failed (non-blocking): {e}")
+    
+    def close(self):
+        """Close HTTP clients."""
+        self._client.close()
+        if self._metering_client:
+            self._metering_client.close()
+
+
+# ============================================================================
+# Convenience function for quick edge setup
+# ============================================================================
+
+def connect_edge(
+    endpoint: str,
+    api_key: Optional[str] = None,
+    hipaa_mode: bool = False,
+) -> EdgeClient:
+    """
+    Quick helper to connect to an edge deployment.
+    
+    Example:
+        from memoryintelligence import connect_edge
+        
+        mi = connect_edge("https://mi.internal.hospital.com", hipaa_mode=True)
+        umo = mi.process(clinical_note, patient_ulid="01ABC...")
+    """
+    return EdgeClient(
+        endpoint=endpoint,
+        api_key=api_key,
+        hipaa_mode=hipaa_mode,
+    )