daita-agents 0.2.0__py3-none-any.whl

daita/config/base.py

@@ -0,0 +1,159 @@
+"""
+Configuration models for Daita Agents.
+
+Simplified configuration system focused on essential functionality for MVP.
+Advanced features like complex retry policies and error analysis can be added later.
+"""
+import asyncio
+from enum import Enum
+from typing import Any, Dict, List, Optional, Union
+from pydantic import BaseModel, Field, model_validator
+
+class YamlSerializableMixin:
+    """Mixin for YAML serialization support."""
+    
+    def model_dump_yaml_safe(self) -> Dict[str, Any]:
+        """Export to YAML-safe dictionary."""
+        return self.model_dump(mode='json', exclude_none=True)
+
+class AgentType(str, Enum):
+    """Types of agents available."""
+    SUBSTRATE = "substrate"
+    # Keep room for future agent types without forcing everything to be SUBSTRATE
+
+class FocusType(str, Enum):
+    """Types of focus selectors."""
+    COLUMN = "column"
+    JSONPATH = "jsonpath"
+    XPATH = "xpath"
+    CSS_SELECTOR = "css"
+    REGEX = "regex"
+    SEMANTIC = "semantic"
+
+class RetryStrategy(str, Enum):
+    """Retry strategy types - unified from core/reliability.py."""
+    FIXED = "fixed"
+    EXPONENTIAL = "exponential" 
+    LINEAR = "linear"
+    # Legacy aliases for backward compatibility
+    EXPONENTIAL_BACKOFF = "exponential"
+    FIXED_DELAY = "fixed"
+    IMMEDIATE = "fixed"
+
+class FocusConfig(YamlSerializableMixin, BaseModel):
+    """Configuration for focus parameter."""
+    type: Optional[FocusType] = None
+    include: Optional[Union[List[str], str]] = None
+    exclude: Optional[Union[List[str], str]] = None
+    paths: Optional[List[str]] = None
+    description: Optional[str] = None
+
+class RetryPolicy(YamlSerializableMixin, BaseModel):
+    """Unified retry configuration compatible with core/reliability.py."""
+    
+    # Core fields (compatible with dataclass version)
+    max_retries: int = Field(default=3, ge=0, le=20, description="Maximum number of retry attempts")
+    base_delay: float = Field(default=1.0, ge=0.1, le=60.0, description="Base delay in seconds")
+    max_delay: float = Field(default=60.0, ge=1.0, le=300.0, description="Maximum delay in seconds")
+    strategy: RetryStrategy = Field(default=RetryStrategy.EXPONENTIAL, description="Retry timing strategy")
+    jitter: bool = Field(default=True, description="Add jitter to prevent thundering herd")
+    
+    # Additional fields for configuration support
+    permanent_errors: List[str] = Field(
+        default=[
+            "AuthenticationError",
+            "PermissionError", 
+            "ValidationError",
+            "InvalidDataError",
+            "NotFoundError",
+            "BadRequestError",
+            "PermanentError"
+        ],
+        description="Error types that should not be retried"
+    )
+    
+    # Legacy compatibility field
+    initial_delay: Optional[float] = Field(default=None, description="Legacy field - use base_delay instead")
+    
+    @model_validator(mode='after')
+    def handle_legacy_fields(self):
+        """Handle legacy initial_delay field."""
+        if self.initial_delay is not None and hasattr(self, 'base_delay'):
+            self.base_delay = self.initial_delay
+        return self
+    
+    def calculate_delay(self, attempt: int) -> float:
+        """Calculate delay for given retry attempt."""
+        if self.strategy == RetryStrategy.FIXED:
+            delay = self.base_delay
+        elif self.strategy == RetryStrategy.LINEAR:
+            delay = self.base_delay * attempt
+        else:  # EXPONENTIAL
+            delay = self.base_delay * (2 ** (attempt - 1))
+        
+        # Apply max delay limit
+        delay = min(delay, self.max_delay)
+        
+        # Add jitter to prevent thundering herd
+        if self.jitter:
+            import random
+            delay *= (0.5 + random.random() * 0.5)
+        
+        return delay
+    
+    async def execute_with_retry(
+        self, 
+        func,
+        *args, 
+        **kwargs
+    ):
+        """Execute function with retry policy."""
+        from typing import Callable, Any
+        last_error = None
+        
+        for attempt in range(self.max_retries + 1):
+            try:
+                if asyncio.iscoroutinefunction(func):
+                    return await func(*args, **kwargs)
+                else:
+                    return func(*args, **kwargs)
+            except Exception as e:
+                last_error = e
+                
+                if attempt < self.max_retries:
+                    delay = self.calculate_delay(attempt + 1)
+                    await asyncio.sleep(delay)
+                else:
+                    break
+        
+        # If we get here, all retries failed
+        raise last_error
+
+class AgentConfig(YamlSerializableMixin, BaseModel):
+    """Simplified agent configuration."""
+    name: str
+    type: AgentType = AgentType.SUBSTRATE
+    enabled: bool = True
+    settings: Dict[str, Any] = Field(default_factory=dict)
+    
+    # Simple retry configuration - optional
+    enable_retry: bool = Field(default=False, description="Enable retry behavior (default: fail-fast)")
+    retry_policy: Optional[RetryPolicy] = Field(default=None, description="Retry policy - only used if enable_retry=True")
+    
+    @model_validator(mode='after')
+    def setup_retry_policy(self):
+        """Set up retry policy if retry is enabled but no policy provided."""
+        if self.enable_retry and self.retry_policy is None:
+            self.retry_policy = RetryPolicy()
+        return self
+    
+    @property
+    def retry_enabled(self) -> bool:
+        """Check if retry behavior is enabled."""
+        return self.enable_retry and self.retry_policy is not None
+
+class DaitaConfig(YamlSerializableMixin, BaseModel):
+    """Main configuration for Daita framework."""
+    version: str = "1.0.0"
+    agents: List[AgentConfig] = Field(default_factory=list)
+    settings: Dict[str, Any] = Field(default_factory=dict)

daita/config/settings.py

@@ -0,0 +1,184 @@
+"""
+Runtime settings management.
+
+Simplified settings system focused on essential configuration.
+"""
+import os
+from pathlib import Path
+from typing import Any, Dict, Optional, List, ClassVar
+from pydantic import BaseModel
+from dotenv import load_dotenv
+
+# Load environment variables
+load_dotenv()
+
+class Settings(BaseModel):
+    """Runtime settings for Daita framework."""
+    
+    # API settings (SECURE - from environment only)
+    api_key: Optional[str] = None
+    api_endpoint: str = ""  # Must be set via DAITA_API_ENDPOINT env var
+    dashboard_url: str = ""  # Must be set via DAITA_DASHBOARD_URL env var
+    
+    # Deployment settings
+    deployment_id: Optional[str] = None
+    environment: str = "development"
+    
+    # Local mode settings
+    local_mode: bool = True
+    cache_dir: Path = Path.home() / ".daita" / "cache"
+    log_level: str = "INFO"
+    
+    # LLM Provider API Keys
+    openai_api_key: Optional[str] = None
+    anthropic_api_key: Optional[str] = None
+    google_api_key: Optional[str] = None
+    gemini_api_key: Optional[str] = None
+    xai_api_key: Optional[str] = None
+    grok_api_key: Optional[str] = None
+    
+    # LLM settings
+    default_model: str = "gpt-4"
+    default_provider: str = "openai"
+    default_temperature: float = 0.7
+    
+    def validate_endpoint(self, endpoint: str) -> str:
+        """Validate API endpoint for security."""
+        if not endpoint:
+            raise ValueError("API endpoint cannot be empty")
+        
+        if not endpoint.startswith('https://'):
+            raise ValueError("API endpoint must use HTTPS")
+        
+        return endpoint
+    
+    def __init__(self, **data):
+        # Override with environment variables
+        env_overrides = {}
+        
+        # Lambda environment detection - use /tmp for cache
+        if os.getenv('AWS_LAMBDA_FUNCTION_NAME') or os.getenv('DAITA_RUNTIME') == 'lambda':
+            env_overrides["cache_dir"] = Path("/tmp/.daita/cache")
+        
+        # Main Daita API key
+        if os.getenv("DAITA_API_KEY"):
+            env_overrides["api_key"] = os.getenv("DAITA_API_KEY")
+        
+        # API endpoints - REQUIRED from environment
+        api_endpoint = os.getenv("DAITA_API_ENDPOINT")
+        if api_endpoint:
+            try:
+                self.validate_endpoint(api_endpoint)
+                env_overrides["api_endpoint"] = api_endpoint
+            except ValueError as e:
+                raise ValueError(f"Invalid DAITA_API_ENDPOINT environment variable: {e}")
+        
+        dashboard_url = os.getenv("DAITA_DASHBOARD_URL") 
+        if dashboard_url:
+            try:
+                self.validate_endpoint(dashboard_url)
+                env_overrides["dashboard_url"] = dashboard_url
+            except ValueError as e:
+                raise ValueError(f"Invalid DAITA_DASHBOARD_URL environment variable: {e}")
+        
+        # Deployment settings
+        if os.getenv("DAITA_DEPLOYMENT_ID"):
+            env_overrides["deployment_id"] = os.getenv("DAITA_DEPLOYMENT_ID")
+        
+        if os.getenv("DAITA_ENVIRONMENT"):
+            env_overrides["environment"] = os.getenv("DAITA_ENVIRONMENT")
+        
+        # LLM Provider API Keys
+        if os.getenv("OPENAI_API_KEY"):
+            env_overrides["openai_api_key"] = os.getenv("OPENAI_API_KEY")
+        
+        if os.getenv("ANTHROPIC_API_KEY"):
+            env_overrides["anthropic_api_key"] = os.getenv("ANTHROPIC_API_KEY")
+        
+        if os.getenv("GOOGLE_API_KEY"):
+            env_overrides["google_api_key"] = os.getenv("GOOGLE_API_KEY")
+        
+        if os.getenv("GEMINI_API_KEY"):
+            env_overrides["gemini_api_key"] = os.getenv("GEMINI_API_KEY")
+        
+        if os.getenv("XAI_API_KEY"):
+            env_overrides["xai_api_key"] = os.getenv("XAI_API_KEY")
+        
+        if os.getenv("GROK_API_KEY"):
+            env_overrides["grok_api_key"] = os.getenv("GROK_API_KEY")
+        
+        # General settings
+        if os.getenv("DAITA_LOCAL_MODE"):
+            env_overrides["local_mode"] = os.getenv("DAITA_LOCAL_MODE").lower() == "true"
+        
+        if os.getenv("DAITA_LOG_LEVEL"):
+            env_overrides["log_level"] = os.getenv("DAITA_LOG_LEVEL")
+        
+        if os.getenv("DAITA_DEFAULT_MODEL"):
+            env_overrides["default_model"] = os.getenv("DAITA_DEFAULT_MODEL")
+        
+        if os.getenv("DAITA_DEFAULT_PROVIDER"):
+            env_overrides["default_provider"] = os.getenv("DAITA_DEFAULT_PROVIDER")
+        
+        if os.getenv("DAITA_DEFAULT_TEMPERATURE"):
+            try:
+                env_overrides["default_temperature"] = float(os.getenv("DAITA_DEFAULT_TEMPERATURE"))
+            except (ValueError, TypeError):
+                pass  # Use default if invalid
+        
+        # Merge with provided data
+        super().__init__(**{**data, **env_overrides})
+        
+        # Ensure cache directory exists
+        self.cache_dir.mkdir(parents=True, exist_ok=True)
+        
+        # SECURITY: Only validate endpoints in Lambda runtime
+        # Customer deployments use hardcoded production endpoints
+        if os.getenv('DAITA_RUNTIME') == 'lambda':
+            if not self.api_endpoint:
+                raise ValueError("DAITA_API_ENDPOINT environment variable required for Lambda runtime")
+            if not self.dashboard_url:
+                raise ValueError("DAITA_DASHBOARD_URL environment variable required for Lambda runtime")
+    
+    def get_llm_api_key(self, provider: str) -> Optional[str]:
+        """
+        Get API key for a specific LLM provider.
+        
+        Args:
+            provider: Provider name (openai, anthropic, google, gemini, xai, grok)
+            
+        Returns:
+            API key for the provider or None if not set
+        """
+        provider = provider.lower()
+        
+        if provider == "openai":
+            return self.openai_api_key
+        elif provider == "anthropic":
+            return self.anthropic_api_key
+        elif provider in ["google", "gemini"]:
+            return self.google_api_key or self.gemini_api_key
+        elif provider in ["xai", "grok"]:
+            return self.xai_api_key or self.grok_api_key
+        
+        return None
+    
+    def get_daita_api_key(self) -> Optional[str]:
+        """
+        Get Daita API key with fallback to provider keys.
+        
+        Returns:
+            Daita API key or first available provider key
+        """
+        return (
+            self.api_key or
+            self.openai_api_key or
+            self.anthropic_api_key or
+            self.google_api_key or
+            self.gemini_api_key or
+            self.xai_api_key or
+            self.grok_api_key
+        )
+
+# Global settings instance
+settings = Settings()

daita/core/__init__.py

@@ -0,0 +1,262 @@
+"""
+Core functionality for Daita Agents.
+
+This module provides the essential building blocks for the Daita framework:
+- Exception hierarchy with intelligent retry hints
+- Core interfaces that define contracts for agents, LLM providers, and processors
+- Focus system for data filtering and selection
+- Relay system for agent-to-agent communication
+- Workflow orchestration for multi-agent systems
+- Unified tracing system for automatic observability
+- Plugin tracing for tool execution monitoring
+- Decision tracing for agent reasoning capture
+
+The core module is designed to be imported by other framework components
+and provides the foundational abstractions that everything else builds upon.
+"""
+
+# Exception hierarchy - Must be imported first to avoid circular imports
+from .exceptions import (
+    # Base exceptions
+    DaitaError,
+    AgentError,
+    ConfigError,
+    LLMError,
+    PluginError,
+    WorkflowError,
+    
+    # Retry-specific exceptions with built-in hints
+    TransientError,
+    RetryableError,
+    PermanentError,
+    
+    # Specific transient errors
+    RateLimitError,
+    TimeoutError,
+    ConnectionError,
+    ServiceUnavailableError,
+    TemporaryError,
+    TooManyRequestsError,
+    
+    # Specific retryable errors
+    ResourceBusyError,
+    DataInconsistencyError,
+    ProcessingQueueFullError,
+    
+    # Specific permanent errors
+    AuthenticationError,
+    PermissionError,
+    ValidationError,
+    InvalidDataError,
+    NotFoundError,
+    BadRequestError,
+    
+    # Circuit breaker errors
+    CircuitBreakerOpenError,
+    
+    # Utility functions
+    classify_exception,
+    create_contextual_error
+)
+
+# Core interfaces - Define contracts for framework components
+from .interfaces import (
+    Agent,
+    LLMProvider,
+    DatabaseBackend,
+    DataProcessor
+)
+
+# Focus system - For data filtering and selection
+from .focus import apply_focus
+
+# Unified Tracing System - NEW: Automatic observability for all operations
+from .tracing import (
+    # Main tracing interface
+    get_trace_manager,
+    TraceManager,
+    
+    # Trace types and status
+    TraceType,
+    TraceStatus,
+    
+    # Core tracing components
+    TraceSpan,
+    TraceContext,
+    DashboardReporter
+)
+
+# Plugin Tracing System - NEW: Automatic tool execution monitoring
+from .plugin_tracing import (
+    # Main plugin tracing function
+    trace_plugin,
+    
+    # Traced plugin factories
+    traced_postgresql,
+    traced_mysql,
+    traced_mongodb,
+    traced_rest,
+    
+    # Context managers for batch operations
+    traced_transaction,
+    traced_api_batch,
+    
+    # Query and statistics functions
+    get_plugin_traces,
+    get_plugin_stats,
+    
+    # Advanced plugin tracing class
+    TracedPlugin
+)
+
+# Decision Tracing System - NEW: Agent reasoning and confidence capture
+from .decision_tracing import (
+    # Main decision tracing interfaces
+    record_decision_point,
+    trace_decision,
+    
+    # Decision types
+    DecisionType,
+    
+    # Helper functions for common decision patterns
+    record_classification_decision,
+    record_analysis_decision,
+    record_recommendation_decision,
+    
+    # Query and analysis functions
+    get_recent_decisions,
+    get_decision_stats,
+    
+    # Advanced decision tracing classes
+    DecisionRecorder,
+    DecisionContext
+)
+
+# Export everything that other modules need
+__all__ = [
+    # Exception hierarchy
+    "DaitaError",
+    "AgentError",
+    "ConfigError", 
+    "LLMError",
+    "PluginError",
+    "WorkflowError",
+    
+    # Retry-specific exceptions
+    "TransientError",
+    "RetryableError", 
+    "PermanentError",
+    
+    # Specific transient errors
+    "RateLimitError",
+    "TimeoutError",
+    "ConnectionError",
+    "ServiceUnavailableError", 
+    "TemporaryError",
+    "TooManyRequestsError",
+    
+    # Specific retryable errors
+    "ResourceBusyError",
+    "DataInconsistencyError",
+    "ProcessingQueueFullError",
+    
+    # Specific permanent errors
+    "AuthenticationError",
+    "PermissionError",
+    "ValidationError",
+    "InvalidDataError",
+    "NotFoundError", 
+    "BadRequestError",
+    
+    # Circuit breaker errors
+    "CircuitBreakerOpenError",
+    
+    # Exception utility functions
+    "classify_exception",
+    "create_contextual_error",
+    
+    # Core interfaces
+    "Agent",
+    "LLMProvider",
+    "DatabaseBackend",
+    "DataProcessor",
+    
+    # Focus system
+    "apply_focus",
+    
+    # === NEW: Unified Tracing System ===
+    # Main tracing interface
+    "get_trace_manager",
+    "TraceManager",
+    
+    # Trace types and status
+    "TraceType",
+    "TraceStatus",
+    
+    # Core tracing components
+    "TraceSpan",
+    "TraceContext", 
+    "DashboardReporter",
+    
+    # === NEW: Plugin Tracing System ===
+    # Main plugin tracing
+    "trace_plugin",
+    
+    # Traced plugin factories
+    "traced_postgresql",
+    "traced_mysql",
+    "traced_mongodb", 
+    "traced_rest",
+    
+    # Plugin batch operations
+    "traced_transaction",
+    "traced_api_batch",
+    
+    # Plugin analytics
+    "get_plugin_traces",
+    "get_plugin_stats",
+    
+    # Advanced plugin tracing
+    "TracedPlugin",
+    
+    # === NEW: Decision Tracing System ===
+    # Main decision tracing
+    "record_decision_point",
+    "trace_decision",
+    
+    # Decision types
+    "DecisionType",
+    
+    # Decision helpers
+    "record_classification_decision",
+    "record_analysis_decision", 
+    "record_recommendation_decision",
+    
+    # Decision analytics
+    "get_recent_decisions",
+    "get_decision_stats",
+    
+    # Advanced decision tracing
+    "DecisionRecorder",
+    "DecisionContext"
+]
+
+# Core module metadata
+CORE_INFO = {
+    "components": [
+        "exceptions",
+        "interfaces", 
+        "focus",
+        "tracing",
+        "plugin_tracing",
+        "decision_tracing"
+    ],
+    "description": "Core abstractions and utilities for the Daita framework",
+    "stability": "stable"
+}
+
+def get_core_info() -> dict:
+    """Get information about core module components."""
+    return CORE_INFO.copy()
+
+__all__.append("get_core_info")