aigency 0.0.1.dev20250904075757__py3-none-any.whl → 0.0.1rc62012314__py3-none-any.whl

aigency/utils/config_service.py

@@ -1,4 +1,24 @@
-"""Configuration service for loading and parsing agent configurations."""
+"""Configuration service for loading and parsing agent configurations.
+
+This module provides comprehensive configuration management for Aigency agents,
+including YAML file loading, environment-specific configuration merging, and
+validation through Pydantic models. It supports hierarchical configuration
+structures and environment-based overrides.
+
+The ConfigService class handles the complete configuration lifecycle from file
+loading through parsing and validation, ensuring that agent configurations
+are properly structured and ready for use by the agent system.
+
+Example:
+    Loading and parsing agent configuration:
+
+    >>> service = ConfigService("config.yaml", environment="production")
+    >>> config = service.config
+    >>> agent_name = config.metadata.name
+
+Attributes:
+    logger: Module-level logger instance for configuration events.
+"""
 
 import os
 from pathlib import Path
@@ -6,63 +26,136 @@ from typing import Any, Dict, Optional
 
 import yaml
 
-from aigency.models.config import AgentConfig
+from aigency.schemas.aigency_config import AigencyConfig
 from aigency.utils.logger import get_logger
 
 
 logger = get_logger()
 
+
 class ConfigService:
-    """Service for loading and managing agent configurations."""
+    """Service for loading and managing agent configurations.
+
+    This service handles loading YAML configuration files, merging environment-specific
+    configurations, and parsing them into AigencyConfig objects.
+
+    Attributes:
+        config_file (str): Path to the main configuration file.
+        environment (str | None): Environment name for environment-specific configs.
+        config (AigencyConfig): Parsed configuration object.
+    """
+
     def __init__(self, config_file: str, environment: Optional[str] = None):
+        """Initialize the configuration service.
+
+        Args:
+            config_file (str): Path to the main configuration file.
+            environment (str, optional): Environment name for environment-specific
+                configs. Defaults to None.
+        """
         self.config_file = config_file
-        self.environment = environment or os.getenv('ENVIRONMENT', None)
+        self.environment = environment or os.getenv("ENVIRONMENT", None)
         self.config = self._load_and_parse()
 
-    def _load_and_parse(self) -> AgentConfig:
-        """Carga los YAMLs, los mergea y parsea según AgentConfig."""
+    def _load_and_parse(self) -> AigencyConfig:
+        """Load YAMLs, merge them and parse according to AigencyConfig.
+
+        Loads the main configuration file and optionally merges it with
+        environment-specific configuration if available.
+
+        Returns:
+            AigencyConfig: Parsed and validated configuration object.
+        """
 
         logger.info(f"Loading configuration from {self.config_file}")
         config = self._load_yaml(self.config_file)
 
         if self.environment is not None:
-            logger.info(f"Environment '{self.environment}' detected, loading environment-specific configuration")
+            logger.info(
+                f"Environment '{self.environment}' detected, loading environment-specific configuration"
+            )
             env_config = self._load_env_config()
             if env_config:
-                logger.info(f"Successfully loaded environment configuration with {len(env_config)} keys: {list(env_config.keys())}")
+                logger.info(
+                    f"Successfully loaded environment configuration with {len(env_config)} keys: {list(env_config.keys())}"
+                )
                 config = self._merge_configs(config, env_config)
-                logger.debug(f"Configuration merged successfully for environment '{self.environment}'")
+                logger.debug(
+                    f"Configuration merged successfully for environment '{self.environment}'"
+                )
             else:
-                logger.warning(f"No environment-specific configuration found for '{self.environment}', using base configuration only")
-        
-        return AgentConfig(**config)
+                logger.warning(
+                    f"No environment-specific configuration found for '{self.environment}', using base configuration only"
+                )
+
+        return AigencyConfig(**config)
 
     def _load_yaml(self, file_path: str) -> Dict[str, Any]:
-        """Carga un archivo YAML."""
+        """Load a YAML file.
+
+        Args:
+            file_path (str): Path to the YAML file to load.
+
+        Returns:
+            Dict[str, Any]: Parsed YAML content as dictionary.
+
+        Raises:
+            FileNotFoundError: If the configuration file is not found.
+            ValueError: If there's an error parsing the YAML file.
+        """
         try:
             with open(file_path, "r", encoding="utf-8") as file:
                 return yaml.safe_load(file) or {}
         except FileNotFoundError:
-            raise FileNotFoundError(f"Archivo de configuración no encontrado: {file_path}")
+            raise FileNotFoundError(f"Configuration file not found: {file_path}")
         except yaml.YAMLError as e:
-            raise ValueError(f"Error al parsear YAML {file_path}: {e}")
+            raise ValueError(f"Error parsing YAML {file_path}: {e}")
 
     def _load_env_config(self) -> Optional[Dict[str, Any]]:
-        """Carga configuración específica del entorno."""
+        """Load environment-specific configuration.
+
+        Attempts to load a configuration file with environment-specific naming
+        pattern (e.g., config.dev.yaml for 'dev' environment).
+
+        Returns:
+            Dict[str, Any] | None: Environment configuration dictionary or None
+                if no environment-specific file exists.
+        """
         config_path = Path(self.config_file)
-        env_file = config_path.parent / f"{config_path.stem}.{self.environment}{config_path.suffix}"
-        
+        env_file = (
+            config_path.parent
+            / f"{config_path.stem}.{self.environment}{config_path.suffix}"
+        )
+
         return self._load_yaml(str(env_file)) if env_file.exists() else None
 
-    def _merge_configs(self, base: Dict[str, Any], env: Optional[Dict[str, Any]]) -> Dict[str, Any]:
-        """Mergea configuración base con configuración de entorno."""
+    def _merge_configs(
+        self, base: Dict[str, Any], env: Optional[Dict[str, Any]]
+    ) -> Dict[str, Any]:
+        """Merge base configuration with environment configuration.
+
+        Recursively merges environment-specific configuration into the base
+        configuration, with environment values taking precedence.
+
+        Args:
+            base (Dict[str, Any]): Base configuration dictionary.
+            env (Dict[str, Any] | None): Environment-specific configuration
+                dictionary.
+
+        Returns:
+            Dict[str, Any]: Merged configuration dictionary.
+        """
         if not env:
             return base
-            
+
         result = base.copy()
         for key, value in env.items():
-            if key in result and isinstance(result[key], dict) and isinstance(value, dict):
+            if (
+                key in result
+                and isinstance(result[key], dict)
+                and isinstance(value, dict)
+            ):
                 result[key] = self._merge_configs(result[key], value)
             else:
                 result[key] = value
-        return result
+        return result

aigency/utils/logger.py

@@ -1,3 +1,24 @@
+"""Singleton logger implementation for consistent application-wide logging.
+
+This module provides a centralized logging system using the Singleton pattern to
+ensure consistent logging behavior across the entire Aigency application. It supports
+configurable log levels, multiple output handlers, and dynamic configuration updates.
+
+The Logger class extends the Singleton base class to guarantee only one logger
+instance exists throughout the application lifecycle, preventing configuration
+conflicts and ensuring unified log formatting and output destinations.
+
+Example:
+    Basic logger usage:
+
+    >>> logger = get_logger({"log_level": "DEBUG", "log_file": "app.log"})
+    >>> logger.info("Application started")
+    >>> logger.error("An error occurred", exc_info=True)
+
+Attributes:
+    None: This module contains only class definitions and utility functions.
+"""
+
 import logging
 import sys
 from typing import Optional, Dict, Any
@@ -5,97 +26,165 @@ from aigency.utils.singleton import Singleton
 
 
 class Logger(Singleton):
+    """Singleton logger class for consistent logging across the application.
+
+    This class provides a centralized logging mechanism that ensures only one
+    logger instance exists throughout the application lifecycle.
+
+    Attributes:
+        config (Dict[str, Any]): Configuration dictionary for logger settings.
+        _logger (logging.Logger): Internal logger instance.
+        _initialized (bool): Flag to track initialization state.
+    """
+
     def __init__(self, config: Optional[Dict[str, Any]] = None):
-        if hasattr(self, '_initialized'):
-            # Si ya está inicializado y se pasa nueva config, actualizar
-            if config and config != getattr(self, 'config', {}):
+        """Initialize the logger with optional configuration.
+
+        Args:
+            config (Dict[str, Any], optional): Dictionary containing logger
+                configuration. Defaults to None.
+        """
+        if hasattr(self, "_initialized"):
+            # If already initialized and new config is passed, update
+            if config and config != getattr(self, "config", {}):
                 self.config.update(config)
                 self._setup_logger()
             return
-        
+
         self._initialized = True
         self.config = config or {}
         self._logger = None
         self._setup_logger()
-    
+
     def _setup_logger(self):
-        """Configura el logger con la configuración proporcionada"""
-        # Obtener configuración del logger
-        log_level = self.config.get('log_level', 'INFO').upper()
-        log_format = self.config.get('log_format', '%(asctime)s - %(name)s - %(levelname)s - %(message)s')
-        log_file = self.config.get('log_file')
-        logger_name = self.config.get('logger_name', 'aigency')
-        
-        # Crear logger
+        """Configure the logger with the provided configuration.
+
+        Sets up the internal logger instance with handlers, formatters, and
+        log levels based on the configuration dictionary.
+        """
+        # Get logger configuration
+        log_level = self.config.get("log_level", "INFO").upper()
+        log_format = self.config.get(
+            "log_format", "%(asctime)s - %(name)s - %(levelname)s - %(message)s"
+        )
+        log_file = self.config.get("log_file")
+        logger_name = self.config.get("logger_name", "aigency")
+
+        # Create logger
         self._logger = logging.getLogger(logger_name)
         self._logger.setLevel(getattr(logging, log_level, logging.INFO))
-        
-        # Evitar duplicar handlers si ya existen
+
+        # Avoid duplicating handlers if they already exist
         if self._logger.handlers:
             return
-        
-        # Crear formatter
+
+        # Create formatter
         formatter = logging.Formatter(log_format)
-        
-        # Handler para consola
+
+        # Console handler
         console_handler = logging.StreamHandler(sys.stdout)
         console_handler.setLevel(getattr(logging, log_level, logging.INFO))
         console_handler.setFormatter(formatter)
         self._logger.addHandler(console_handler)
-        
-        # Handler para archivo si se especifica
+
+        # File handler if specified
         if log_file:
             file_handler = logging.FileHandler(log_file)
             file_handler.setLevel(getattr(logging, log_level, logging.INFO))
             file_handler.setFormatter(formatter)
             self._logger.addHandler(file_handler)
-    
+
     def debug(self, message: str, *args, **kwargs):
-        """Log a debug message"""
+        """Log a debug message.
+
+        Args:
+            message (str): The message to log.
+            *args: Variable length argument list.
+            **kwargs: Arbitrary keyword arguments.
+        """
         self._logger.debug(message, *args, **kwargs)
-    
+
     def info(self, message: str, *args, **kwargs):
-        """Log an info message"""
+        """Log an info message.
+
+        Args:
+            message (str): The message to log.
+            *args: Variable length argument list.
+            **kwargs: Arbitrary keyword arguments.
+        """
         self._logger.info(message, *args, **kwargs)
-    
+
     def warning(self, message: str, *args, **kwargs):
-        """Log a warning message"""
+        """Log a warning message.
+
+        Args:
+            message (str): The message to log.
+            *args: Variable length argument list.
+            **kwargs: Arbitrary keyword arguments.
+        """
         self._logger.warning(message, *args, **kwargs)
-    
+
     def error(self, message: str, *args, **kwargs):
-        """Log an error message"""
+        """Log an error message.
+
+        Args:
+            message (str): The message to log.
+            *args: Variable length argument list.
+            **kwargs: Arbitrary keyword arguments.
+        """
         self._logger.error(message, *args, **kwargs)
-    
+
     def critical(self, message: str, *args, **kwargs):
-        """Log a critical message"""
+        """Log a critical message.
+
+        Args:
+            message (str): The message to log.
+            *args: Variable length argument list.
+            **kwargs: Arbitrary keyword arguments.
+        """
         self._logger.critical(message, *args, **kwargs)
-    
+
     def exception(self, message: str, *args, **kwargs):
-        """Log an exception with traceback"""
+        """Log an exception with traceback.
+
+        Args:
+            message (str): The message to log.
+            *args: Variable length argument list.
+            **kwargs: Arbitrary keyword arguments.
+        """
         self._logger.exception(message, *args, **kwargs)
-    
+
     def set_level(self, level: str):
-        """Cambiar el nivel de logging dinámicamente"""
+        """Change the logging level dynamically.
+
+        Args:
+            level (str): The new logging level as a string.
+        """
         log_level = level.upper()
         self._logger.setLevel(getattr(logging, log_level, logging.INFO))
         for handler in self._logger.handlers:
             handler.setLevel(getattr(logging, log_level, logging.INFO))
-    
+
     def get_logger(self):
-        """Obtener la instancia del logger interno"""
+        """Get the internal logger instance.
+
+        Returns:
+            logging.Logger: The internal logging.Logger instance.
+        """
         return self._logger
 
 
-# Función de conveniencia para obtener la instancia del logger
+# Convenience function to get the logger instance
 def get_logger(config: Optional[Dict[str, Any]] = None) -> Logger:
-    """
-    Obtiene la instancia singleton del logger.
-    Si es la primera vez que se llama y se proporciona config, se usa esa configuración.
-    
+    """Get the singleton logger instance.
+
+    If this is the first call and config is provided, that configuration is used.
+
     Args:
-        config: Configuración opcional para el logger (solo se usa en la primera llamada)
-    
+        config (Dict[str, Any], optional): Optional configuration for the logger
+            (only used on first call). Defaults to None.
+
     Returns:
-        Instancia singleton del Logger
+        Logger: Singleton Logger instance.
     """
-    return Logger(config)
+    return Logger(config)

aigency/utils/singleton.py

@@ -1,7 +1,54 @@
+"""Singleton pattern implementation using metaclasses.
+
+This module provides a robust implementation of the Singleton design pattern using
+Python metaclasses. It ensures that classes inheriting from the Singleton base class
+can have only one instance throughout the application lifecycle, which is useful
+for shared resources like loggers, configuration managers, and database connections.
+
+The implementation uses a metaclass approach to control instance creation at the
+class level, providing thread-safe singleton behavior without requiring explicit
+synchronization in the client code.
+
+Example:
+    Creating singleton classes:
+
+    >>> class DatabaseManager(Singleton):
+    ...     def __init__(self):
+    ...         self.connection = "db_connection"
+    >>>
+    >>> db1 = DatabaseManager()
+    >>> db2 = DatabaseManager()
+    >>> db1 is db2
+    True
+
+Attributes:
+    None: This module contains only class definitions.
+"""
+
+
 class SingletonMeta(type):
+    """Metaclass that implements the Singleton pattern.
+
+    This metaclass ensures that only one instance of a class can exist.
+    When a class uses this metaclass, subsequent instantiation attempts
+    will return the same instance.
+
+    Attributes:
+        _instances (dict): Dictionary storing singleton instances by class.
+    """
+
     _instances = {}
 
     def __call__(cls, *args, **kwargs):
+        """Control instance creation to ensure singleton behavior.
+
+        Args:
+            *args: Variable length argument list for class instantiation.
+            **kwargs: Arbitrary keyword arguments for class instantiation.
+
+        Returns:
+            object: The singleton instance of the class.
+        """
         if cls not in cls._instances:
             instance = super().__call__(*args, **kwargs)
             cls._instances[cls] = instance
@@ -9,4 +56,18 @@ class SingletonMeta(type):
 
 
 class Singleton(metaclass=SingletonMeta):
-    pass
+    """Base class for implementing singleton pattern.
+
+    Classes that inherit from this base class will automatically
+    follow the singleton pattern, ensuring only one instance exists.
+
+    Example:
+        >>> class MyClass(Singleton):
+        ...     pass
+        >>> obj1 = MyClass()
+        >>> obj2 = MyClass()
+        >>> obj1 is obj2
+        True
+    """
+
+    pass

aigency/utils/utils.py

@@ -1,4 +1,23 @@
-"""Utility functions for type conversions and environment variable handling."""
+"""Utility functions for type conversions and environment variable handling.
+
+This module provides essential utility functions for the Aigency framework, including
+type conversions between A2A and Google GenAI formats, environment variable expansion,
+URL generation, and safe asynchronous execution helpers.
+
+The utilities handle common operations needed across the framework, such as converting
+message parts between different protocol formats, managing environment variables in
+configurations, and safely running coroutines in various asyncio contexts.
+
+Example:
+    Converting between A2A and GenAI formats:
+
+    >>> a2a_part = TextPart(text="Hello world")
+    >>> genai_part = convert_a2a_part_to_genai(a2a_part)
+    >>> back_to_a2a = convert_genai_part_to_a2a(genai_part)
+
+Attributes:
+    logger: Module-level logger instance for utility operations.
+"""
 
 import asyncio
 import os
@@ -11,6 +30,7 @@ from aigency.utils.logger import get_logger
 
 logger = get_logger()
 
+
 def convert_a2a_part_to_genai(part: Part) -> types.Part:
     """Convert a single A2A Part type into a Google Gen AI Part type.
 
@@ -54,10 +74,19 @@ def convert_genai_part_to_a2a(part: types.Part) -> Part:
         )
     raise ValueError(f"Unsupported part type: {part}")
 
+
 def expand_env_vars(env_dict):
-    """
-    Expande los valores del diccionario usando variables de entorno solo si el valor es una clave de entorno existente.
-    Si la variable no existe en el entorno, deja el valor literal.
+    """Expand dictionary values using environment variables.
+
+    Expands values in the dictionary using environment variables only if the value
+    is an existing environment variable key. If the variable doesn't exist in the
+    environment, leaves the literal value.
+
+    Args:
+        env_dict (dict): Dictionary with potential environment variable references.
+
+    Returns:
+        dict: Dictionary with expanded environment variable values.
     """
     result = {}
     for k, v in env_dict.items():
@@ -67,8 +96,36 @@ def expand_env_vars(env_dict):
             logger.warning(f"Environment variable {v} not found")
     return result
 
+
+def generate_url(host: str, port: int, path: str = "") -> str:
+    """Generate a URL from host, port, and path components.
+
+    Args:
+        host (str): Hostname or IP address.
+        port (int): Port number.
+        path (str, optional): URL path. Defaults to "".
+
+    Returns:
+        str: Complete URL in the format http://host:port/path.
+    """
+    return f"http://{host}:{port}{path}"
+
+
 def safe_async_run(coro):
-    """Simple wrapper to safely run async code."""
+    """Simple wrapper to safely run async code.
+
+    This function handles different asyncio event loop scenarios to safely
+    execute coroutines, including cases where a loop is already running.
+
+    Args:
+        coro: The coroutine to execute.
+
+    Returns:
+        Any: The result of the coroutine execution.
+
+    Raises:
+        Exception: Any exception raised by the coroutine.
+    """
     try:
         loop = asyncio.get_event_loop()
         if loop.is_running():
@@ -93,4 +150,4 @@ def safe_async_run(coro):
         else:
             return loop.run_until_complete(coro)
     except RuntimeError:
-        return asyncio.run(coro)
+        return asyncio.run(coro)