django-cfg 1.3.5__py3-none-any.whl → 1.3.9__py3-none-any.whl

django_cfg/modules/django_app_agent/agents/base/agent.py

@@ -0,0 +1,354 @@
+"""
+Base Django Agent class with Pydantic AI integration.
+
+This module provides the foundational DjangoAgent class that all
+specialized agents inherit from, with proper django-cfg integration.
+"""
+
+from typing import TypeVar, Generic, Optional, Dict, Any, List, Type, Union
+from abc import ABC, abstractmethod
+import asyncio
+import uuid
+from contextlib import asynccontextmanager
+
+from pydantic_ai import Agent, RunContext
+from pydantic_ai.models import Model, KnownModelName
+
+from ...core.config import AgentConfig, ModelConfig, AIProvider, DEFAULT_MODELS
+from ...core.exceptions import (
+    AgentExecutionError, 
+    AuthenticationError, 
+    RateLimitError,
+    TimeoutError as AgentTimeoutError
+)
+from ...utils.logging import log_agent_operation, StructuredLogger
+from .context import AgentDependencies, AgentContext
+
+# Type variables for generic agent
+OutputT = TypeVar('OutputT')
+DepsT = TypeVar('DepsT', bound=AgentDependencies)
+
+
+class DjangoAgent(Generic[DepsT, OutputT], ABC):
+    """Base class for all Django App Agent AI agents.
+    
+    This class provides:
+    - Integration with django-cfg configuration
+    - Pydantic AI agent management
+    - Error handling and retry logic
+    - Logging and monitoring
+    - Context management
+    """
+    
+    def __init__(
+        self,
+        agent_name: str,
+        config: AgentConfig,
+        output_type: Type[OutputT] = str,
+        deps_type: Type[DepsT] = AgentDependencies,
+        model_override: Optional[str] = None,
+        **agent_kwargs: Any
+    ):
+        """Initialize Django Agent.
+        
+        Args:
+            agent_name: Name of the agent for logging and identification
+            config: Agent configuration from django-cfg
+            output_type: Expected output type from the agent
+            deps_type: Dependencies type for dependency injection
+            model_override: Optional model override for testing
+            **agent_kwargs: Additional arguments for Pydantic AI Agent
+        """
+        self.agent_name = agent_name
+        self.config = config
+        self.output_type = output_type
+        self.deps_type = deps_type
+        
+        # Get logger for this agent
+        self.logger = StructuredLogger(f"agents.{agent_name}")
+        
+        # Determine model to use
+        model_config = self._get_model_config(model_override)
+        
+        # Create Pydantic AI agent
+        self._agent = Agent[DepsT, OutputT](
+            model=model_config.provider.value + ":" + model_config.model_id,
+            output_type=output_type,
+            deps_type=deps_type,
+            name=agent_name,
+            retries=3,  # Default retries
+            **agent_kwargs
+        )
+        
+        # Register base instructions
+        self._register_instructions()
+        
+        # Register tools
+        self._register_tools()
+    
+    def _get_model_config(self, model_override: Optional[str] = None) -> ModelConfig:
+        """Get model configuration for this agent."""
+        if model_override:
+            # Parse model override (e.g., "openai:gpt-4")
+            if ":" in model_override:
+                provider_str, model_id = model_override.split(":", 1)
+                provider = AIProvider(provider_str)
+            else:
+                # Default to OpenRouter
+                provider = AIProvider.OPENROUTER
+                model_id = model_override
+            
+            return ModelConfig(
+                provider=provider,
+                model_id=model_id,
+                tier="balanced",
+                max_tokens=100000,
+                temperature=0.1,
+                timeout_seconds=300.0
+            )
+        
+        # Get model config for this agent type
+        model_config = self.config.get_model_config(self.agent_name)
+        if model_config:
+            return model_config
+        
+        # Fall back to default model
+        default_key = "generation"  # Default task type
+        if default_key in DEFAULT_MODELS:
+            return DEFAULT_MODELS[default_key]
+        
+        # Ultimate fallback
+        return ModelConfig(
+            provider=AIProvider.OPENROUTER,
+            model_id="anthropic/claude-3-haiku",
+            tier="balanced",
+            max_tokens=50000,
+            temperature=0.1,
+            timeout_seconds=180.0
+        )
+    
+    @abstractmethod
+    def _register_instructions(self) -> None:
+        """Register agent instructions. Must be implemented by subclasses."""
+        pass
+    
+    @abstractmethod
+    def _register_tools(self) -> None:
+        """Register agent tools. Must be implemented by subclasses."""
+        pass
+    
+    @log_agent_operation("base_agent", "run")
+    async def run(
+        self,
+        prompt: str,
+        deps: DepsT,
+        context: Optional[AgentContext] = None,
+        **run_kwargs: Any
+    ) -> OutputT:
+        """Run the agent with the given prompt and dependencies.
+        
+        Args:
+            prompt: Input prompt for the agent
+            deps: Dependencies for the agent execution
+            context: Optional execution context
+            **run_kwargs: Additional arguments for agent.run()
+            
+        Returns:
+            Agent output of type OutputT
+            
+        Raises:
+            AgentExecutionError: If agent execution fails
+            AuthenticationError: If API authentication fails
+            RateLimitError: If rate limits are exceeded
+            AgentTimeoutError: If execution times out
+        """
+        if context:
+            context.update_progress(f"{self.agent_name}_execution", 0.0)
+        
+        try:
+            # Validate API key
+            model_config = self._get_model_config()
+            if not self.config.has_api_key(model_config.provider):
+                raise AuthenticationError(
+                    f"No API key configured for {model_config.provider}",
+                    provider=model_config.provider.value
+                )
+            
+            deps.log_operation(f"Starting {self.agent_name} execution", prompt_length=len(prompt))
+            
+            # Run the agent with timeout
+            result = await asyncio.wait_for(
+                self._agent.run(prompt, deps=deps, **run_kwargs),
+                timeout=model_config.timeout_seconds
+            )
+            
+            if context:
+                context.add_result({
+                    "agent": self.agent_name,
+                    "output_type": self.output_type.__name__,
+                    "success": True
+                })
+                context.update_progress(f"{self.agent_name}_completed", 100.0)
+            
+            deps.log_operation(f"Completed {self.agent_name} execution successfully")
+            
+            return result.output
+            
+        except asyncio.TimeoutError as e:
+            error_msg = f"Agent {self.agent_name} execution timed out"
+            deps.log_error(error_msg, e)
+            if context:
+                context.add_error(error_msg)
+            raise AgentTimeoutError(
+                error_msg,
+                operation=f"{self.agent_name}_execution",
+                timeout_seconds=model_config.timeout_seconds
+            )
+            
+        except Exception as e:
+            error_msg = f"Agent {self.agent_name} execution failed: {e}"
+            deps.log_error(error_msg, e)
+            if context:
+                context.add_error(error_msg)
+            
+            # Map specific exceptions
+            if "authentication" in str(e).lower() or "api key" in str(e).lower():
+                raise AuthenticationError(
+                    error_msg,
+                    provider=model_config.provider.value,
+                    cause=e
+                )
+            elif "rate limit" in str(e).lower():
+                raise RateLimitError(
+                    error_msg,
+                    provider=model_config.provider.value,
+                    cause=e
+                )
+            else:
+                raise AgentExecutionError(
+                    error_msg,
+                    agent_name=self.agent_name,
+                    agent_operation="run",
+                    cause=e
+                )
+    
+    async def run_sync(
+        self,
+        prompt: str,
+        deps: DepsT,
+        context: Optional[AgentContext] = None,
+        **run_kwargs: Any
+    ) -> OutputT:
+        """Synchronous wrapper for run method."""
+        return await self.run(prompt, deps, context, **run_kwargs)
+    
+    @asynccontextmanager
+    async def execution_context(
+        self,
+        operation_name: str,
+        correlation_id: Optional[str] = None
+    ):
+        """Context manager for agent execution with proper cleanup."""
+        if correlation_id is None:
+            correlation_id = str(uuid.uuid4())
+        
+        context = AgentContext()
+        
+        try:
+            with self.logger.operation_context(operation_name, correlation_id):
+                yield context
+        finally:
+            context.mark_completed()
+    
+    def get_instructions(self) -> str:
+        """Get the current instructions for this agent."""
+        return getattr(self, '_instructions', f"You are {self.agent_name}, a specialized AI agent.")
+    
+    def validate_dependencies(self, deps: DepsT) -> List[str]:
+        """Validate that dependencies are properly configured.
+        
+        Args:
+            deps: Dependencies to validate
+            
+        Returns:
+            List of validation errors (empty if valid)
+        """
+        errors = []
+        
+        # Check API key availability
+        model_config = self._get_model_config()
+        if not deps.config.has_api_key(model_config.provider):
+            errors.append(f"No API key configured for {model_config.provider}")
+        
+        # Check project context if required
+        if self._requires_project_context() and not deps.has_project_context():
+            errors.append("Project context is required but not provided")
+        
+        return errors
+    
+    def _requires_project_context(self) -> bool:
+        """Check if this agent requires project context. Override in subclasses."""
+        return False
+    
+    @property
+    def agent(self) -> Agent[DepsT, OutputT]:
+        """Get the underlying Pydantic AI agent."""
+        return self._agent
+    
+    def __repr__(self) -> str:
+        """String representation of the agent."""
+        return f"{self.__class__.__name__}(name='{self.agent_name}', output_type={self.output_type.__name__})"
+
+
+class SimpleTextAgent(DjangoAgent[AgentDependencies, str]):
+    """Simple text-based agent for basic operations."""
+    
+    def __init__(
+        self,
+        agent_name: str,
+        config: AgentConfig,
+        instructions: str,
+        **kwargs: Any
+    ):
+        """Initialize simple text agent.
+        
+        Args:
+            agent_name: Name of the agent
+            config: Agent configuration
+            instructions: Instructions for the agent
+            **kwargs: Additional arguments
+        """
+        self._instructions = instructions
+        super().__init__(agent_name, config, str, AgentDependencies, **kwargs)
+    
+    def _register_instructions(self) -> None:
+        """Register instructions for the agent."""
+        @self._agent.instructions
+        async def agent_instructions(ctx: RunContext[AgentDependencies]) -> str:
+            return self._instructions
+    
+    def _register_tools(self) -> None:
+        """Register tools for the agent."""
+        # Simple text agent has no tools by default
+        pass
+
+
+# Utility function for creating simple agents
+def create_simple_agent(
+    name: str,
+    instructions: str,
+    config: AgentConfig,
+    **kwargs: Any
+) -> SimpleTextAgent:
+    """Create a simple text-based agent.
+    
+    Args:
+        name: Agent name
+        instructions: Agent instructions
+        config: Agent configuration
+        **kwargs: Additional arguments
+        
+    Returns:
+        Configured SimpleTextAgent
+    """
+    return SimpleTextAgent(name, config, instructions, **kwargs)

django_cfg/modules/django_app_agent/agents/base/context.py

@@ -0,0 +1,236 @@
+"""
+Context management for Django App Agent AI agents.
+
+This module provides context classes for dependency injection and
+execution management following Pydantic AI patterns.
+"""
+
+from typing import Optional, Dict, Any, List
+from dataclasses import dataclass, field
+from pathlib import Path
+from datetime import datetime, timezone
+
+from pydantic import BaseModel, Field, ConfigDict
+
+from ...core.config import AgentConfig, AIProvider
+from ...models.context import ProjectContext, InfrastructureContext
+from ...utils.logging import StructuredLogger, get_logger
+
+
+class AgentDependencies(BaseModel):
+    """Base dependencies for all Django App Agent AI agents.
+    
+    This follows Pydantic AI dependency injection patterns and provides
+    common dependencies that all agents need.
+    """
+    
+    model_config = ConfigDict(
+        extra='forbid',
+        validate_assignment=True,
+        arbitrary_types_allowed=True  # For logger and config objects
+    )
+    
+    # Core configuration
+    config: AgentConfig = Field(description="Agent configuration")
+    logger: StructuredLogger = Field(description="Structured logger instance")
+    
+    # Project context
+    project_context: Optional[ProjectContext] = Field(
+        default=None,
+        description="Django project context information"
+    )
+    
+    infrastructure_context: Optional[InfrastructureContext] = Field(
+        default=None,
+        description="Infrastructure context for code generation"
+    )
+    
+    # Execution context
+    correlation_id: str = Field(description="Correlation ID for tracing")
+    operation_name: str = Field(description="Name of the current operation")
+    
+    # Working directories
+    project_root: Optional[Path] = Field(
+        default=None,
+        description="Root directory of the Django project"
+    )
+    
+    output_directory: Optional[Path] = Field(
+        default=None,
+        description="Directory for generated output"
+    )
+    
+    # Execution metadata
+    execution_metadata: Dict[str, Any] = Field(
+        default_factory=dict,
+        description="Additional metadata for execution"
+    )
+    
+    def get_api_key(self, provider: str) -> Optional[str]:
+        """Get API key for AI provider."""
+        try:
+            ai_provider = AIProvider(provider)
+            return self.config.get_api_key(ai_provider)
+        except ValueError:
+            return None
+    
+    def has_project_context(self) -> bool:
+        """Check if project context is available."""
+        return self.project_context is not None
+    
+    def get_project_path(self) -> Optional[Path]:
+        """Get project path from context or direct setting."""
+        if self.project_context:
+            return self.project_context.project_path
+        return self.project_root
+    
+    def log_operation(self, message: str, **metadata: Any) -> None:
+        """Log operation with context."""
+        self.logger.info(
+            message,
+            operation=self.operation_name,
+            correlation_id=self.correlation_id,
+            **metadata
+        )
+    
+    def log_error(self, message: str, error: Exception, **metadata: Any) -> None:
+        """Log error with context."""
+        self.logger.error(
+            message,
+            operation=self.operation_name,
+            correlation_id=self.correlation_id,
+            error=str(error),
+            error_type=type(error).__name__,
+            **metadata
+        )
+
+
+@dataclass
+class AgentContext:
+    """Execution context for Django App Agent operations.
+    
+    This class manages the execution context for agent operations,
+    including timing, progress tracking, and result collection.
+    """
+    
+    # Execution tracking
+    start_time: datetime = field(default_factory=lambda: datetime.now(timezone.utc))
+    end_time: Optional[datetime] = field(default=None)
+    
+    # Progress tracking
+    current_stage: str = field(default="initialization")
+    progress_percentage: float = field(default=0.0)
+    
+    # Result collection
+    intermediate_results: List[Dict[str, Any]] = field(default_factory=list)
+    errors: List[str] = field(default_factory=list)
+    warnings: List[str] = field(default_factory=list)
+    
+    # Performance metrics
+    token_usage: Dict[str, int] = field(default_factory=dict)
+    api_calls_count: int = field(default=0)
+    
+    def mark_completed(self) -> None:
+        """Mark the context as completed."""
+        self.end_time = datetime.now(timezone.utc)
+        self.progress_percentage = 100.0
+    
+    def update_progress(self, stage: str, percentage: float) -> None:
+        """Update progress information."""
+        self.current_stage = stage
+        self.progress_percentage = min(100.0, max(0.0, percentage))
+    
+    def add_result(self, result: Dict[str, Any]) -> None:
+        """Add intermediate result."""
+        self.intermediate_results.append({
+            **result,
+            "timestamp": datetime.now(timezone.utc).isoformat(),
+            "stage": self.current_stage
+        })
+    
+    def add_error(self, error: str) -> None:
+        """Add error message."""
+        self.errors.append(error)
+    
+    def add_warning(self, warning: str) -> None:
+        """Add warning message."""
+        self.warnings.append(warning)
+    
+    def track_token_usage(self, provider: str, tokens: int) -> None:
+        """Track token usage by provider."""
+        self.token_usage[provider] = self.token_usage.get(provider, 0) + tokens
+    
+    def increment_api_calls(self) -> None:
+        """Increment API calls counter."""
+        self.api_calls_count += 1
+    
+    @property
+    def execution_time_seconds(self) -> float:
+        """Get execution time in seconds."""
+        end = self.end_time or datetime.now(timezone.utc)
+        return (end - self.start_time).total_seconds()
+    
+    @property
+    def is_completed(self) -> bool:
+        """Check if execution is completed."""
+        return self.end_time is not None
+    
+    @property
+    def has_errors(self) -> bool:
+        """Check if there are any errors."""
+        return len(self.errors) > 0
+    
+    @property
+    def total_tokens_used(self) -> int:
+        """Get total tokens used across all providers."""
+        return sum(self.token_usage.values())
+    
+    def get_summary(self) -> Dict[str, Any]:
+        """Get execution summary."""
+        return {
+            "start_time": self.start_time.isoformat(),
+            "end_time": self.end_time.isoformat() if self.end_time else None,
+            "execution_time_seconds": self.execution_time_seconds,
+            "current_stage": self.current_stage,
+            "progress_percentage": self.progress_percentage,
+            "is_completed": self.is_completed,
+            "results_count": len(self.intermediate_results),
+            "errors_count": len(self.errors),
+            "warnings_count": len(self.warnings),
+            "total_tokens_used": self.total_tokens_used,
+            "api_calls_count": self.api_calls_count,
+        }
+
+
+def create_agent_dependencies(
+    config: AgentConfig,
+    correlation_id: str,
+    operation_name: str,
+    project_root: Optional[Path] = None,
+    output_directory: Optional[Path] = None,
+    **metadata: Any
+) -> AgentDependencies:
+    """Factory function to create AgentDependencies.
+    
+    Args:
+        config: Agent configuration
+        correlation_id: Correlation ID for tracing
+        operation_name: Name of the operation
+        project_root: Optional project root directory
+        output_directory: Optional output directory
+        **metadata: Additional metadata
+        
+    Returns:
+        Configured AgentDependencies instance
+    """
+    logger = get_logger(f"agents.{operation_name}")
+    
+    return AgentDependencies(
+        config=config,
+        logger=logger,
+        correlation_id=correlation_id,
+        operation_name=operation_name,
+        project_root=project_root,
+        output_directory=output_directory,
+        execution_metadata=metadata
+    )