aiecs 1.5.1__py3-none-any.whl

aiecs/llm/config/config_loader.py

@@ -0,0 +1,275 @@
+"""
+Configuration loader for LLM models.
+
+This module provides a singleton configuration loader that loads and manages
+LLM model configurations from YAML files with support for hot-reloading.
+"""
+
+import logging
+import os
+from pathlib import Path
+from typing import Optional
+import yaml
+from threading import Lock
+
+from aiecs.llm.config.model_config import (
+    LLMModelsConfig,
+    ProviderConfig,
+    ModelConfig,
+)
+
+logger = logging.getLogger(__name__)
+
+
+class LLMConfigLoader:
+    """
+    Singleton configuration loader for LLM models.
+
+    Supports:
+    - Loading configuration from YAML files
+    - Hot-reloading (manual refresh)
+    - Thread-safe access
+    - Caching for performance
+    """
+
+    _instance: Optional["LLMConfigLoader"] = None
+    _lock = Lock()
+    _config_lock = Lock()
+
+    def __new__(cls):
+        """Ensure singleton instance"""
+        if cls._instance is None:
+            with cls._lock:
+                if cls._instance is None:
+                    cls._instance = super().__new__(cls)
+                    cls._instance._initialized = False
+        return cls._instance
+
+    def __init__(self):
+        """Initialize the configuration loader"""
+        if self._initialized:
+            return
+
+        self._config: Optional[LLMModelsConfig] = None
+        self._config_path: Optional[Path] = None
+        self._initialized = True
+        logger.info("LLMConfigLoader initialized")
+
+    def _find_config_file(self) -> Path:
+        """
+        Find the configuration file.
+
+        Search order:
+        1. Settings llm_models_config_path
+        2. Environment variable LLM_MODELS_CONFIG
+        3. aiecs/config/llm_models.yaml
+        4. config/llm_models.yaml
+        """
+        # Check settings first
+        try:
+            from aiecs.config.config import get_settings
+
+            settings = get_settings()
+            if settings.llm_models_config_path:
+                path = Path(settings.llm_models_config_path)
+                if path.exists():
+                    logger.info(f"Using LLM config from settings: {path}")
+                    return path
+                else:
+                    logger.warning(f"Settings llm_models_config_path does not exist: {path}")
+        except Exception as e:
+            logger.debug(f"Could not load settings: {e}")
+
+        # Check environment variable
+        env_path = os.environ.get("LLM_MODELS_CONFIG")
+        if env_path:
+            path = Path(env_path)
+            if path.exists():
+                logger.info(f"Using LLM config from environment: {path}")
+                return path
+            else:
+                logger.warning(f"LLM_MODELS_CONFIG path does not exist: {path}")
+
+        # Check standard locations
+        current_dir = Path(__file__).parent.parent  # aiecs/
+
+        # Try aiecs/config/llm_models.yaml
+        config_path1 = current_dir / "config" / "llm_models.yaml"
+        if config_path1.exists():
+            logger.info(f"Using LLM config from: {config_path1}")
+            return config_path1
+
+        # Try config/llm_models.yaml (relative to project root)
+        config_path2 = current_dir.parent / "config" / "llm_models.yaml"
+        if config_path2.exists():
+            logger.info(f"Using LLM config from: {config_path2}")
+            return config_path2
+
+        # Default to the first path even if it doesn't exist
+        logger.warning(f"LLM config file not found, using default path: {config_path1}")
+        return config_path1
+
+    def load_config(self, config_path: Optional[Path] = None) -> LLMModelsConfig:
+        """
+        Load configuration from YAML file.
+
+        Args:
+            config_path: Optional path to configuration file. If not provided,
+                        will search in standard locations.
+
+        Returns:
+            LLMModelsConfig: Loaded and validated configuration
+
+        Raises:
+            FileNotFoundError: If config file doesn't exist
+            ValueError: If config file is invalid
+        """
+        with self._config_lock:
+            if config_path is None:
+                config_path = self._find_config_file()
+            else:
+                config_path = Path(config_path)
+
+            if not config_path.exists():
+                raise FileNotFoundError(
+                    f"LLM models configuration file not found: {config_path}\n"
+                    f"Please create the configuration file or set LLM_MODELS_CONFIG environment variable."
+                )
+
+            try:
+                with open(config_path, "r", encoding="utf-8") as f:
+                    config_data = yaml.safe_load(f)
+
+                if not config_data:
+                    raise ValueError("Configuration file is empty")
+
+                # Validate and parse using Pydantic
+                self._config = LLMModelsConfig(**config_data)
+                self._config_path = config_path
+
+                logger.info(
+                    f"Loaded LLM configuration from {config_path}: "
+                    f"{len(self._config.providers)} providers, "
+                    f"{sum(len(p.models) for p in self._config.providers.values())} models"
+                )
+
+                return self._config
+
+            except yaml.YAMLError as e:
+                raise ValueError(f"Invalid YAML in configuration file: {e}")
+            except Exception as e:
+                raise ValueError(f"Failed to load configuration: {e}")
+
+    def reload_config(self) -> LLMModelsConfig:
+        """
+        Reload configuration from the current config file.
+
+        This supports the hybrid loading mode - configuration is loaded at startup
+        but can be manually refreshed without restarting the application.
+
+        Returns:
+            LLMModelsConfig: Reloaded configuration
+        """
+        logger.info("Reloading LLM configuration...")
+        return self.load_config(self._config_path)
+
+    def get_config(self) -> LLMModelsConfig:
+        """
+        Get the current configuration.
+
+        Loads configuration on first access if not already loaded.
+
+        Returns:
+            LLMModelsConfig: Current configuration
+        """
+        if self._config is None:
+            self.load_config()
+        return self._config
+
+    def get_provider_config(self, provider_name: str) -> Optional[ProviderConfig]:
+        """
+        Get configuration for a specific provider.
+
+        Args:
+            provider_name: Name of the provider (e.g., "Vertex", "OpenAI")
+
+        Returns:
+            ProviderConfig if found, None otherwise
+        """
+        config = self.get_config()
+        return config.get_provider_config(provider_name)
+
+    def get_model_config(self, provider_name: str, model_name: str) -> Optional[ModelConfig]:
+        """
+        Get configuration for a specific model.
+
+        Args:
+            provider_name: Name of the provider
+            model_name: Name of the model (or alias)
+
+        Returns:
+            ModelConfig if found, None otherwise
+        """
+        config = self.get_config()
+        return config.get_model_config(provider_name, model_name)
+
+    def get_default_model(self, provider_name: str) -> Optional[str]:
+        """
+        Get the default model name for a provider.
+
+        Args:
+            provider_name: Name of the provider
+
+        Returns:
+            Default model name if found, None otherwise
+        """
+        provider_config = self.get_provider_config(provider_name)
+        if provider_config:
+            return provider_config.default_model
+        return None
+
+    def is_loaded(self) -> bool:
+        """Check if configuration has been loaded"""
+        return self._config is not None
+
+    def get_config_path(self) -> Optional[Path]:
+        """Get the path to the current configuration file"""
+        return self._config_path
+
+
+# Global singleton instance
+_loader = LLMConfigLoader()
+
+
+def get_llm_config_loader() -> LLMConfigLoader:
+    """
+    Get the global LLM configuration loader instance.
+
+    Returns:
+        LLMConfigLoader: Global singleton instance
+    """
+    return _loader
+
+
+def get_llm_config() -> LLMModelsConfig:
+    """
+    Get the current LLM configuration.
+
+    Convenience function that returns the configuration from the global loader.
+
+    Returns:
+        LLMModelsConfig: Current configuration
+    """
+    return _loader.get_config()
+
+
+def reload_llm_config() -> LLMModelsConfig:
+    """
+    Reload the LLM configuration.
+
+    Convenience function that reloads the configuration in the global loader.
+
+    Returns:
+        LLMModelsConfig: Reloaded configuration
+    """
+    return _loader.reload_config()

aiecs/llm/config/config_validator.py

@@ -0,0 +1,236 @@
+"""
+Configuration validation utilities for LLM models.
+
+This module provides validation functions to ensure configuration integrity
+and provide helpful error messages.
+"""
+
+import logging
+from typing import List, Tuple
+
+from aiecs.llm.config.model_config import (
+    LLMModelsConfig,
+    ProviderConfig,
+    ModelConfig,
+    ModelCostConfig,
+)
+
+logger = logging.getLogger(__name__)
+
+
+class ConfigValidationError(Exception):
+    """Raised when configuration validation fails"""
+
+
+def validate_cost_config(cost_config: ModelCostConfig, model_name: str) -> List[str]:
+    """
+    Validate cost configuration.
+
+    Args:
+        cost_config: Cost configuration to validate
+        model_name: Name of the model (for error messages)
+
+    Returns:
+        List of warning messages (empty if valid)
+    """
+    warnings = []
+
+    if cost_config.input < 0:
+        raise ConfigValidationError(
+            f"Model '{model_name}': Input cost must be non-negative, got {cost_config.input}"
+        )
+
+    if cost_config.output < 0:
+        raise ConfigValidationError(
+            f"Model '{model_name}': Output cost must be non-negative, got {cost_config.output}"
+        )
+
+    # Warn if costs are zero (might be intentional for free tiers or unknown
+    # pricing)
+    if cost_config.input == 0 and cost_config.output == 0:
+        warnings.append(f"Model '{model_name}': Both input and output costs are 0")
+
+    return warnings
+
+
+def validate_model_config(model_config: ModelConfig) -> List[str]:
+    """
+    Validate a single model configuration.
+
+    Args:
+        model_config: Model configuration to validate
+
+    Returns:
+        List of warning messages (empty if valid)
+
+    Raises:
+        ConfigValidationError: If validation fails
+    """
+    warnings = []
+
+    # Validate name
+    if not model_config.name or not model_config.name.strip():
+        raise ConfigValidationError("Model name cannot be empty")
+
+    # Validate costs
+    cost_warnings = validate_cost_config(model_config.costs, model_config.name)
+    warnings.extend(cost_warnings)
+
+    # Validate capabilities
+    if model_config.capabilities.max_tokens <= 0:
+        raise ConfigValidationError(
+            f"Model '{model_config.name}': max_tokens must be positive, "
+            f"got {model_config.capabilities.max_tokens}"
+        )
+
+    if model_config.capabilities.context_window <= 0:
+        raise ConfigValidationError(
+            f"Model '{model_config.name}': context_window must be positive, "
+            f"got {model_config.capabilities.context_window}"
+        )
+
+    # Validate default params
+    if not (0.0 <= model_config.default_params.temperature <= 2.0):
+        raise ConfigValidationError(
+            f"Model '{model_config.name}': temperature must be between 0.0 and 2.0, "
+            f"got {model_config.default_params.temperature}"
+        )
+
+    if model_config.default_params.max_tokens <= 0:
+        raise ConfigValidationError(
+            f"Model '{model_config.name}': default max_tokens must be positive, "
+            f"got {model_config.default_params.max_tokens}"
+        )
+
+    # Warn if default max_tokens exceeds capability max_tokens
+    if model_config.default_params.max_tokens > model_config.capabilities.max_tokens:
+        warnings.append(
+            f"Model '{model_config.name}': default max_tokens ({model_config.default_params.max_tokens}) "
+            f"exceeds capability max_tokens ({model_config.capabilities.max_tokens})"
+        )
+
+    return warnings
+
+
+def validate_provider_config(provider_config: ProviderConfig) -> List[str]:
+    """
+    Validate a provider configuration.
+
+    Args:
+        provider_config: Provider configuration to validate
+
+    Returns:
+        List of warning messages (empty if valid)
+
+    Raises:
+        ConfigValidationError: If validation fails
+    """
+    warnings = []
+
+    # Validate provider name
+    if not provider_config.provider_name or not provider_config.provider_name.strip():
+        raise ConfigValidationError("Provider name cannot be empty")
+
+    # Validate models list
+    if not provider_config.models:
+        raise ConfigValidationError(
+            f"Provider '{provider_config.provider_name}': Must have at least one model"
+        )
+
+    # Validate default model exists
+    model_names = provider_config.get_model_names()
+    if provider_config.default_model not in model_names:
+        raise ConfigValidationError(
+            f"Provider '{provider_config.provider_name}': Default model '{provider_config.default_model}' "
+            f"not found in models list: {model_names}"
+        )
+
+    # Validate each model
+    for model in provider_config.models:
+        model_warnings = validate_model_config(model)
+        warnings.extend(model_warnings)
+
+    # Check for duplicate model names
+    if len(model_names) != len(set(model_names)):
+        duplicates = [name for name in model_names if model_names.count(name) > 1]
+        raise ConfigValidationError(
+            f"Provider '{provider_config.provider_name}': Duplicate model names found: {set(duplicates)}"
+        )
+
+    # Validate model mappings if present
+    if provider_config.model_mappings:
+        for alias, target in provider_config.model_mappings.items():
+            if target not in model_names:
+                raise ConfigValidationError(
+                    f"Provider '{provider_config.provider_name}': Model mapping alias '{alias}' "
+                    f"points to non-existent model '{target}'. Available models: {model_names}"
+                )
+
+            # Warn if alias is the same as target
+            if alias == target:
+                warnings.append(
+                    f"Provider '{provider_config.provider_name}': Model mapping has redundant entry "
+                    f"'{alias}' -> '{target}'"
+                )
+
+    return warnings
+
+
+def validate_llm_config(config: LLMModelsConfig) -> Tuple[bool, List[str]]:
+    """
+    Validate the entire LLM configuration.
+
+    Args:
+        config: Complete LLM configuration to validate
+
+    Returns:
+        Tuple of (is_valid, warnings_list)
+
+    Raises:
+        ConfigValidationError: If validation fails critically
+    """
+    warnings = []
+
+    # Validate providers exist
+    if not config.providers:
+        raise ConfigValidationError("Configuration must have at least one provider")
+
+    # Validate each provider
+    for provider_name, provider_config in config.providers.items():
+        try:
+            provider_warnings = validate_provider_config(provider_config)
+            warnings.extend(provider_warnings)
+        except ConfigValidationError as e:
+            raise ConfigValidationError(f"Provider '{provider_name}': {e}")
+
+    # Log warnings
+    if warnings:
+        logger.warning(f"Configuration validation completed with {len(warnings)} warnings:")
+        for warning in warnings:
+            logger.warning(f"  - {warning}")
+    else:
+        logger.info("Configuration validation completed successfully with no warnings")
+
+    return True, warnings
+
+
+def validate_config_file(config_path: str) -> Tuple[bool, List[str]]:
+    """
+    Validate a configuration file.
+
+    Args:
+        config_path: Path to the configuration file
+
+    Returns:
+        Tuple of (is_valid, warnings_list)
+
+    Raises:
+        ConfigValidationError: If validation fails
+        FileNotFoundError: If file doesn't exist
+    """
+    from aiecs.llm.config.config_loader import LLMConfigLoader
+
+    loader = LLMConfigLoader()
+    config = loader.load_config(config_path)
+
+    return validate_llm_config(config)

aiecs/llm/config/model_config.py

@@ -0,0 +1,151 @@
+"""
+Pydantic models for LLM configuration management.
+
+This module defines the configuration schema for all LLM providers and models,
+enabling centralized, type-safe configuration management.
+"""
+
+from typing import Dict, Optional, List
+from pydantic import BaseModel, Field, field_validator
+
+
+class ModelCostConfig(BaseModel):
+    """Token cost configuration for a model"""
+
+    input: float = Field(ge=0, description="Cost per 1K input tokens in USD")
+    output: float = Field(ge=0, description="Cost per 1K output tokens in USD")
+
+    @field_validator("input", "output")
+    @classmethod
+    def validate_positive(cls, v: float) -> float:
+        """Ensure costs are non-negative"""
+        if v < 0:
+            raise ValueError("Cost must be non-negative")
+        return v
+
+
+class ModelCapabilities(BaseModel):
+    """Capabilities and limits for a model"""
+
+    streaming: bool = Field(default=True, description="Whether the model supports streaming")
+    vision: bool = Field(
+        default=False,
+        description="Whether the model supports vision/image input",
+    )
+    function_calling: bool = Field(
+        default=False,
+        description="Whether the model supports function calling",
+    )
+    max_tokens: int = Field(default=8192, ge=1, description="Maximum output tokens")
+    context_window: int = Field(default=128000, ge=1, description="Maximum context window size")
+
+
+class ModelDefaultParams(BaseModel):
+    """Default parameters for model inference"""
+
+    temperature: float = Field(default=0.7, ge=0.0, le=2.0, description="Default temperature")
+    max_tokens: int = Field(default=8192, ge=1, description="Default max output tokens")
+    top_p: float = Field(default=0.95, ge=0.0, le=1.0, description="Default top_p")
+    top_k: int = Field(default=40, ge=0, description="Default top_k")
+
+
+class ModelConfig(BaseModel):
+    """Complete configuration for a single model"""
+
+    name: str = Field(description="Model identifier")
+    display_name: Optional[str] = Field(default=None, description="Human-readable model name")
+    costs: ModelCostConfig = Field(description="Token cost configuration")
+    capabilities: ModelCapabilities = Field(
+        default_factory=ModelCapabilities, description="Model capabilities"
+    )
+    default_params: ModelDefaultParams = Field(
+        default_factory=ModelDefaultParams, description="Default parameters"
+    )
+    description: Optional[str] = Field(default=None, description="Model description")
+
+    def __init__(self, **data):
+        super().__init__(**data)
+        # Set display_name to name if not provided
+        if self.display_name is None:
+            self.display_name = self.name
+
+
+class ProviderConfig(BaseModel):
+    """Configuration for a single LLM provider"""
+
+    provider_name: str = Field(description="Provider identifier")
+    default_model: str = Field(description="Default model for this provider")
+    models: List[ModelConfig] = Field(description="List of available models")
+    model_mappings: Optional[Dict[str, str]] = Field(
+        default=None,
+        description="Model name aliases (e.g., 'Grok 4' -> 'grok-4')",
+    )
+
+    @field_validator("models")
+    @classmethod
+    def validate_models_not_empty(cls, v: List[ModelConfig]) -> List[ModelConfig]:
+        """Ensure at least one model is configured"""
+        if not v:
+            raise ValueError("Provider must have at least one model configured")
+        return v
+
+    def get_model_config(self, model_name: str) -> Optional[ModelConfig]:
+        """Get configuration for a specific model"""
+        # First, check if this is an alias
+        if self.model_mappings and model_name in self.model_mappings:
+            model_name = self.model_mappings[model_name]
+
+        # Find the model configuration
+        for model in self.models:
+            if model.name == model_name:
+                return model
+        return None
+
+    def get_model_names(self) -> List[str]:
+        """Get list of all model names"""
+        return [model.name for model in self.models]
+
+    def get_all_model_names_with_aliases(self) -> List[str]:
+        """Get list of all model names including aliases"""
+        names = self.get_model_names()
+        if self.model_mappings:
+            names.extend(list(self.model_mappings.keys()))
+        return names
+
+
+class LLMModelsConfig(BaseModel):
+    """Root configuration containing all providers"""
+
+    providers: Dict[str, ProviderConfig] = Field(
+        description="Provider configurations keyed by provider name"
+    )
+
+    @field_validator("providers")
+    @classmethod
+    def validate_providers_not_empty(
+        cls, v: Dict[str, ProviderConfig]
+    ) -> Dict[str, ProviderConfig]:
+        """Ensure at least one provider is configured"""
+        if not v:
+            raise ValueError("At least one provider must be configured")
+        return v
+
+    def get_provider_config(self, provider_name: str) -> Optional[ProviderConfig]:
+        """Get configuration for a specific provider"""
+        # Normalize provider name (case-insensitive lookup)
+        provider_name_lower = provider_name.lower()
+        for key, config in self.providers.items():
+            if key.lower() == provider_name_lower:
+                return config
+        return None
+
+    def get_model_config(self, provider_name: str, model_name: str) -> Optional[ModelConfig]:
+        """Get configuration for a specific model from a provider"""
+        provider_config = self.get_provider_config(provider_name)
+        if provider_config:
+            return provider_config.get_model_config(model_name)
+        return None
+
+    def get_provider_names(self) -> List[str]:
+        """Get list of all provider names"""
+        return list(self.providers.keys())

aiecs/llm/utils/__init__.py

@@ -0,0 +1,10 @@
+"""
+LLM Utilities.
+
+This package contains utility functions and scripts for LLM operations.
+"""
+
+# Validation script is executable and doesn't need to be imported
+# It can be run as: python -m aiecs.llm.utils.validate_config
+
+__all__ = []