memoryintelligence 0.1.0__py3-none-any.whl

memoryintelligence/__init__.py

@@ -0,0 +1,71 @@
+"""memoryintelligence: the official Python client for Memory Intelligence.
+
+Ask once. Never explain again.
+
+    from memoryintelligence import MemoryIntelligence
+
+    mi = MemoryIntelligence.from_env()                 # reads MI_API_KEY
+    note = mi.capture("Deploy is Friday at 3pm.", source="standup")
+
+    for hit in mi.ask("when is the deploy?"):
+        print(hit.score, hit.summary)
+
+    assert mi.verify(note.id).valid                     # every memory has a receipt
+
+Eight verbs on the canonical API: capture, ask, get, list, verify, explain,
+forget, batch, upload. Results come back as small typed objects, not envelopes.
+"""
+from ._version import __version__
+
+from ._simple import (
+    MemoryIntelligence,
+    MI,
+    Memory,
+    Match,
+    Proof,
+    Explanation,
+    Receipt,
+)
+from ._errors import (
+    MIError,
+    ConfigurationError,
+    AuthenticationError,
+    RateLimitError,
+    NotFoundError,
+    ValidationError,
+    ServerError,
+    ConnectionError,
+    TimeoutError,
+    ConflictError,
+    PaymentRequiredError,
+    PermissionError,
+)
+
+__author__ = "Memory Intelligence"
+__license__ = "MIT"
+
+__all__ = [
+    "__version__",
+    # Client
+    "MemoryIntelligence",
+    "MI",
+    # Result types
+    "Memory",
+    "Match",
+    "Proof",
+    "Explanation",
+    "Receipt",
+    # Exceptions
+    "MIError",
+    "ConfigurationError",
+    "AuthenticationError",
+    "RateLimitError",
+    "NotFoundError",
+    "ValidationError",
+    "ServerError",
+    "ConnectionError",
+    "TimeoutError",
+    "ConflictError",
+    "PaymentRequiredError",
+    "PermissionError",
+]

memoryintelligence/_auth.py

@@ -0,0 +1,316 @@
+"""Memory Intelligence SDK - Authentication.
+
+API key resolution and validation.
+"""
+
+from __future__ import annotations
+
+import os
+import re
+from urllib.parse import urlparse
+
+from ._errors import ConfigurationError
+
+# Try to load python-dotenv if available (optional dependency)
+_dotenv_loaded = False
+try:
+    from dotenv import load_dotenv
+    # Load .env file from current directory (won't override existing env vars)
+    load_dotenv(override=False)
+    _dotenv_loaded = True
+except ImportError:
+    pass  # python-dotenv not installed, skip .env loading
+
+# Production API URL
+DEFAULT_API_URL = "https://api.memoryintelligence.io"
+
+# Valid API key prefixes
+LIVE_KEY_PREFIX  = "mi_sk_live_"
+TEST_KEY_PREFIX  = "mi_sk_test_"
+BETA_KEY_PREFIX  = "mi_sk_beta_"  # beta programme keys
+VALID_KEY_PREFIXES = (LIVE_KEY_PREFIX, TEST_KEY_PREFIX, BETA_KEY_PREFIX)
+
+# Minimum key length (prefix + some randomness)
+MIN_KEY_LENGTH = 32
+
+# URL patterns that indicate localhost/local development
+LOCALHOST_PATTERNS = [
+    r"localhost",
+    r"127\.\d+\.\d+\.\d+",
+    r"0\.0\.0\.0",
+    r"::1",
+    r"\.local$",
+    r"\.internal$",
+    r":\d+/(?!/)"  # Any port specifier (rough heuristic)
+]
+
+
+def resolve_api_key(explicit_key: str | None) -> str:
+    """
+    Resolve API key from explicit argument or environment.
+
+    Priority:
+        1. Explicit key passed to constructor
+        2. MI_API_KEY environment variable
+        3. ConfigurationError (key is required)
+
+    Args:
+        explicit_key: API key passed directly to constructor
+
+    Returns:
+        Resolved API key string
+
+    Raises:
+        ConfigurationError: If no API key is found
+
+    Example:
+        >>> resolve_api_key("mi_sk_test_abc123...")
+        'mi_sk_test_abc123...'
+        >>> resolve_api_key(None)  # With MI_API_KEY set
+        'mi_sk_live_xyz789...'
+    """
+    if explicit_key is not None:
+        key = explicit_key.strip()
+        if key:
+            return key
+
+    env_key = os.environ.get("MI_API_KEY")
+    if env_key:
+        key = env_key.strip()
+        if key:
+            return key
+
+    raise ConfigurationError(
+        "API key is required. Pass it directly, set MI_API_KEY environment variable, "
+        "or add MI_API_KEY=your_key to a .env file (requires: pip install memoryintelligence[dotenv]). "
+        "Get your API key at https://memoryintelligence.io/portal"
+    )
+
+
+def validate_api_key(api_key: str, base_url: str) -> None:
+    """
+    Validate API key format and environment compatibility.
+    
+    Combines format and environment checks into one call.
+    
+    Args:
+        api_key: API key to validate
+        base_url: Base URL being used (to check live key + localhost)
+        
+    Raises:
+        ConfigurationError: If key format or environment is invalid
+    """
+    validate_key_format(api_key)
+    validate_key_environment(api_key, base_url)
+
+
+def resolve_base_url(explicit_url: str | None) -> str:
+    """
+    Resolve base URL from explicit argument or environment.
+
+    Priority:
+        1. Explicit URL passed to constructor
+        2. MI_BASE_URL environment variable
+        3. Production default (https://api.memoryintelligence.io)
+
+    Args:
+        explicit_url: Base URL passed directly to constructor
+
+    Returns:
+        Resolved base URL string (normalized, no trailing slash)
+
+    Raises:
+        ConfigurationError: If URL is malformed
+
+    Example:
+        >>> resolve_base_url("https://custom.example.com")
+        'https://custom.example.com'
+        >>> resolve_base_url("https://custom.example.com/")  # Trailing slash removed
+        'https://custom.example.com'
+    """
+    url = None
+
+    if explicit_url is not None:
+        url = explicit_url.strip()
+    else:
+        env_url = os.environ.get("MI_BASE_URL")
+        if env_url:
+            url = env_url.strip()
+
+    if not url:
+        return DEFAULT_API_URL
+
+    # Basic URL validation
+    if not url.startswith(("http://", "https://")):
+        raise ConfigurationError(
+            f"Invalid base_url: must start with http:// or https://. Got: {url[:50]}..."
+        )
+
+    # Validate URL structure
+    try:
+        parsed = urlparse(url)
+        if not parsed.netloc:
+            raise ConfigurationError(f"Invalid base_url: missing host. Got: {url}")
+    except Exception as e:
+        raise ConfigurationError(f"Invalid base_url: {e}") from e
+
+    # Remove trailing slashes for consistency
+    return url.rstrip("/")
+
+
+def validate_key_format(api_key: str) -> None:
+    """
+    Validate API key format.
+
+    Valid keys must:
+        - Start with 'mi_sk_live_' or 'mi_sk_test_'
+        - Be at least 32 characters long
+        - Not contain whitespace
+
+    Args:
+        api_key: API key to validate
+
+    Raises:
+        ConfigurationError: If key format is invalid
+
+    Example:
+        >>> validate_key_format("mi_sk_test_abc123xyz...")
+        # passes silently
+        >>> validate_key_format("invalid_key")
+        ConfigurationError: Invalid API key format...
+    """
+    if not api_key:
+        raise ConfigurationError("API key cannot be empty.")
+
+    # Check for whitespace
+    if api_key != api_key.strip():
+        raise ConfigurationError(
+            "API key contains leading or trailing whitespace. Please check your key."
+        )
+
+    # Check prefix
+    if not any(api_key.startswith(prefix) for prefix in VALID_KEY_PREFIXES):
+        # Show what we received (safely truncated)
+        displayed_key = api_key[:20] + "..." if len(api_key) > 20 else api_key
+        raise ConfigurationError(
+            f"Invalid API key format. Key must start with 'mi_sk_live_', 'mi_sk_test_', or 'mi_sk_beta_'. "
+            f"Got: '{displayed_key}'. Get your API key at https://memoryintelligence.io/dashboard"
+        )
+
+    # Check minimum length
+    if len(api_key) < MIN_KEY_LENGTH:
+        raise ConfigurationError(
+            f"API key too short. Expected at least {MIN_KEY_LENGTH} characters, "
+            f"got {len(api_key)}. Please provide a complete key."
+        )
+
+
+def validate_key_environment(api_key: str, base_url: str) -> None:
+    """
+    Validate that live keys are not used with localhost/development URLs.
+
+    This is a safety measure to prevent accidentally using production keys
+    in development environments.
+
+    Args:
+        api_key: The API key being used
+        base_url: The base URL being configured
+
+    Raises:
+        ConfigurationError: If live key is used with localhost URL
+
+    Example:
+        >>> validate_key_environment(
+        ...     "mi_sk_live_abc123...",
+        ...     "http://localhost:8000"
+        ... )
+        ConfigurationError: Live key detected with local base_url...
+    """
+    is_live_key = api_key.startswith(LIVE_KEY_PREFIX)
+
+    # Check for local/development URLs
+    is_localhost = _is_localhost_url(base_url)
+
+    if is_live_key and is_localhost:
+        raise ConfigurationError(
+            "Live key detected with local base_url. "
+            "Use a test key for local development. "
+            "Test keys start with 'mi_sk_test_'. "
+            "Get test keys at https://memoryintelligence.io/dashboard"
+        )
+
+
+def _is_localhost_url(url: str) -> bool:
+    """
+    Check if URL points to localhost/development environment.
+
+    Args:
+        url: URL string to check
+
+    Returns:
+        True if URL appears to be localhost/local development
+    """
+    url_lower = url.lower()
+
+    for pattern in LOCALHOST_PATTERNS:
+        if re.search(pattern, url_lower):
+            return True
+
+    return False
+
+
+def is_live_key(api_key: str) -> bool:
+    """
+    Check if API key is a live/production key.
+
+    Args:
+        api_key: API key to check
+
+    Returns:
+        True if key starts with 'mi_sk_live_'
+
+    Example:
+        >>> is_live_key("mi_sk_live_abc123")
+        True
+        >>> is_live_key("mi_sk_test_xyz789")
+        False
+    """
+    return api_key.startswith(LIVE_KEY_PREFIX)
+
+
+def is_test_key(api_key: str) -> bool:
+    """
+    Check if API key is a test/development key.
+
+    Args:
+        api_key: API key to check
+
+    Returns:
+        True if key starts with 'mi_sk_test_'
+
+    Example:
+        >>> is_test_key("mi_sk_test_xyz789")
+        True
+        >>> is_test_key("mi_sk_live_abc123")
+        False
+    """
+    return api_key.startswith(TEST_KEY_PREFIX)
+
+
+def mask_key(api_key: str) -> str:
+    """
+    Mask API key for safe logging/display.
+
+    Args:
+        api_key: API key to mask
+
+    Returns:
+        Masked key showing only first 12 and last 4 characters
+
+    Example:
+        >>> mask_key("mi_sk_test_abc123xyz789")
+        'mi_sk_test_abc...yz89'
+    """
+    if len(api_key) <= 16:
+        return "***"
+    return f"{api_key[:12]}...{api_key[-4:]}"

memoryintelligence/_errors.py

@@ -0,0 +1,232 @@
+"""Memory Intelligence SDK - Error types.
+
+Complete error hierarchy for programmatic exception handling.
+Every error has a `code` string attribute that matches the API error envelope.
+"""
+
+from dataclasses import dataclass, field
+
+
+class MIError(Exception):
+    """Base. All SDK errors inherit from this."""
+    code: str = "mi_error"
+
+    def __init__(self, message: str = "Memory Intelligence error"):
+        super().__init__(message)
+
+
+class ConfigurationError(MIError):
+    """Invalid SDK configuration (wrong key format, live key + localhost, etc.)"""
+    code = "configuration_error"
+
+    def __init__(self, message: str = "Invalid configuration"):
+        super().__init__(message)
+
+
+class LicenseError(MIError):
+    """License invalid, expired beyond grace period, or revoked."""
+    code = "license_error"
+    days_expired: int = 0  # 0 if not expired, N if in warning period
+    renew_url: str = "https://memoryintelligence.io/billing"
+
+    def __init__(
+        self,
+        message: str = "License error",
+        days_expired: int = 0,
+        renew_url: str = "https://memoryintelligence.io/billing",
+    ):
+        super().__init__(message)
+        self.days_expired = days_expired
+        self.renew_url = renew_url
+
+
+class AuthenticationError(MIError):
+    """API key rejected by server."""
+    code = "authentication_error"
+
+    def __init__(self, message: str = "Authentication failed"):
+        super().__init__(message)
+
+
+class RateLimitError(MIError):
+    """Rate limit exceeded."""
+    code = "rate_limit"
+    retry_after: int = 60  # seconds, from Retry-After header
+
+    def __init__(
+        self,
+        message: str = "Rate limit exceeded",
+        retry_after: int = 60,
+    ):
+        super().__init__(message)
+        self.retry_after = retry_after
+
+
+class ScopeViolationError(MIError):
+    """Cross-scope access attempt or missing scope_id."""
+    code = "scope_violation"
+
+    def __init__(self, message: str = "Scope violation"):
+        super().__init__(message)
+
+
+class PIIViolationError(MIError):
+    """Content rejected due to PII policy."""
+    code = "pii_violation"
+    detected_types: list = field(default_factory=list)
+
+    def __init__(
+        self,
+        message: str = "PII violation detected",
+        detected_types: list | None = None,
+    ):
+        super().__init__(message)
+        self.detected_types = detected_types or []
+
+
+class GovernanceError(MIError):
+    """Operation violates governance policy."""
+    code = "governance_error"
+
+    def __init__(self, message: str = "Governance policy violation"):
+        super().__init__(message)
+
+
+class ConflictError(MIError):
+    """Resource conflict (e.g., duplicate UMO)."""
+    code = "conflict"
+
+    def __init__(self, message: str = "Resource conflict"):
+        super().__init__(message)
+
+
+class PaymentRequiredError(MIError):
+    """Payment required - license upgrade needed."""
+    code = "payment_required"
+
+    def __init__(self, message: str = "License upgrade required"):
+        super().__init__(message)
+
+
+class EncryptionError(MIError):
+    """Encryption/decryption failure."""
+    code = "encryption_error"
+
+    def __init__(self, message: str = "Encryption error"):
+        super().__init__(message)
+
+
+class PermissionError(MIError):
+    """Permission denied."""
+    code = "permission_error"
+
+    def __init__(self, message: str = "Permission denied"):
+        super().__init__(message)
+
+
+class ProvenanceError(MIError):
+    """Provenance verification failed."""
+    code = "provenance_error"
+
+    def __init__(self, message: str = "Provenance verification failed"):
+        super().__init__(message)
+
+
+class ValidationError(MIError):
+    """Request payload failed server-side validation."""
+    code = "validation_error"
+    field: str = ""  # which field failed
+
+    def __init__(
+        self,
+        message: str = "Validation error",
+        field: str = "",
+    ):
+        super().__init__(message)
+        self.field = field
+
+
+class PaymentRequiredError(MIError):
+    """Payment required - license upgrade needed."""
+    code = "payment_required"
+
+    def __init__(self, message: str = "License upgrade required"):
+        super().__init__(message)
+
+
+class PermissionError(MIError):
+    """Permission denied for this operation."""
+    code = "permission_error"
+
+    def __init__(self, message: str = "Permission denied"):
+        super().__init__(message)
+
+
+class NotFoundError(MIError):
+    """Resource not found."""
+    code = "not_found"
+
+    def __init__(self, message: str = "Resource not found"):
+        super().__init__(message)
+
+
+class ConflictError(MIError):
+    """Resource conflict (e.g., duplicate UMO)."""
+    code = "conflict"
+
+    def __init__(self, message: str = "Resource conflict"):
+        super().__init__(message)
+
+
+class ServerError(MIError):
+    """Unrecoverable server-side error."""
+    code = "server_error"
+    request_id: str = ""  # from X-MI-Request-ID response header
+
+    def __init__(
+        self,
+        message: str = "Server error",
+        request_id: str = "",
+    ):
+        super().__init__(message)
+        self.request_id = request_id
+
+
+class ConnectionError(MIError):
+    """Could not reach the API."""
+    code = "connection_error"
+
+    def __init__(self, message: str = "Could not connect to API"):
+        super().__init__(message)
+
+
+class TimeoutError(MIError):
+    """Request timed out."""
+    code = "timeout"
+
+    def __init__(self, message: str = "Request timed out"):
+        super().__init__(message)
+
+
+# HTTP status code to exception mapping
+# Used by _http.py to raise appropriate exceptions
+HTTP_STATUS_EXCEPTIONS: dict[int, type[MIError]] = {
+    400: ValidationError,
+    401: AuthenticationError,
+    402: PaymentRequiredError,
+    403: PermissionError,
+    404: NotFoundError,
+    409: ConflictError,
+    422: ValidationError,
+    429: RateLimitError,
+    451: PIIViolationError,
+    500: ServerError,
+    502: ServerError,
+    503: ServerError,
+    504: ServerError,
+}
+
+
+def get_exception_for_status(status_code: int) -> type[MIError]:
+    """Get the appropriate exception class for an HTTP status code."""
+    return HTTP_STATUS_EXCEPTIONS.get(status_code, ServerError)