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

aiecs/llm/config/config_validator.py

@@ -0,0 +1,206 @@
+"""
+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
+    from pathlib import Path
+
+    loader = LLMConfigLoader()
+    config_path_obj: Path | None = Path(config_path) if config_path else None
+    config = loader.load_config(config_path_obj)
+
+    return validate_llm_config(config)

aiecs/llm/config/model_config.py

@@ -0,0 +1,143 @@
+"""
+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/protocols.py

@@ -0,0 +1,149 @@
+"""
+LLM Client Protocols
+
+Defines Protocol interfaces for LLM clients to enable duck typing and flexible integration.
+"""
+
+from typing import Protocol, List, Optional, AsyncGenerator, runtime_checkable
+from aiecs.llm.clients.base_client import LLMMessage, LLMResponse
+
+
+@runtime_checkable
+class LLMClientProtocol(Protocol):
+    """
+    Protocol for LLM clients.
+
+    This protocol defines the interface that any LLM client must implement
+    to be compatible with AIECS agents. It uses duck typing (Protocol) rather
+    than inheritance, allowing custom LLM clients to work without inheriting
+    from BaseLLMClient.
+
+    Example:
+        ```python
+        # Custom LLM client that implements the protocol
+        class CustomLLMClient:
+            def __init__(self):
+                self.provider_name = "custom"
+
+            async def generate_text(
+                self,
+                messages: List[LLMMessage],
+                model: Optional[str] = None,
+                temperature: float = 0.7,
+                max_tokens: Optional[int] = None,
+                **kwargs
+            ) -> LLMResponse:
+                # Custom implementation
+                pass
+
+            async def stream_text(
+                self,
+                messages: List[LLMMessage],
+                model: Optional[str] = None,
+                temperature: float = 0.7,
+                max_tokens: Optional[int] = None,
+                **kwargs
+            ) -> AsyncGenerator[str, None]:
+                # Custom implementation
+                yield "token"
+
+            async def close(self):
+                # Cleanup
+                pass
+
+        # Use with agents
+        agent = HybridAgent(
+            llm_client=CustomLLMClient(),  # Works without BaseLLMClient inheritance!
+            ...
+        )
+        ```
+    """
+
+    provider_name: str
+
+    async def generate_text(
+        self,
+        messages: List[LLMMessage],
+        model: Optional[str] = None,
+        temperature: float = 0.7,
+        max_tokens: Optional[int] = None,
+        **kwargs,
+    ) -> LLMResponse:
+        """
+        Generate text using the LLM provider's API.
+
+        Args:
+            messages: List of conversation messages
+            model: Model name (optional, uses default if not provided)
+            temperature: Sampling temperature (0.0 to 1.0)
+            max_tokens: Maximum tokens to generate
+            **kwargs: Additional provider-specific parameters
+
+        Returns:
+            LLMResponse with generated text and metadata
+        """
+        ...
+
+    async def stream_text(
+        self,
+        messages: List[LLMMessage],
+        model: Optional[str] = None,
+        temperature: float = 0.7,
+        max_tokens: Optional[int] = None,
+        **kwargs,
+    ) -> AsyncGenerator[str, None]:
+        """
+        Stream text generation using the LLM provider's API.
+
+        Args:
+            messages: List of conversation messages
+            model: Model name (optional, uses default if not provided)
+            temperature: Sampling temperature (0.0 to 1.0)
+            max_tokens: Maximum tokens to generate
+            **kwargs: Additional provider-specific parameters
+
+        Yields:
+            Text tokens as they are generated
+        """
+        ...
+
+    async def close(self):
+        """
+        Clean up resources (connections, sessions, etc.).
+
+        This method should be called when the client is no longer needed.
+        """
+        ...
+
+    async def get_embeddings(
+        self,
+        texts: List[str],
+        model: Optional[str] = None,
+        **kwargs,
+    ) -> List[List[float]]:
+        """
+        Get embeddings for a list of texts.
+
+        This method is used for semantic compression and similarity analysis.
+        Implementations should return normalized embeddings for cosine similarity.
+
+        Args:
+            texts: List of texts to embed
+            model: Embedding model name (optional, uses default if not provided)
+            **kwargs: Additional provider-specific parameters
+
+        Returns:
+            List of embedding vectors (one per input text)
+
+        Example:
+            ```python
+            texts = ["Hello world", "Goodbye world"]
+            embeddings = await llm_client.get_embeddings(texts)
+            # embeddings = [[0.1, 0.2, ...], [0.15, 0.25, ...]]
+            ```
+
+        Note:
+            Not all LLM clients support embeddings. If not supported,
+            this method should raise NotImplementedError.
+        """
+        ...

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__ = []

aiecs/llm/utils/validate_config.py

@@ -0,0 +1,89 @@
+#!/usr/bin/env python3
+"""
+Validation script for LLM models configuration.
+
+This script validates the LLM models configuration file and prints
+information about configured providers and models.
+"""
+
+import sys
+import logging
+
+# Setup logging
+logging.basicConfig(
+    level=logging.INFO,
+    format="%(asctime)s - %(name)s - %(levelname)s - %(message)s",
+)
+logger = logging.getLogger(__name__)
+
+
+def main():
+    """Main validation function"""
+    try:
+        from aiecs.llm.config import get_llm_config_loader, validate_llm_config
+
+        logger.info("=" * 70)
+        logger.info("LLM Models Configuration Validator")
+        logger.info("=" * 70)
+
+        # Load configuration
+        loader = get_llm_config_loader()
+        config = loader.get_config()
+
+        logger.info(f"\nConfiguration loaded from: {loader.get_config_path()}")
+
+        # Validate configuration
+        logger.info("\nValidating configuration...")
+        is_valid, warnings = validate_llm_config(config)
+
+        if is_valid:
+            logger.info("✓ Configuration is valid!")
+
+        # Print summary
+        logger.info("\n" + "=" * 70)
+        logger.info("Configuration Summary")
+        logger.info("=" * 70)
+
+        logger.info(f"\nTotal Providers: {len(config.providers)}")
+
+        for provider_name, provider_config in config.providers.items():
+            logger.info(f"\n{provider_name}:")
+            logger.info(f"  Default Model: {provider_config.default_model}")
+            logger.info(f"  Total Models: {len(provider_config.models)}")
+
+            if provider_config.model_mappings:
+                logger.info(f"  Model Aliases: {len(provider_config.model_mappings)}")
+
+            logger.info("  Available Models:")
+            for model in provider_config.models:
+                cost_str = f"${model.costs.input:.6f} in / ${model.costs.output:.6f} out (per 1K tokens)"
+                logger.info(f"    - {model.name}: {cost_str}")
+                if model.capabilities.vision:
+                    logger.info("        Vision: Yes")
+                if model.capabilities.function_calling:
+                    logger.info("        Function Calling: Yes")
+
+        logger.info("\n" + "=" * 70)
+        logger.info("Validation Complete!")
+        logger.info("=" * 70)
+
+        if warnings:
+            logger.info(f"\nNote: {len(warnings)} warnings were generated during validation.")
+            logger.info("See logs above for details.")
+
+        return 0
+
+    except FileNotFoundError as e:
+        logger.error(f"\n✗ Configuration file not found: {e}")
+        logger.error("\nPlease ensure the LLM models configuration file exists at:")
+        logger.error("  - aiecs/config/llm_models.yaml")
+        logger.error("  - Or set LLM_MODELS_CONFIG environment variable")
+        return 1
+
+    except Exception as e:
+        logger.error(f"\n✗ Validation failed: {e}", exc_info=True)
+        return 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())