pygeai-orchestration 0.1.0b2__py3-none-any.whl

pygeai_orchestration/core/handlers.py

@@ -0,0 +1,380 @@
+"""
+Error handling utilities for pygeai-orchestration.
+
+This module provides centralized error handling functionality following
+the PyGEAI pattern. The ErrorHandler class offers consistent error detection,
+extraction, and processing across the orchestration package.
+"""
+
+from typing import Any, Dict, Optional
+import logging
+
+from .exceptions import OrchestrationError
+
+
+logger = logging.getLogger("pygeai-orchestration")
+
+
+class ErrorHandler:
+    """
+    Centralized error handler for orchestration operations.
+
+    This class provides static methods for detecting, extracting, and handling
+    errors in a consistent manner across the package. It follows the PyGEAI
+    ErrorHandler pattern for uniform error processing.
+
+    The ErrorHandler can process various response formats and extract error
+    information, making it easier to handle errors from different sources
+    (agents, tools, external APIs, etc.).
+
+    Example:
+        >>> response = {"error": "Agent timeout", "code": 500}
+        >>> if ErrorHandler.has_errors(response):
+        ...     error = ErrorHandler.extract_error(response)
+        ...     ErrorHandler.handle_error(error, context={"operation": "generate"})
+    """
+
+    @staticmethod
+    def has_errors(response: Any) -> bool:
+        """
+        Check if a response contains error information.
+
+        Detects errors in various response formats including:
+        - Dictionary with 'error' or 'errors' key
+        - Dictionary with 'success': False
+        - Dictionary with 'status' indicating error
+        - Exception objects
+
+        :param response: Any - The response to check for errors.
+        :return: bool - True if errors are detected, False otherwise.
+
+        Example:
+            >>> ErrorHandler.has_errors({"error": "Failed"})
+            True
+            >>> ErrorHandler.has_errors({"success": True})
+            False
+        """
+        if response is None:
+            return False
+
+        if isinstance(response, Exception):
+            return True
+
+        if isinstance(response, dict):
+            # Check for explicit error keys
+            if "error" in response and response["error"]:
+                return True
+            if "errors" in response and response["errors"]:
+                return True
+
+            # Check for success flag
+            if "success" in response and response["success"] is False:
+                return True
+
+            # Check for error status codes
+            if "status" in response:
+                status = response["status"]
+                if isinstance(status, int) and status >= 400:
+                    return True
+                if isinstance(status, str) and status.lower() in ["error", "failed", "failure"]:
+                    return True
+
+            # Check for code indicating error
+            if "code" in response:
+                code = response["code"]
+                if isinstance(code, int) and code >= 400:
+                    return True
+
+        return False
+
+    @staticmethod
+    def extract_error(response: Any) -> str:
+        """
+        Extract error message from a response.
+
+        Attempts to extract a meaningful error message from various response
+        formats. Returns a descriptive error message or a generic message if
+        the specific error cannot be determined.
+
+        :param response: Any - The response containing error information.
+        :return: str - The extracted error message.
+
+        Example:
+            >>> response = {"error": "Connection timeout", "code": 504}
+            >>> ErrorHandler.extract_error(response)
+            'Connection timeout'
+        """
+        if response is None:
+            return "Unknown error: None response"
+
+        if isinstance(response, Exception):
+            return str(response)
+
+        if isinstance(response, str):
+            return response
+
+        if isinstance(response, dict):
+            # Try to extract from common error keys
+            if "error" in response:
+                error = response["error"]
+                if isinstance(error, dict):
+                    # Handle nested error object
+                    return error.get("message", str(error))
+                return str(error)
+
+            if "errors" in response:
+                errors = response["errors"]
+                if isinstance(errors, list) and errors:
+                    # Return first error or join multiple
+                    if len(errors) == 1:
+                        return str(errors[0])
+                    return "; ".join(str(e) for e in errors)
+                return str(errors)
+
+            if "message" in response:
+                return str(response["message"])
+
+            # Try to construct message from status/code
+            if "status" in response or "code" in response:
+                parts = []
+                if "status" in response:
+                    parts.append(f"Status: {response['status']}")
+                if "code" in response:
+                    parts.append(f"Code: {response['code']}")
+                if parts:
+                    return " | ".join(parts)
+
+            # Last resort: stringify the entire response
+            return f"Error in response: {response}"
+
+        return f"Unknown error: {type(response).__name__}"
+
+    @staticmethod
+    def handle_error(
+        error: Any, context: Optional[Dict[str, Any]] = None, log_level: int = logging.ERROR
+    ) -> str:
+        """
+        Handle an error with logging and context.
+
+        Processes an error by extracting the error message, logging it with
+        context, and returning a formatted error message. This provides a
+        centralized point for error processing across the package.
+
+        :param error: Any - The error to handle (Exception, dict, or string).
+        :param context: Optional[Dict[str, Any]] - Additional context for the error.
+        :param log_level: int - Logging level to use. Defaults to logging.ERROR.
+        :return: str - The formatted error message.
+
+        Example:
+            >>> error = {"error": "Pattern failed", "iteration": 5}
+            >>> msg = ErrorHandler.handle_error(
+            ...     error,
+            ...     context={"pattern": "reflection", "task": "summarize"},
+            ...     log_level=logging.WARNING
+            ... )
+        """
+        # Extract error message
+        error_message = ErrorHandler.extract_error(error)
+
+        # Build context string
+        context_str = ""
+        if context:
+            context_parts = [f"{k}={v}" for k, v in context.items()]
+            context_str = f" [{', '.join(context_parts)}]"
+
+        # Format full message
+        full_message = f"{error_message}{context_str}"
+
+        # Log the error
+        logger.log(log_level, full_message)
+
+        return full_message
+
+    @staticmethod
+    def wrap_exception(
+        error: Exception,
+        exception_class: type = OrchestrationError,
+        message_prefix: Optional[str] = None,
+        **kwargs,
+    ) -> OrchestrationError:
+        """
+        Wrap an exception in a custom orchestration exception.
+
+        Converts generic exceptions into specific orchestration exceptions
+        while preserving the original error message and adding context.
+
+        :param error: Exception - The original exception to wrap.
+        :param exception_class: type - The exception class to wrap with. Defaults to OrchestrationError.
+        :param message_prefix: Optional[str] - Prefix to add to error message.
+        :param kwargs: Additional keyword arguments for the exception class.
+        :return: OrchestrationError - The wrapped exception.
+
+        Example:
+            >>> try:
+            ...     risky_operation()
+            ... except Exception as e:
+            ...     raise ErrorHandler.wrap_exception(
+            ...         e,
+            ...         PatternExecutionError,
+            ...         message_prefix="Pattern execution failed",
+            ...         pattern_name="reflection",
+            ...         iteration=3
+            ...     )
+        """
+        original_message = str(error)
+
+        if message_prefix:
+            message = f"{message_prefix}: {original_message}"
+        else:
+            message = original_message
+
+        # Create the wrapped exception
+        wrapped = exception_class(message, **kwargs)
+
+        # Preserve the original exception as context
+        wrapped.__cause__ = error
+
+        return wrapped
+
+    @staticmethod
+    def is_recoverable(error: Any) -> bool:
+        """
+        Determine if an error is potentially recoverable.
+
+        Analyzes an error to determine if the operation could potentially
+        succeed if retried. This helps in implementing retry logic.
+
+        :param error: Any - The error to analyze.
+        :return: bool - True if the error might be recoverable, False otherwise.
+
+        Example:
+            >>> error = {"error": "Timeout", "code": 504}
+            >>> if ErrorHandler.is_recoverable(error):
+            ...     retry_operation()
+        """
+        if isinstance(error, dict):
+            # Check status/code for recoverable errors
+            code = error.get("code", 0)
+            if isinstance(code, int):
+                # Timeout and rate limit errors are often recoverable
+                if code in [408, 429, 503, 504]:
+                    return True
+
+            # Check for specific error types
+            error_msg = str(ErrorHandler.extract_error(error)).lower()
+            recoverable_keywords = [
+                "timeout",
+                "rate limit",
+                "too many requests",
+                "service unavailable",
+                "connection",
+                "temporary",
+            ]
+
+            return any(keyword in error_msg for keyword in recoverable_keywords)
+
+        if isinstance(error, Exception):
+            error_str = str(error).lower()
+            recoverable_types = [
+                "timeout",
+                "connection",
+                "temporary",
+            ]
+            return any(err_type in error_str for err_type in recoverable_types)
+
+        return False
+
+    @staticmethod
+    def format_error_response(error: Any, include_details: bool = True) -> Dict[str, Any]:
+        """
+        Format an error as a standardized response dictionary.
+
+        Converts various error formats into a consistent dictionary structure
+        that can be used across the package.
+
+        :param error: Any - The error to format.
+        :param include_details: bool - Whether to include detailed error information.
+        :return: Dict[str, Any] - Standardized error response.
+
+        Example:
+            >>> error = ValueError("Invalid input")
+            >>> response = ErrorHandler.format_error_response(error)
+            >>> print(response)
+            {'success': False, 'error': 'Invalid input', 'error_type': 'ValueError'}
+        """
+        response = {
+            "success": False,
+            "error": ErrorHandler.extract_error(error),
+        }
+
+        if include_details:
+            if isinstance(error, Exception):
+                response["error_type"] = type(error).__name__
+                if hasattr(error, "__cause__") and error.__cause__:
+                    response["original_error"] = str(error.__cause__)
+
+            if isinstance(error, dict):
+                # Include additional fields from error dict
+                for key in ["code", "status", "details"]:
+                    if key in error:
+                        response[key] = error[key]
+
+        return response
+
+
+class RetryHandler:
+    """
+    Handler for implementing retry logic with error handling.
+
+    This class provides utilities for retrying operations that may fail
+    transiently, with configurable retry strategies and error handling.
+
+    Example:
+        >>> handler = RetryHandler(max_retries=3, delay=1.0)
+        >>> result = await handler.execute_with_retry(risky_operation, arg1, arg2)
+    """
+
+    def __init__(
+        self,
+        max_retries: int = 3,
+        delay: float = 1.0,
+        backoff_factor: float = 2.0,
+        recoverable_only: bool = True,
+    ):
+        """
+        Initialize the RetryHandler.
+
+        :param max_retries: int - Maximum number of retry attempts. Defaults to 3.
+        :param delay: float - Initial delay between retries in seconds. Defaults to 1.0.
+        :param backoff_factor: float - Multiplier for delay on each retry. Defaults to 2.0.
+        :param recoverable_only: bool - Only retry recoverable errors. Defaults to True.
+        """
+        self.max_retries = max_retries
+        self.delay = delay
+        self.backoff_factor = backoff_factor
+        self.recoverable_only = recoverable_only
+
+    def should_retry(self, error: Any, attempt: int) -> bool:
+        """
+        Determine if an operation should be retried.
+
+        :param error: Any - The error that occurred.
+        :param attempt: int - Current attempt number (0-indexed).
+        :return: bool - True if should retry, False otherwise.
+        """
+        if attempt >= self.max_retries:
+            return False
+
+        if self.recoverable_only:
+            return ErrorHandler.is_recoverable(error)
+
+        return True
+
+    def get_delay(self, attempt: int) -> float:
+        """
+        Calculate delay before next retry.
+
+        :param attempt: int - Current attempt number (0-indexed).
+        :return: float - Delay in seconds.
+        """
+        return self.delay * (self.backoff_factor**attempt)

pygeai_orchestration/core/utils/__init__.py

@@ -0,0 +1,37 @@
+from .logging import OrchestrationLogger, get_logger
+from .config import ConfigManager, get_config
+from .validators import (
+    ValidationResult,
+    validate_agent_config,
+    validate_pattern_config,
+    validate_tool_config,
+    validate_pydantic_model,
+)
+from .cache import CacheEntry, LRUCache, PatternCache
+from .metrics import (
+    Metric,
+    MetricType,
+    MetricsCollector,
+    GlobalMetrics,
+    TimerContext,
+)
+
+__all__ = [
+    "OrchestrationLogger",
+    "get_logger",
+    "ConfigManager",
+    "get_config",
+    "ValidationResult",
+    "validate_agent_config",
+    "validate_pattern_config",
+    "validate_tool_config",
+    "validate_pydantic_model",
+    "CacheEntry",
+    "LRUCache",
+    "PatternCache",
+    "Metric",
+    "MetricType",
+    "MetricsCollector",
+    "GlobalMetrics",
+    "TimerContext",
+]

pygeai_orchestration/core/utils/cache.py

@@ -0,0 +1,138 @@
+import hashlib
+import json
+import time
+from collections import OrderedDict
+from typing import Any, Optional
+
+
+class CacheEntry:
+    def __init__(self, value: Any, ttl: Optional[float] = None):
+        self.value = value
+        self.created_at = time.time()
+        self.ttl = ttl
+        self.access_count = 0
+        self.last_accessed = self.created_at
+
+    def is_expired(self) -> bool:
+        if self.ttl is None:
+            return False
+        return (time.time() - self.created_at) > self.ttl
+
+    def access(self) -> Any:
+        self.access_count += 1
+        self.last_accessed = time.time()
+        return self.value
+
+
+class LRUCache:
+    def __init__(self, max_size: int = 100, default_ttl: Optional[float] = None):
+        self.max_size = max_size
+        self.default_ttl = default_ttl
+        self._cache: OrderedDict[str, CacheEntry] = OrderedDict()
+        self._hits = 0
+        self._misses = 0
+
+    def _generate_key(self, key_data: Any) -> str:
+        if isinstance(key_data, str):
+            return hashlib.sha256(key_data.encode()).hexdigest()
+        try:
+            serialized = json.dumps(key_data, sort_keys=True)
+            return hashlib.sha256(serialized.encode()).hexdigest()
+        except (TypeError, ValueError):
+            return hashlib.sha256(str(key_data).encode()).hexdigest()
+
+    def get(self, key: Any) -> Optional[Any]:
+        cache_key = self._generate_key(key)
+
+        if cache_key not in self._cache:
+            self._misses += 1
+            return None
+
+        entry = self._cache[cache_key]
+
+        if entry.is_expired():
+            del self._cache[cache_key]
+            self._misses += 1
+            return None
+
+        self._cache.move_to_end(cache_key)
+        self._hits += 1
+        return entry.access()
+
+    def set(self, key: Any, value: Any, ttl: Optional[float] = None) -> None:
+        cache_key = self._generate_key(key)
+
+        if len(self._cache) >= self.max_size and cache_key not in self._cache:
+            self._cache.popitem(last=False)
+
+        effective_ttl = ttl if ttl is not None else self.default_ttl
+        self._cache[cache_key] = CacheEntry(value, effective_ttl)
+        self._cache.move_to_end(cache_key)
+
+    def invalidate(self, key: Any) -> bool:
+        cache_key = self._generate_key(key)
+        if cache_key in self._cache:
+            del self._cache[cache_key]
+            return True
+        return False
+
+    def clear(self) -> None:
+        self._cache.clear()
+        self._hits = 0
+        self._misses = 0
+
+    def size(self) -> int:
+        self._cleanup_expired()
+        return len(self._cache)
+
+    def _cleanup_expired(self) -> None:
+        expired_keys = [
+            key for key, entry in self._cache.items() if entry.is_expired()
+        ]
+        for key in expired_keys:
+            del self._cache[key]
+
+    def get_stats(self) -> dict[str, Any]:
+        self._cleanup_expired()
+        total_requests = self._hits + self._misses
+        hit_rate = (self._hits / total_requests * 100) if total_requests > 0 else 0
+
+        return {
+            "size": len(self._cache),
+            "max_size": self.max_size,
+            "hits": self._hits,
+            "misses": self._misses,
+            "hit_rate": hit_rate,
+            "total_requests": total_requests,
+        }
+
+
+class PatternCache:
+    _instance: Optional["PatternCache"] = None
+    _cache: Optional[LRUCache] = None
+
+    def __new__(cls):
+        if cls._instance is None:
+            cls._instance = super().__new__(cls)
+            cls._cache = None
+        return cls._instance
+
+    def initialize(
+        self, max_size: int = 100, default_ttl: Optional[float] = 3600.0
+    ) -> None:
+        if self._cache is None:
+            self._cache = LRUCache(max_size=max_size, default_ttl=default_ttl)
+
+    def get_cache(self) -> LRUCache:
+        if self._cache is None:
+            self.initialize()
+        return self._cache
+
+    def clear(self) -> None:
+        if self._cache is not None:
+            self._cache.clear()
+
+    @classmethod
+    def reset(cls) -> None:
+        cls._instance = None
+        cls._cache = None

pygeai_orchestration/core/utils/config.py

@@ -0,0 +1,94 @@
+from typing import Any, Dict, Optional
+from pathlib import Path
+import json
+
+
+class ConfigManager:
+    _instance: Optional["ConfigManager"] = None
+
+    def __new__(cls):
+        if cls._instance is None:
+            cls._instance = super().__new__(cls)
+        return cls._instance
+
+    def __init__(self):
+        if not hasattr(self, "_initialized"):
+            self._config: Dict[str, Any] = {}
+            self._config_path: Optional[Path] = None
+            self._load_defaults()
+            self._initialized = True
+
+    def _load_defaults(self) -> None:
+        self._config = {
+            "orchestration": {
+                "max_iterations": 10,
+                "timeout": 300.0,
+                "verbose": False,
+                "retry_attempts": 3,
+            },
+            "agent": {
+                "temperature": 0.7,
+                "max_tokens": 4096,
+            },
+            "logging": {
+                "level": "info",
+            },
+        }
+
+    def load_from_file(self, config_path: str) -> None:
+        path = Path(config_path)
+        if not path.exists():
+            raise FileNotFoundError(f"Config file not found: {config_path}")
+
+        with open(path, "r") as f:
+            file_config = json.load(f)
+
+        self._merge_config(file_config)
+        self._config_path = path
+
+    def _merge_config(self, new_config: Dict[str, Any]) -> None:
+        for key, value in new_config.items():
+            if (
+                key in self._config
+                and isinstance(self._config[key], dict)
+                and isinstance(value, dict)
+            ):
+                self._config[key].update(value)
+            else:
+                self._config[key] = value
+
+    def get(self, key: str, default: Any = None) -> Any:
+        keys = key.split(".")
+        value = self._config
+        for k in keys:
+            if isinstance(value, dict):
+                value = value.get(k)
+                if value is None:
+                    return default
+            else:
+                return default
+        return value
+
+    def set(self, key: str, value: Any) -> None:
+        keys = key.split(".")
+        config = self._config
+        for k in keys[:-1]:
+            if k not in config:
+                config[k] = {}
+            config = config[k]
+        config[keys[-1]] = value
+
+    def get_all(self) -> Dict[str, Any]:
+        return self._config.copy()
+
+    def save_to_file(self, config_path: Optional[str] = None) -> None:
+        path = Path(config_path) if config_path else self._config_path
+        if path is None:
+            raise ValueError("No config path specified")
+
+        with open(path, "w") as f:
+            json.dump(self._config, f, indent=2)
+
+
+def get_config() -> ConfigManager:
+    return ConfigManager()

pygeai_orchestration/core/utils/logging.py

@@ -0,0 +1,57 @@
+import logging
+import sys
+from typing import Optional
+
+
+class OrchestrationLogger:
+    _instance: Optional["OrchestrationLogger"] = None
+
+    def __new__(cls):
+        if cls._instance is None:
+            cls._instance = super().__new__(cls)
+        return cls._instance
+
+    def __init__(self):
+        if not hasattr(self, "_initialized"):
+            self._logger = logging.getLogger("pygeai_orchestration")
+            self._logger.setLevel(logging.INFO)
+
+            if not self._logger.handlers:
+                handler = logging.StreamHandler(sys.stdout)
+                formatter = logging.Formatter(
+                    "%(asctime)s - %(name)s - %(levelname)s - %(message)s",
+                    datefmt="%Y-%m-%d %H:%M:%S",
+                )
+                handler.setFormatter(formatter)
+                self._logger.addHandler(handler)
+
+            self._initialized = True
+
+    def set_level(self, level: str) -> None:
+        level_map = {
+            "debug": logging.DEBUG,
+            "info": logging.INFO,
+            "warning": logging.WARNING,
+            "error": logging.ERROR,
+            "critical": logging.CRITICAL,
+        }
+        self._logger.setLevel(level_map.get(level.lower(), logging.INFO))
+
+    def debug(self, message: str, **kwargs) -> None:
+        self._logger.debug(message, **kwargs)
+
+    def info(self, message: str, **kwargs) -> None:
+        self._logger.info(message, **kwargs)
+
+    def warning(self, message: str, **kwargs) -> None:
+        self._logger.warning(message, **kwargs)
+
+    def error(self, message: str, **kwargs) -> None:
+        self._logger.error(message, **kwargs)
+
+    def critical(self, message: str, **kwargs) -> None:
+        self._logger.critical(message, **kwargs)
+
+
+def get_logger() -> OrchestrationLogger:
+    return OrchestrationLogger()