memoryintelligence 1.0.0__py3-none-any.whl

memoryintelligence/mi_types.py

@@ -0,0 +1,364 @@
+"""
+Memory Intelligence SDK - Types
+===============================
+
+Core types, enums, and response models for the SDK.
+These define the contract between developers and the MI API.
+
+Design Principles:
+    1. Meaning-Only by Default: Raw content discarded unless explicitly overridden
+    2. Provenance-First: Every operation produces verifiable audit trail
+    3. Scope Isolation: Cryptographic boundaries, not just policies
+    4. Explainability: Human + audit explanations on every operation
+    5. Edge-Ready: Same types work cloud and on-prem
+
+Author: Memory Intelligence Team
+Version: 1.0.0
+"""
+
+from dataclasses import dataclass, field
+from datetime import datetime
+from enum import Enum
+from typing import Any, Dict, List, Optional, Union
+
+
+# ============================================================================
+# ENUMS - SDK Controlled Vocabularies
+# ============================================================================
+
+class Scope(str, Enum):
+    """
+    Governance scope for memory isolation.
+    
+    Scopes are cryptographic boundaries—data in one scope is
+    technically inaccessible from another, not just policy-restricted.
+    
+    Usage:
+        mi.process(content, scope=Scope.CLIENT, client_ulid="01ABC...")
+        mi.search(query, scope=Scope.CLIENT, client_ulid="01ABC...")
+    """
+    USER = "user"           # Personal user memories
+    CLIENT = "client"       # Per-client isolation (consulting, legal)
+    PROJECT = "project"     # Per-project isolation
+    TEAM = "team"           # Team-shared memories
+    ORGANIZATION = "org"    # Organization-wide
+    ALL = "all"             # All accessible scopes (for deletion)
+
+
+class RetentionPolicy(str, Enum):
+    """
+    What to retain after processing.
+    
+    Privacy by design: meaning_only is the default, discards raw content.
+    
+    Usage:
+        mi.process(content, retention_policy=RetentionPolicy.MEANING_ONLY)
+    """
+    MEANING_ONLY = "meaning_only"   # Extract meaning, discard raw (DEFAULT)
+    FULL = "full"                    # Store raw + meaning (requires governance override)
+    SUMMARY_ONLY = "summary_only"    # Store summary + meaning, discard raw
+
+
+class PIIHandling(str, Enum):
+    """
+    How to handle detected PII.
+    
+    Usage:
+        mi.process(content, pii_handling=PIIHandling.EXTRACT_AND_REDACT)
+    """
+    DETECT_ONLY = "detect_only"             # Flag PII, don't modify
+    EXTRACT_AND_REDACT = "extract_and_redact"  # Extract to meaning, redact in output
+    HASH = "hash"                            # Replace PII with deterministic hash
+    REJECT = "reject"                        # Reject content containing PII
+
+
+class ProvenanceMode(str, Enum):
+    """
+    Provenance tracking level.
+    
+    Usage:
+        mi.process(content, provenance_mode=ProvenanceMode.AUTHORSHIP)
+    """
+    STANDARD = "standard"       # Hash chain, timestamp (DEFAULT)
+    AUTHORSHIP = "authorship"   # + semantic fingerprint, lineage tracking
+    AUDIT = "audit"             # + full transformation log
+
+
+class ExplainLevel(str, Enum):
+    """
+    Level of explanation to include in responses.
+    
+    Usage:
+        mi.search(query, explain=ExplainLevel.FULL)
+    """
+    NONE = "none"           # No explanation (fastest)
+    HUMAN = "human"         # Human-readable only
+    AUDIT = "audit"         # Machine-verifiable only
+    FULL = "full"           # Both human + audit (DEFAULT when explain=True)
+
+
+# ============================================================================
+# RESPONSE TYPES - What the SDK Returns
+# ============================================================================
+
+@dataclass
+class Entity:
+    """An extracted entity from content."""
+    text: str
+    type: str               # PERSON, ORG, LOCATION, CONCEPT, etc.
+    confidence: float       # 0.0 to 1.0
+    first_seen: Optional[datetime] = None
+    resolved_ulid: Optional[str] = None  # Canonical entity ID
+
+
+@dataclass
+class Topic:
+    """An extracted topic from content."""
+    name: str
+    confidence: float
+    parent: Optional[str] = None
+
+
+@dataclass
+class SVOTriple:
+    """Subject-Verb-Object extraction."""
+    subject: str
+    verb: str
+    object: str
+    confidence: float = 1.0
+
+
+@dataclass 
+class Provenance:
+    """Cryptographic provenance record."""
+    semantic_hash: str              # Hash of meaning content
+    timestamp_anchor: datetime      # When processed
+    hash_chain: str                 # Link to previous hash
+    lineage: List[str] = field(default_factory=list)  # Parent UMO IDs
+    model_version: str = ""         # Processing model version
+    
+    def verify(self) -> bool:
+        """Verify hash chain integrity."""
+        # Implementation would verify cryptographic chain
+        return True
+
+
+@dataclass
+class ExplainHuman:
+    """Human-readable explanation."""
+    summary: str
+    key_reasons: List[str] = field(default_factory=list)
+    what_changed: Optional[str] = None
+
+
+@dataclass
+class ExplainAudit:
+    """Machine-verifiable audit explanation."""
+    semantic_score: float
+    temporal_score: float
+    entity_score: float
+    graph_score: float
+    topic_match: List[str] = field(default_factory=list)
+    model_version: str = ""
+    hash_chain: str = ""
+    reproducible: bool = True
+
+
+@dataclass
+class Explanation:
+    """Combined explanation for auditable AI."""
+    human: ExplainHuman
+    audit: ExplainAudit
+
+
+@dataclass
+class PIIDetection:
+    """PII detection result."""
+    detected: bool
+    types: List[str] = field(default_factory=list)  # PERSON, EMAIL, PHONE, SSN, etc.
+    count: int = 0
+    handling_applied: PIIHandling = PIIHandling.DETECT_ONLY
+
+
+@dataclass
+class MeaningObject:
+    """
+    The core output of MI processing.
+    
+    This is what developers work with—structured meaning, not raw content.
+    """
+    umo_id: str                                 # ULID identifier
+    user_ulid: str                              # Owner
+    
+    # Meaning extraction
+    entities: List[Entity] = field(default_factory=list)
+    topics: List[Topic] = field(default_factory=list)
+    svo_triples: List[SVOTriple] = field(default_factory=list)
+    key_phrases: List[str] = field(default_factory=list)
+    summary: Optional[str] = None
+    
+    # Embeddings
+    embedding: Optional[List[float]] = None     # 384D or 768D vector
+    embedding_model: str = ""
+    
+    # Sentiment
+    sentiment_label: Optional[str] = None       # positive, negative, neutral
+    sentiment_score: float = 0.0
+    
+    # Temporal
+    timestamp: Optional[datetime] = None
+    ingested_at: datetime = field(default_factory=lambda: datetime.utcnow())
+    recency_score: float = 1.0
+    
+    # Quality
+    quality_score: float = 0.0                  # 0.0 to 1.0
+    validation_status: str = "pending"
+    
+    # Provenance
+    provenance: Optional[Provenance] = None
+    
+    # PII
+    pii: Optional[PIIDetection] = None
+    
+    # Scope
+    scope: Scope = Scope.USER
+    scope_id: Optional[str] = None              # client_ulid, project_ulid, etc.
+
+
+@dataclass
+class SearchResult:
+    """A single search result with explanation."""
+    umo: MeaningObject
+    score: float
+    explain: Optional[Explanation] = None
+
+
+@dataclass
+class SearchResponse:
+    """Response from mi.search()."""
+    results: List[SearchResult]
+    query: str
+    scope: Scope
+    total_count: int
+    
+    # Audit
+    audit_proof: Optional[Dict[str, Any]] = None
+
+
+@dataclass
+class MatchResult:
+    """Response from mi.match()."""
+    score: float                            # 0.0 to 1.0
+    match: bool                             # Above threshold?
+    source_ulid: str
+    candidate_ulid: str
+    explain: Optional[Explanation] = None
+
+
+@dataclass
+class DeleteResult:
+    """Response from mi.delete()."""
+    deleted_count: int
+    user_ulid: str
+    scope: Scope
+    scope_id: Optional[str] = None
+    audit_proof: Dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass
+class VerifyResult:
+    """Response from mi.verify_provenance()."""
+    valid: bool
+    semantic_hash: str
+    timestamp_anchor: datetime
+    original_author_ulid: Optional[str] = None
+    first_published: Optional[datetime] = None
+    hash_chain_valid: bool = True
+    audit_proof: Dict[str, Any] = field(default_factory=dict)
+
+
+# ============================================================================
+# CONFIGURATION TYPES
+# ============================================================================
+
+@dataclass
+class ProcessConfig:
+    """Configuration for mi.process()."""
+    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
+    
+    # Edge processing
+    edge_mode: bool = False
+    hipaa_mode: bool = False
+    
+    # Optional metadata
+    source: str = "api"
+    metadata: Dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass
+class SearchConfig:
+    """Configuration for mi.search()."""
+    scope: Scope = Scope.USER
+    scope_id: Optional[str] = None
+    explain: Union[bool, ExplainLevel] = False
+    limit: int = 10
+    offset: int = 0
+    
+    # Filtering
+    date_from: Optional[datetime] = None
+    date_to: Optional[datetime] = None
+    topics: Optional[List[str]] = None
+    entities: Optional[List[str]] = None
+    
+    # Budget
+    budget_tokens: Optional[int] = None  # Max tokens in response
+
+
+@dataclass
+class MatchConfig:
+    """Configuration for mi.match()."""
+    explain: Union[bool, ExplainLevel] = False
+    threshold: float = 0.7
+
+
+# ============================================================================
+# ERROR TYPES
+# ============================================================================
+
+class MIError(Exception):
+    """Base exception for Memory Intelligence SDK."""
+    pass
+
+
+class AuthenticationError(MIError):
+    """Invalid or expired API key."""
+    pass
+
+
+class RateLimitError(MIError):
+    """Rate limit exceeded."""
+    retry_after: int = 60
+
+
+class ScopeViolationError(MIError):
+    """Attempted cross-scope access."""
+    pass
+
+
+class PIIViolationError(MIError):
+    """Content contains PII and policy is REJECT."""
+    detected_types: List[str] = field(default_factory=list)
+
+
+class GovernanceError(MIError):
+    """Operation violates governance policy."""
+    pass
+
+
+class ProvenenaceError(MIError):
+    """Provenance verification failed."""
+    pass