aiecs 1.0.1__py3-none-any.whl → 1.7.6__py3-none-any.whl

aiecs/infrastructure/graph_storage/error_handling.py

@@ -0,0 +1,380 @@
+"""
+Comprehensive Error Handling and Logging for Graph Storage
+
+Provides structured error handling, logging, and exception types
+for production-ready graph storage operations.
+"""
+
+import asyncio
+import logging
+import traceback
+from typing import Optional, Dict, Any, Callable
+from enum import Enum
+from dataclasses import dataclass
+from datetime import datetime
+import functools
+
+logger = logging.getLogger(__name__)
+
+
+class GraphStoreError(Exception):
+    """Base exception for graph store errors"""
+
+
+class GraphStoreConnectionError(GraphStoreError):
+    """Connection-related errors"""
+
+
+class GraphStoreQueryError(GraphStoreError):
+    """Query execution errors"""
+
+
+class GraphStoreValidationError(GraphStoreError):
+    """Data validation errors"""
+
+
+class GraphStoreNotFoundError(GraphStoreError):
+    """Entity/relation not found errors"""
+
+
+class GraphStoreConflictError(GraphStoreError):
+    """Conflict errors (duplicate IDs, etc.)"""
+
+
+class GraphStoreTimeoutError(GraphStoreError):
+    """Operation timeout errors"""
+
+
+class ErrorSeverity(str, Enum):
+    """Error severity levels"""
+
+    LOW = "low"
+    MEDIUM = "medium"
+    HIGH = "high"
+    CRITICAL = "critical"
+
+
+@dataclass
+class ErrorContext:
+    """Context information for error reporting"""
+
+    operation: str
+    entity_id: Optional[str] = None
+    relation_id: Optional[str] = None
+    query: Optional[str] = None
+    parameters: Optional[Dict[str, Any]] = None
+    timestamp: Optional[datetime] = None
+    severity: ErrorSeverity = ErrorSeverity.MEDIUM
+
+    def __post_init__(self):
+        if self.timestamp is None:
+            self.timestamp = datetime.utcnow()
+
+    def to_dict(self) -> Dict[str, Any]:
+        """Convert to dictionary for logging"""
+        return {
+            "operation": self.operation,
+            "entity_id": self.entity_id,
+            "relation_id": self.relation_id,
+            "query": (self.query[:100] + "..." if self.query and len(self.query) > 100 else self.query),
+            "parameters": self.parameters,
+            "timestamp": self.timestamp.isoformat() if self.timestamp is not None else None,
+            "severity": self.severity.value,
+        }
+
+
+class ErrorHandler:
+    """
+    Centralized error handling and logging
+
+    Provides structured error handling with context and logging.
+
+    Example:
+        ```python
+        handler = ErrorHandler()
+
+        try:
+            await store.add_entity(entity)
+        except Exception as e:
+            handler.handle_error(
+                e,
+                ErrorContext(
+                    operation="add_entity",
+                    entity_id=entity.id,
+                    severity=ErrorSeverity.HIGH
+                )
+            )
+        ```
+    """
+
+    def __init__(self, log_level: int = logging.ERROR):
+        """
+        Initialize error handler
+
+        Args:
+            log_level: Logging level for errors
+        """
+        self.log_level = log_level
+
+    def handle_error(self, error: Exception, context: ErrorContext, reraise: bool = True) -> None:
+        """
+        Handle and log an error with context
+
+        Args:
+            error: Exception that occurred
+            context: Error context information
+            reraise: Whether to re-raise the exception
+        """
+        # Map exception types
+        mapped_error = self._map_exception(error)
+
+        # Log error with context
+        self._log_error(mapped_error, context)
+
+        # Re-raise if requested
+        if reraise:
+            raise mapped_error from error
+
+    def _map_exception(self, error: Exception) -> Exception:
+        """
+        Map generic exceptions to specific graph store exceptions
+
+        Args:
+            error: Original exception
+
+        Returns:
+            Mapped exception
+        """
+        error_str = str(error).lower()
+        error_type = type(error).__name__
+
+        # Connection errors
+        if any(keyword in error_str for keyword in ["connection", "connect", "timeout", "network"]):
+            return GraphStoreConnectionError(str(error))
+
+        # Not found errors
+        if any(keyword in error_str for keyword in ["not found", "does not exist", "missing"]):
+            return GraphStoreNotFoundError(str(error))
+
+        # Conflict errors
+        if any(
+            keyword in error_str
+            for keyword in [
+                "duplicate",
+                "already exists",
+                "conflict",
+                "unique",
+            ]
+        ):
+            return GraphStoreConflictError(str(error))
+
+        # Validation errors
+        if any(keyword in error_str for keyword in ["invalid", "validation", "required", "missing"]):
+            return GraphStoreValidationError(str(error))
+
+        # Timeout errors
+        if "timeout" in error_str or "TimeoutError" in error_type:
+            return GraphStoreTimeoutError(str(error))
+
+        # Query errors
+        if any(keyword in error_str for keyword in ["syntax", "query", "sql", "execute"]):
+            return GraphStoreQueryError(str(error))
+
+        # Return original if no mapping
+        return error
+
+    def _log_error(self, error: Exception, context: ErrorContext) -> None:
+        """
+        Log error with structured context
+
+        Args:
+            error: Exception to log
+            context: Error context
+        """
+        error_dict = {
+            "error_type": type(error).__name__,
+            "error_message": str(error),
+            "context": context.to_dict(),
+            "traceback": traceback.format_exc(),
+        }
+
+        # Log based on severity
+        if context.severity == ErrorSeverity.CRITICAL:
+            logger.critical(f"CRITICAL: {error_dict}")
+        elif context.severity == ErrorSeverity.HIGH:
+            logger.error(f"HIGH: {error_dict}")
+        elif context.severity == ErrorSeverity.MEDIUM:
+            logger.warning(f"MEDIUM: {error_dict}")
+        else:
+            logger.info(f"LOW: {error_dict}")
+
+
+def error_handler(
+    operation: str,
+    severity: ErrorSeverity = ErrorSeverity.MEDIUM,
+    reraise: bool = True,
+):
+    """
+    Decorator for automatic error handling
+
+    Args:
+        operation: Operation name for context
+        severity: Error severity level
+        reraise: Whether to re-raise exceptions
+
+    Example:
+        ```python
+        @error_handler("add_entity", severity=ErrorSeverity.HIGH)
+        async def add_entity(self, entity: Entity):
+            # Implementation
+            pass
+        ```
+    """
+
+    def decorator(func: Callable) -> Callable:
+        @functools.wraps(func)
+        async def wrapper(self, *args, **kwargs):
+            handler = ErrorHandler()
+
+            # Extract context from arguments
+            entity_id = None
+            relation_id = None
+
+            if args and hasattr(args[0], "id"):
+                entity_id = args[0].id
+            elif "entity_id" in kwargs:
+                entity_id = kwargs["entity_id"]
+            elif "relation_id" in kwargs:
+                relation_id = kwargs["relation_id"]
+
+            context = ErrorContext(
+                operation=operation,
+                entity_id=entity_id,
+                relation_id=relation_id,
+                severity=severity,
+            )
+
+            try:
+                return await func(self, *args, **kwargs)
+            except Exception as e:
+                handler.handle_error(e, context, reraise=reraise)
+
+        return wrapper
+
+    return decorator
+
+
+class RetryHandler:
+    """
+    Retry handler for transient errors
+
+    Implements exponential backoff retry logic for operations
+    that may fail due to transient issues.
+
+    Example:
+        ```python
+        retry = RetryHandler(max_retries=3, base_delay=1.0)
+
+        result = await retry.execute(
+            lambda: store.get_entity("entity_1"),
+            retry_on=[GraphStoreConnectionError]
+        )
+        ```
+    """
+
+    def __init__(
+        self,
+        max_retries: int = 3,
+        base_delay: float = 1.0,
+        max_delay: float = 60.0,
+        exponential_base: float = 2.0,
+    ):
+        """
+        Initialize retry handler
+
+        Args:
+            max_retries: Maximum number of retry attempts
+            base_delay: Base delay in seconds
+            max_delay: Maximum delay in seconds
+            exponential_base: Exponential backoff multiplier
+        """
+        self.max_retries = max_retries
+        self.base_delay = base_delay
+        self.max_delay = max_delay
+        self.exponential_base = exponential_base
+
+    async def execute(self, func: Callable, retry_on: Optional[list] = None, *args, **kwargs) -> Any:
+        """
+        Execute function with retry logic
+
+        Args:
+            func: Async function to execute
+            retry_on: List of exception types to retry on (None = all)
+            *args: Function arguments
+            **kwargs: Function keyword arguments
+
+        Returns:
+            Function result
+
+        Raises:
+            Last exception if all retries fail
+        """
+        if retry_on is None:
+            retry_on = [Exception]
+
+        last_exception = None
+
+        for attempt in range(self.max_retries + 1):
+            try:
+                return await func(*args, **kwargs)
+            except Exception as e:
+                last_exception = e
+
+                # Check if we should retry
+                if not any(isinstance(e, exc_type) for exc_type in retry_on):
+                    raise
+
+                # Don't retry on last attempt
+                if attempt >= self.max_retries:
+                    break
+
+                # Calculate delay with exponential backoff
+                delay = min(
+                    self.base_delay * (self.exponential_base**attempt),
+                    self.max_delay,
+                )
+
+                logger.warning(f"Retry attempt {attempt + 1}/{self.max_retries} after {delay:.1f}s: {e}")
+
+                await asyncio.sleep(delay)
+
+        # All retries exhausted
+        if last_exception is None:
+            raise RuntimeError("Retry logic failed but no exception was captured")
+        raise last_exception
+
+
+# Configure logging for graph storage
+def configure_graph_storage_logging(level: int = logging.INFO, format_string: Optional[str] = None) -> None:
+    """
+    Configure logging for graph storage modules
+
+    Args:
+        level: Logging level
+        format_string: Custom format string
+    """
+    if format_string is None:
+        format_string = "%(asctime)s - %(name)s - %(levelname)s - " "%(message)s - [%(filename)s:%(lineno)d]"
+
+    handler = logging.StreamHandler()
+    handler.setFormatter(logging.Formatter(format_string))
+
+    # Configure graph storage logger
+    graph_logger = logging.getLogger("aiecs.infrastructure.graph_storage")
+    graph_logger.setLevel(level)
+    graph_logger.addHandler(handler)
+
+    logger.info(f"Graph storage logging configured at level {logging.getLevelName(level)}")
+
+
+# Import asyncio for retry handler

aiecs/infrastructure/graph_storage/graceful_degradation.py

@@ -0,0 +1,294 @@
+"""
+Graceful Degradation for Graph Storage
+
+Provides automatic fallback to in-memory storage when primary backend fails,
+ensuring service continuity even during backend outages.
+"""
+
+import logging
+from typing import Optional, Any, Dict
+from dataclasses import dataclass
+from enum import Enum
+
+from aiecs.infrastructure.graph_storage import InMemoryGraphStore, GraphStore
+from aiecs.infrastructure.graph_storage.error_handling import (
+    GraphStoreConnectionError,
+    GraphStoreError,
+    ErrorHandler,
+    ErrorContext,
+    ErrorSeverity,
+)
+
+logger = logging.getLogger(__name__)
+
+
+class DegradationMode(str, Enum):
+    """Degradation mode"""
+
+    NORMAL = "normal"  # Using primary backend
+    DEGRADED = "degraded"  # Using fallback
+    FAILED = "failed"  # Both backends failed
+
+
+@dataclass
+class DegradationStatus:
+    """Status of graceful degradation"""
+
+    mode: DegradationMode
+    primary_available: bool
+    fallback_available: bool
+    last_failure: Optional[str] = None
+    failure_count: int = 0
+
+    def to_dict(self) -> Dict[str, Any]:
+        """Convert to dictionary"""
+        return {
+            "mode": self.mode.value,
+            "primary_available": self.primary_available,
+            "fallback_available": self.fallback_available,
+            "last_failure": self.last_failure,
+            "failure_count": self.failure_count,
+        }
+
+
+class GracefulDegradationStore:
+    """
+    Graph store with graceful degradation support
+
+    Automatically falls back to in-memory storage when primary backend fails.
+
+    Example:
+        ```python
+        primary = PostgresGraphStore(...)
+        store = GracefulDegradationStore(primary)
+        await store.initialize()
+
+        # If PostgreSQL fails, automatically uses in-memory fallback
+        entity = await store.get_entity("entity_1")
+        ```
+    """
+
+    def __init__(
+        self,
+        primary_store: GraphStore,
+        enable_fallback: bool = True,
+        max_failures: int = 3,
+    ):
+        """
+        Initialize graceful degradation store
+
+        Args:
+            primary_store: Primary graph store backend
+            enable_fallback: Enable automatic fallback
+            max_failures: Max failures before switching to fallback
+        """
+        self.primary_store = primary_store
+        self.enable_fallback = enable_fallback
+        self.max_failures = max_failures
+
+        self.fallback_store: Optional[InMemoryGraphStore] = None
+        self.status = DegradationStatus(
+            mode=DegradationMode.NORMAL,
+            primary_available=True,
+            fallback_available=False,
+        )
+        self.failure_count = 0
+        self.error_handler = ErrorHandler()
+
+    async def initialize(self) -> None:
+        """Initialize both primary and fallback stores"""
+        # Initialize primary
+        try:
+            await self.primary_store.initialize()
+            self.status.primary_available = True
+            logger.info("Primary store initialized successfully")
+        except Exception as e:
+            self.status.primary_available = False
+            self.status.last_failure = str(e)
+            logger.error(f"Primary store initialization failed: {e}")
+
+            if self.enable_fallback:
+                await self._initialize_fallback()
+
+        # Initialize fallback if enabled
+        if self.enable_fallback and not self.fallback_store:
+            await self._initialize_fallback()
+
+    async def _initialize_fallback(self) -> None:
+        """Initialize fallback in-memory store"""
+        try:
+            self.fallback_store = InMemoryGraphStore()
+            await self.fallback_store.initialize()
+            self.status.fallback_available = True
+            self.status.mode = DegradationMode.DEGRADED
+            logger.warning("Using fallback in-memory store")
+        except Exception as e:
+            self.status.fallback_available = False
+            self.status.mode = DegradationMode.FAILED
+            logger.critical(f"Fallback store initialization failed: {e}")
+
+    async def close(self) -> None:
+        """Close both stores"""
+        if self.primary_store:
+            try:
+                await self.primary_store.close()
+            except Exception as e:
+                logger.warning(f"Error closing primary store: {e}")
+
+        if self.fallback_store:
+            try:
+                await self.fallback_store.close()
+            except Exception as e:
+                logger.warning(f"Error closing fallback store: {e}")
+
+    def _get_active_store(self) -> GraphStore:
+        """
+        Get the currently active store (primary or fallback)
+
+        Returns:
+            Active graph store
+
+        Raises:
+            GraphStoreError: If no store is available
+        """
+        if self.status.primary_available:
+            return self.primary_store
+        elif self.status.fallback_available and self.fallback_store:
+            return self.fallback_store
+        else:
+            raise GraphStoreError("No graph store available (primary and fallback both failed)")
+
+    async def _execute_with_fallback(self, operation: str, func, *args, **kwargs):
+        """
+        Execute operation with automatic fallback
+
+        Args:
+            operation: Operation name for error context
+            func: Function to execute
+            *args: Function arguments
+            **kwargs: Function keyword arguments
+
+        Returns:
+            Function result
+        """
+        # Try primary first
+        if self.status.primary_available:
+            try:
+                result = await func(self.primary_store, *args, **kwargs)
+
+                # Reset failure count on success
+                if self.failure_count > 0:
+                    logger.info("Primary store recovered, switching back")
+                    self.failure_count = 0
+                    self.status.primary_available = True
+                    self.status.mode = DegradationMode.NORMAL
+
+                return result
+
+            except (GraphStoreConnectionError, Exception) as e:
+                self.failure_count += 1
+                self.status.last_failure = str(e)
+
+                # Log error
+                self.error_handler.handle_error(
+                    e,
+                    ErrorContext(operation=operation, severity=ErrorSeverity.HIGH),
+                    reraise=False,
+                )
+
+                # Switch to fallback if threshold reached
+                if self.failure_count >= self.max_failures:
+                    logger.warning(f"Primary store failed {self.failure_count} times, " f"switching to fallback")
+                    self.status.primary_available = False
+                    self.status.mode = DegradationMode.DEGRADED
+
+                # Try fallback if available
+                if self.status.fallback_available and self.fallback_store:
+                    try:
+                        return await func(self.fallback_store, *args, **kwargs)
+                    except Exception as fallback_error:
+                        logger.error(f"Fallback store also failed: {fallback_error}")
+                        self.status.fallback_available = False
+                        self.status.mode = DegradationMode.FAILED
+                        raise GraphStoreError(f"Both primary and fallback stores failed. " f"Primary: {e}, Fallback: {fallback_error}")
+                else:
+                    # No fallback available, raise original error
+                    raise
+
+        # Use fallback if primary unavailable
+        elif self.status.fallback_available and self.fallback_store:
+            try:
+                return await func(self.fallback_store, *args, **kwargs)
+            except Exception as e:
+                logger.error(f"Fallback store failed: {e}")
+                self.status.fallback_available = False
+                self.status.mode = DegradationMode.FAILED
+                raise GraphStoreError(f"Fallback store failed: {e}")
+
+        else:
+            raise GraphStoreError("No graph store available")
+
+    # Delegate all GraphStore methods with fallback
+    async def add_entity(self, entity):
+        """Add entity with fallback"""
+        return await self._execute_with_fallback("add_entity", lambda store, e: store.add_entity(e), entity)
+
+    async def get_entity(self, entity_id: str):
+        """Get entity with fallback"""
+        return await self._execute_with_fallback("get_entity", lambda store, eid: store.get_entity(eid), entity_id)
+
+    async def add_relation(self, relation):
+        """Add relation with fallback"""
+        return await self._execute_with_fallback("add_relation", lambda store, r: store.add_relation(r), relation)
+
+    async def get_relation(self, relation_id: str):
+        """Get relation with fallback"""
+        return await self._execute_with_fallback(
+            "get_relation",
+            lambda store, rid: store.get_relation(rid),
+            relation_id,
+        )
+
+    async def get_neighbors(self, entity_id: str, **kwargs):
+        """Get neighbors with fallback"""
+        return await self._execute_with_fallback(
+            "get_neighbors",
+            lambda store, eid, **kw: store.get_neighbors(eid, **kw),
+            entity_id,
+            **kwargs,
+        )
+
+    async def get_stats(self):
+        """Get stats with fallback"""
+        return await self._execute_with_fallback("get_stats", lambda store: store.get_stats())
+
+    def get_degradation_status(self) -> DegradationStatus:
+        """Get current degradation status"""
+        return self.status
+
+    async def try_recover_primary(self) -> bool:
+        """
+        Attempt to recover primary store
+
+        Returns:
+            True if recovery successful, False otherwise
+        """
+        if self.status.primary_available:
+            return True
+
+        try:
+            # Try to reinitialize primary
+            await self.primary_store.initialize()
+
+            # Test with a simple operation (available via StatsMixinProtocol)
+            await self.primary_store.get_stats()  # type: ignore[attr-defined]
+
+            self.status.primary_available = True
+            self.status.mode = DegradationMode.NORMAL
+            self.failure_count = 0
+            logger.info("Primary store recovered successfully")
+            return True
+
+        except Exception as e:
+            logger.warning(f"Primary store recovery failed: {e}")
+            return False