alma-memory 0.4.0__py3-none-any.whl → 0.5.1__py3-none-any.whl

alma/events/webhook.py

@@ -0,0 +1,425 @@
+"""
+ALMA Webhook Delivery.
+
+Provides webhook delivery capabilities for external system integration.
+Webhooks are delivered asynchronously with retry logic and signature
+verification support.
+"""
+
+import asyncio
+import hashlib
+import hmac
+import json
+import logging
+import time
+from dataclasses import dataclass, field
+from enum import Enum
+
+# TYPE_CHECKING import for forward references
+from typing import TYPE_CHECKING, Dict, List, Optional
+
+from alma.events.types import MemoryEvent, MemoryEventType
+
+if TYPE_CHECKING:
+    from alma.events.emitter import EventEmitter
+
+logger = logging.getLogger(__name__)
+
+# Try to import aiohttp, provide fallback warning
+try:
+    import aiohttp
+
+    AIOHTTP_AVAILABLE = True
+except ImportError:
+    AIOHTTP_AVAILABLE = False
+    logger.warning("aiohttp not installed - webhook delivery will be unavailable")
+
+
+class WebhookDeliveryStatus(Enum):
+    """Status of webhook delivery attempt."""
+
+    SUCCESS = "success"
+    FAILED = "failed"
+    RETRYING = "retrying"
+    PENDING = "pending"
+
+
+@dataclass
+class WebhookConfig:
+    """
+    Configuration for a webhook endpoint.
+
+    Attributes:
+        url: The URL to send webhook payloads to
+        events: List of event types to deliver (empty = all)
+        secret: Optional secret for HMAC signature generation
+        max_retries: Maximum number of retry attempts
+        timeout_seconds: Request timeout in seconds
+        headers: Optional additional headers to include
+    """
+
+    url: str
+    events: List[MemoryEventType] = field(default_factory=list)
+    secret: Optional[str] = None
+    max_retries: int = 3
+    timeout_seconds: int = 10
+    headers: Dict[str, str] = field(default_factory=dict)
+
+    def matches_event(self, event_type: MemoryEventType) -> bool:
+        """Check if this webhook should receive the given event type."""
+        if not self.events:
+            return True  # Empty list means all events
+        return event_type in self.events
+
+
+@dataclass
+class WebhookDeliveryResult:
+    """Result of a webhook delivery attempt."""
+
+    config: WebhookConfig
+    event: MemoryEvent
+    status: WebhookDeliveryStatus
+    status_code: Optional[int] = None
+    attempts: int = 0
+    error: Optional[str] = None
+    response_body: Optional[str] = None
+
+
+class WebhookDelivery:
+    """
+    Handles webhook delivery with retry logic and signature generation.
+
+    Features:
+    - HMAC-SHA256 signature for payload verification
+    - Exponential backoff retry logic
+    - Async delivery to avoid blocking
+    - Configurable timeouts
+
+    Example:
+        ```python
+        configs = [
+            WebhookConfig(
+                url="https://example.com/webhook",
+                events=[MemoryEventType.CREATED],
+                secret="my-secret"
+            )
+        ]
+        delivery = WebhookDelivery(configs)
+        results = await delivery.deliver(event)
+        ```
+    """
+
+    def __init__(self, configs: List[WebhookConfig]):
+        """
+        Initialize webhook delivery.
+
+        Args:
+            configs: List of webhook configurations
+        """
+        self.configs = configs
+
+    async def deliver(self, event: MemoryEvent) -> List[WebhookDeliveryResult]:
+        """
+        Deliver event to all matching webhooks.
+
+        Args:
+            event: The event to deliver
+
+        Returns:
+            List of delivery results for each webhook
+        """
+        if not AIOHTTP_AVAILABLE:
+            logger.error("Cannot deliver webhooks: aiohttp not installed")
+            return []
+
+        # Filter to matching webhooks
+        matching_configs = [
+            config for config in self.configs if config.matches_event(event.event_type)
+        ]
+
+        if not matching_configs:
+            return []
+
+        # Deliver to all matching webhooks concurrently
+        tasks = [self._send_webhook(config, event) for config in matching_configs]
+
+        results = await asyncio.gather(*tasks, return_exceptions=True)
+
+        # Handle any exceptions that occurred
+        delivery_results = []
+        for i, result in enumerate(results):
+            if isinstance(result, Exception):
+                delivery_results.append(
+                    WebhookDeliveryResult(
+                        config=matching_configs[i],
+                        event=event,
+                        status=WebhookDeliveryStatus.FAILED,
+                        error=str(result),
+                    )
+                )
+            else:
+                delivery_results.append(result)
+
+        return delivery_results
+
+    def _sign_payload(self, payload: str, secret: str) -> str:
+        """
+        Sign payload with HMAC-SHA256.
+
+        Args:
+            payload: JSON payload string
+            secret: Secret key for signing
+
+        Returns:
+            Hexadecimal signature string
+        """
+        return hmac.new(
+            secret.encode("utf-8"),
+            payload.encode("utf-8"),
+            hashlib.sha256,
+        ).hexdigest()
+
+    def _build_headers(
+        self,
+        config: WebhookConfig,
+        payload: str,
+        timestamp: int,
+    ) -> Dict[str, str]:
+        """Build headers for webhook request."""
+        headers = {
+            "Content-Type": "application/json",
+            "X-ALMA-Event-Type": payload,  # Will be replaced with actual event type
+            "X-ALMA-Timestamp": str(timestamp),
+            **config.headers,
+        }
+
+        if config.secret:
+            # Create signature from timestamp + payload
+            signature_payload = f"{timestamp}.{payload}"
+            signature = self._sign_payload(signature_payload, config.secret)
+            headers["X-ALMA-Signature"] = f"sha256={signature}"
+
+        return headers
+
+    async def _send_webhook(
+        self,
+        config: WebhookConfig,
+        event: MemoryEvent,
+    ) -> WebhookDeliveryResult:
+        """
+        Send a single webhook with retry logic.
+
+        Uses exponential backoff for retries:
+        - Attempt 1: immediate
+        - Attempt 2: 1 second delay
+        - Attempt 3: 2 second delay
+        - Attempt 4: 4 second delay
+
+        Args:
+            config: Webhook configuration
+            event: Event to deliver
+
+        Returns:
+            Delivery result
+        """
+        payload = json.dumps(event.to_dict(), default=str)
+        timestamp = int(time.time())
+
+        headers = {
+            "Content-Type": "application/json",
+            "X-ALMA-Event-Type": event.event_type.value,
+            "X-ALMA-Timestamp": str(timestamp),
+            **config.headers,
+        }
+
+        if config.secret:
+            signature_payload = f"{timestamp}.{payload}"
+            signature = self._sign_payload(signature_payload, config.secret)
+            headers["X-ALMA-Signature"] = f"sha256={signature}"
+
+        attempts = 0
+        last_error = None
+        last_status_code = None
+
+        async with aiohttp.ClientSession() as session:
+            for attempt in range(config.max_retries + 1):
+                attempts = attempt + 1
+
+                try:
+                    async with session.post(
+                        config.url,
+                        data=payload,
+                        headers=headers,
+                        timeout=aiohttp.ClientTimeout(total=config.timeout_seconds),
+                    ) as response:
+                        last_status_code = response.status
+
+                        if 200 <= response.status < 300:
+                            logger.info(
+                                f"Webhook delivered successfully to {config.url} "
+                                f"(attempt {attempts})"
+                            )
+                            return WebhookDeliveryResult(
+                                config=config,
+                                event=event,
+                                status=WebhookDeliveryStatus.SUCCESS,
+                                status_code=response.status,
+                                attempts=attempts,
+                            )
+
+                        # Non-2xx response
+                        response_body = await response.text()
+                        last_error = f"HTTP {response.status}: {response_body[:200]}"
+                        logger.warning(
+                            f"Webhook delivery failed to {config.url}: {last_error}"
+                        )
+
+                except asyncio.TimeoutError:
+                    last_error = f"Timeout after {config.timeout_seconds} seconds"
+                    logger.warning(
+                        f"Webhook delivery timeout to {config.url} (attempt {attempts})"
+                    )
+
+                except aiohttp.ClientError as e:
+                    last_error = str(e)
+                    logger.warning(
+                        f"Webhook delivery error to {config.url}: {e} (attempt {attempts})"
+                    )
+
+                # Calculate backoff for next attempt
+                if attempt < config.max_retries:
+                    backoff = 2**attempt  # 1, 2, 4 seconds
+                    await asyncio.sleep(backoff)
+
+        # All retries exhausted
+        logger.error(
+            f"Webhook delivery failed after {attempts} attempts to {config.url}"
+        )
+        return WebhookDeliveryResult(
+            config=config,
+            event=event,
+            status=WebhookDeliveryStatus.FAILED,
+            status_code=last_status_code,
+            attempts=attempts,
+            error=last_error,
+        )
+
+    def add_config(self, config: WebhookConfig) -> None:
+        """Add a webhook configuration."""
+        self.configs.append(config)
+
+    def remove_config(self, url: str) -> bool:
+        """
+        Remove a webhook configuration by URL.
+
+        Args:
+            url: URL of the webhook to remove
+
+        Returns:
+            True if removed, False if not found
+        """
+        for i, config in enumerate(self.configs):
+            if config.url == url:
+                self.configs.pop(i)
+                return True
+        return False
+
+
+class WebhookManager:
+    """
+    High-level manager for webhook delivery integrated with the event emitter.
+
+    Automatically subscribes to the event emitter and delivers webhooks
+    for configured events.
+
+    Example:
+        ```python
+        from alma.events import get_emitter
+        from alma.events.webhook import WebhookManager, WebhookConfig
+
+        manager = WebhookManager()
+        manager.add_webhook(WebhookConfig(
+            url="https://example.com/webhook",
+            secret="my-secret"
+        ))
+        manager.start(get_emitter())
+        ```
+    """
+
+    def __init__(self):
+        """Initialize the webhook manager."""
+        self._configs: List[WebhookConfig] = []
+        self._delivery: Optional[WebhookDelivery] = None
+        self._running = False
+
+    def add_webhook(self, config: WebhookConfig) -> None:
+        """Add a webhook configuration."""
+        self._configs.append(config)
+        if self._delivery:
+            self._delivery.add_config(config)
+
+    def remove_webhook(self, url: str) -> bool:
+        """Remove a webhook by URL."""
+        for i, config in enumerate(self._configs):
+            if config.url == url:
+                self._configs.pop(i)
+                if self._delivery:
+                    self._delivery.remove_config(url)
+                return True
+        return False
+
+    def start(self, emitter: "EventEmitter") -> None:
+        """
+        Start the webhook manager.
+
+        Subscribes to all events from the emitter.
+
+        Args:
+            emitter: The event emitter to subscribe to
+        """
+
+        if self._running:
+            return
+
+        self._delivery = WebhookDelivery(self._configs)
+        emitter.subscribe_all(self._on_event)
+        self._running = True
+        logger.info(f"Webhook manager started with {len(self._configs)} webhooks")
+
+    def stop(self, emitter: "EventEmitter") -> None:
+        """
+        Stop the webhook manager.
+
+        Args:
+            emitter: The event emitter to unsubscribe from
+        """
+
+        if not self._running:
+            return
+
+        emitter.unsubscribe_all(self._on_event)
+        self._running = False
+        logger.info("Webhook manager stopped")
+
+    def _on_event(self, event: MemoryEvent) -> None:
+        """Handle incoming events by delivering webhooks."""
+        if not self._delivery or not AIOHTTP_AVAILABLE:
+            return
+
+        # Run async delivery in a new event loop if needed
+        try:
+            asyncio.get_running_loop()
+            asyncio.create_task(self._delivery.deliver(event))
+        except RuntimeError:
+            # No running event loop, create one
+            asyncio.run(self._delivery.deliver(event))
+
+    @property
+    def webhook_count(self) -> int:
+        """Get the number of configured webhooks."""
+        return len(self._configs)
+
+    @property
+    def is_running(self) -> bool:
+        """Check if the manager is running."""
+        return self._running

alma/exceptions.py

@@ -0,0 +1,49 @@
+"""
+ALMA Exception Hierarchy
+
+Custom exceptions for the ALMA memory system, providing clear error
+categorization for configuration, storage, embedding, retrieval,
+and extraction operations.
+"""
+
+
+class ALMAError(Exception):
+    """Base exception for all ALMA errors."""
+
+    pass
+
+
+class ConfigurationError(ALMAError):
+    """Raised when configuration is invalid or missing."""
+
+    pass
+
+
+class ScopeViolationError(ALMAError):
+    """Raised when an agent attempts to learn outside its scope."""
+
+    pass
+
+
+class StorageError(ALMAError):
+    """Raised when storage operations fail."""
+
+    pass
+
+
+class EmbeddingError(ALMAError):
+    """Raised when embedding generation fails."""
+
+    pass
+
+
+class RetrievalError(ALMAError):
+    """Raised when memory retrieval fails."""
+
+    pass
+
+
+class ExtractionError(ALMAError):
+    """Raised when fact extraction fails."""
+
+    pass

alma/extraction/__init__.py

@@ -0,0 +1,31 @@
+"""
+ALMA Extraction Module.
+
+LLM-powered and rule-based fact extraction from conversations.
+"""
+
+from alma.extraction.auto_learner import (
+    AutoLearner,
+    add_auto_learning_to_alma,
+)
+from alma.extraction.extractor import (
+    ExtractedFact,
+    ExtractionResult,
+    FactExtractor,
+    FactType,
+    LLMFactExtractor,
+    RuleBasedExtractor,
+    create_extractor,
+)
+
+__all__ = [
+    "FactExtractor",
+    "LLMFactExtractor",
+    "RuleBasedExtractor",
+    "ExtractedFact",
+    "ExtractionResult",
+    "FactType",
+    "create_extractor",
+    "AutoLearner",
+    "add_auto_learning_to_alma",
+]