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

aiecs/domain/agent/integration/protocols.py

@@ -0,0 +1,281 @@
+"""
+Agent Integration Protocols
+
+Defines Protocol interfaces for agent integrations to enable duck typing and flexible integration.
+"""
+
+from typing import Protocol, Dict, Any, Optional, runtime_checkable, List
+
+
+@runtime_checkable
+class ConfigManagerProtocol(Protocol):
+    """
+    Protocol for custom configuration managers.
+
+    This protocol defines the interface for configuration managers that can
+    provide dynamic configuration to agents from external sources (databases,
+    config servers, environment variables, etc.).
+
+    Example:
+        ```python
+        class DatabaseConfigManager:
+            async def get_config(self, key: str, default: Any = None) -> Any:
+                # Fetch from database
+                return await db.get_config(key, default)
+
+            async def set_config(self, key: str, value: Any) -> None:
+                # Save to database
+                await db.set_config(key, value)
+
+            async def reload_config(self) -> None:
+                # Refresh cache
+                await db.refresh_cache()
+
+        # Use with agents
+        agent = HybridAgent(
+            config_manager=DatabaseConfigManager(),
+            ...
+        )
+        ```
+    """
+
+    async def get_config(self, key: str, default: Any = None) -> Any:
+        """
+        Get configuration value by key.
+
+        Args:
+            key: Configuration key
+            default: Default value if key not found
+
+        Returns:
+            Configuration value or default
+        """
+        ...
+
+    async def set_config(self, key: str, value: Any) -> None:
+        """
+        Set configuration value.
+
+        Args:
+            key: Configuration key
+            value: Configuration value
+        """
+        ...
+
+    async def reload_config(self) -> None:
+        """
+        Reload configuration from source.
+
+        This method should refresh any cached configuration data.
+        """
+        ...
+
+
+@runtime_checkable
+class CheckpointerProtocol(Protocol):
+    """
+    Protocol for custom checkpointers.
+
+    This protocol defines the interface for checkpointers that can save and
+    load agent state for persistence and recovery. Compatible with LangGraph
+    checkpointing patterns.
+
+    Example:
+        ```python
+        class RedisCheckpointer:
+            async def save_checkpoint(
+                self,
+                agent_id: str,
+                session_id: str,
+                checkpoint_data: Dict[str, Any]
+            ) -> str:
+                # Save to Redis
+                checkpoint_id = str(uuid.uuid4())
+                await redis.set(f"checkpoint:{checkpoint_id}", json.dumps(checkpoint_data))
+                return checkpoint_id
+
+            async def load_checkpoint(
+                self,
+                agent_id: str,
+                session_id: str,
+                checkpoint_id: Optional[str] = None
+            ) -> Optional[Dict[str, Any]]:
+                # Load from Redis
+                if checkpoint_id:
+                    data = await redis.get(f"checkpoint:{checkpoint_id}")
+                    return json.loads(data) if data else None
+                # Load latest
+                return await self._load_latest(agent_id, session_id)
+
+            async def list_checkpoints(
+                self,
+                agent_id: str,
+                session_id: str
+            ) -> list[str]:
+                # List all checkpoint IDs
+                return await redis.keys(f"checkpoint:{agent_id}:{session_id}:*")
+
+        # Use with agents
+        agent = HybridAgent(
+            checkpointer=RedisCheckpointer(),
+            ...
+        )
+        ```
+    """
+
+    async def save_checkpoint(self, agent_id: str, session_id: str, checkpoint_data: Dict[str, Any]) -> str:
+        """
+        Save checkpoint and return checkpoint ID.
+
+        Args:
+            agent_id: Agent identifier
+            session_id: Session identifier
+            checkpoint_data: Checkpoint data to save
+
+        Returns:
+            Checkpoint ID for later retrieval
+        """
+        ...
+
+    async def load_checkpoint(self, agent_id: str, session_id: str, checkpoint_id: Optional[str] = None) -> Optional[Dict[str, Any]]:
+        """
+        Load checkpoint data.
+
+        Args:
+            agent_id: Agent identifier
+            session_id: Session identifier
+            checkpoint_id: Specific checkpoint ID (loads latest if None)
+
+        Returns:
+            Checkpoint data or None if not found
+        """
+        ...
+
+    async def list_checkpoints(self, agent_id: str, session_id: str) -> list[str]:
+        """
+        List all checkpoint IDs for a session.
+
+        Args:
+            agent_id: Agent identifier
+            session_id: Session identifier
+
+        Returns:
+            List of checkpoint IDs
+        """
+        ...
+
+
+@runtime_checkable
+class AgentCollaborationProtocol(Protocol):
+    """
+    Protocol for agent collaboration.
+
+    This protocol defines the interface for agents that can collaborate with
+    other agents through task delegation, peer review, and consensus-based
+    decision making. Enables multi-agent workflows and distributed task execution.
+
+    **Key Features:**
+    - Task delegation to capable agents
+    - Peer review of task results
+    - Consensus-based decision making
+    - Capability-based agent discovery
+    - Multi-agent parallel execution
+
+    **Required Attributes:**
+    - agent_id: Unique identifier for the agent
+    - name: Human-readable agent name
+    - capabilities: List of capability strings (e.g., ["search", "analysis"])
+
+    **Required Methods:**
+    - execute_task: Execute a task and return result
+    - review_result: Review another agent's task result
+
+    Examples:
+        # Example 1: Basic collaborative agent implementation
+        class CollaborativeAgent(BaseAIAgent):
+            agent_id: str
+            name: str
+            capabilities: List[str]
+
+            async def execute_task(
+                self, task: Dict[str, Any], context: Dict[str, Any]
+            ) -> Dict[str, Any]:
+                # Execute task
+                return {"success": True, "output": "result"}
+
+            async def review_result(
+                self, task: Dict[str, Any], result: Dict[str, Any]
+            ) -> Dict[str, Any]:
+                # Review another agent's result
+                return {"approved": True, "feedback": "Looks good"}
+
+        # Example 2: Using with agent registry
+        registry = {
+            "agent1": CollaborativeAgent(
+                agent_id="agent1",
+                name="Search Agent",
+                capabilities=["search", "web_scraping"]
+            ),
+            "agent2": CollaborativeAgent(
+                agent_id="agent2",
+                name="Analysis Agent",
+                capabilities=["data_analysis", "statistics"]
+            ),
+        }
+
+        agent = HybridAgent(
+            collaboration_enabled=True,
+            agent_registry=registry,
+            ...
+        )
+
+        # Example 3: Delegate task to capable agent
+        result = await agent.delegate_task(
+            task_description="Search for recent AI papers",
+            required_capabilities=["search"]
+        )
+
+        # Example 4: Request peer review
+        review = await agent.request_peer_review(
+            task=task,
+            result=result,
+            reviewer_agent_id="agent2"
+        )
+
+        # Example 5: Multi-agent collaboration
+        result = await agent.collaborate_on_task(
+            task=task,
+            strategy="parallel",  # Execute in parallel
+            required_capabilities=["search", "analysis"]
+        )
+    """
+
+    agent_id: str
+    name: str
+    capabilities: List[str]
+
+    async def execute_task(self, task: Dict[str, Any], context: Dict[str, Any]) -> Dict[str, Any]:
+        """
+        Execute a task.
+
+        Args:
+            task: Task specification
+            context: Execution context
+
+        Returns:
+            Task execution result
+        """
+        ...
+
+    async def review_result(self, task: Dict[str, Any], result: Dict[str, Any]) -> Dict[str, Any]:
+        """
+        Review another agent's task result.
+
+        Args:
+            task: Original task specification
+            result: Task execution result to review
+
+        Returns:
+            Review result with 'approved' (bool) and 'feedback' (str)
+        """
+        ...

aiecs/domain/agent/integration/retry_policy.py

@@ -0,0 +1,218 @@
+"""
+Enhanced Retry Policy
+
+Sophisticated retry logic with exponential backoff and error classification.
+"""
+
+import asyncio
+import random
+import logging
+from typing import Callable, Any
+from enum import Enum
+
+logger = logging.getLogger(__name__)
+
+
+class ErrorType(Enum):
+    """Error types for classification."""
+
+    RATE_LIMIT = "rate_limit"
+    TIMEOUT = "timeout"
+    SERVER_ERROR = "server_error"
+    CLIENT_ERROR = "client_error"
+    NETWORK_ERROR = "network_error"
+    UNKNOWN = "unknown"
+
+
+class ErrorClassifier:
+    """Classifies errors for retry strategy."""
+
+    @staticmethod
+    def classify(error: Exception) -> ErrorType:
+        """
+        Classify error type.
+
+        Args:
+            error: Exception to classify
+
+        Returns:
+            ErrorType
+        """
+        error_str = str(error).lower()
+        error_type_name = type(error).__name__.lower()
+
+        # Rate limit errors
+        if "rate limit" in error_str or "429" in error_str:
+            return ErrorType.RATE_LIMIT
+
+        # Timeout errors
+        if "timeout" in error_str or "timed out" in error_str:
+            return ErrorType.TIMEOUT
+
+        # Server errors (5xx)
+        if any(code in error_str for code in ["500", "502", "503", "504"]):
+            return ErrorType.SERVER_ERROR
+
+        # Client errors (4xx)
+        if any(code in error_str for code in ["400", "401", "403", "404"]):
+            return ErrorType.CLIENT_ERROR
+
+        # Network errors
+        if any(term in error_type_name for term in ["connection", "network", "socket"]):
+            return ErrorType.NETWORK_ERROR
+
+        return ErrorType.UNKNOWN
+
+    @staticmethod
+    def is_retryable(error_type: ErrorType) -> bool:
+        """
+        Determine if error type should be retried.
+
+        Args:
+            error_type: Error type
+
+        Returns:
+            True if retryable
+        """
+        retryable_types = {
+            ErrorType.RATE_LIMIT,
+            ErrorType.TIMEOUT,
+            ErrorType.SERVER_ERROR,
+            ErrorType.NETWORK_ERROR,
+        }
+        return error_type in retryable_types
+
+
+class EnhancedRetryPolicy:
+    """
+    Enhanced retry policy with exponential backoff and jitter.
+
+    Example:
+        policy = EnhancedRetryPolicy(max_retries=5, base_delay=1.0)
+        result = await policy.execute_with_retry(my_async_function, arg1, arg2)
+    """
+
+    def __init__(
+        self,
+        max_retries: int = 3,
+        base_delay: float = 1.0,
+        max_delay: float = 60.0,
+        exponential_base: float = 2.0,
+        jitter: bool = True,
+    ):
+        """
+        Initialize retry policy.
+
+        Args:
+            max_retries: Maximum number of retry attempts
+            base_delay: Base delay in seconds
+            max_delay: Maximum delay in seconds
+            exponential_base: Base for exponential backoff
+            jitter: Whether to add random jitter
+        """
+        self.max_retries = max_retries
+        self.base_delay = base_delay
+        self.max_delay = max_delay
+        self.exponential_base = exponential_base
+        self.jitter = jitter
+
+    def calculate_delay(self, attempt: int, error_type: ErrorType) -> float:
+        """
+        Calculate delay for retry attempt.
+
+        Args:
+            attempt: Retry attempt number (0-indexed)
+            error_type: Type of error
+
+        Returns:
+            Delay in seconds
+        """
+        # Base exponential backoff
+        delay = min(self.base_delay * (self.exponential_base**attempt), self.max_delay)
+
+        # Adjust for error type
+        if error_type == ErrorType.RATE_LIMIT:
+            # Longer delay for rate limits
+            delay *= 2
+
+        # Add jitter to prevent thundering herd
+        if self.jitter:
+            delay *= 0.5 + random.random()
+
+        return delay
+
+    async def execute_with_retry(self, func: Callable, *args, **kwargs) -> Any:
+        """
+        Execute function with retry logic.
+
+        Args:
+            func: Async function to execute
+            *args: Function arguments
+            **kwargs: Function keyword arguments
+
+        Returns:
+            Function result
+
+        Raises:
+            Exception: If all retries exhausted
+        """
+        last_error = None
+
+        for attempt in range(self.max_retries + 1):
+            try:
+                result = await func(*args, **kwargs)
+
+                # Log success after retries
+                if attempt > 0:
+                    logger.info(f"Succeeded after {attempt} retries")
+
+                return result
+
+            except Exception as e:
+                last_error = e
+
+                # Classify error
+                error_type = ErrorClassifier.classify(e)
+
+                # Check if we should retry
+                if attempt >= self.max_retries:
+                    logger.error(f"Max retries ({self.max_retries}) exhausted")
+                    break
+
+                if not ErrorClassifier.is_retryable(error_type):
+                    logger.error(f"Non-retryable error: {error_type.value}")
+                    break
+
+                # Calculate delay and wait
+                delay = self.calculate_delay(attempt, error_type)
+                logger.warning(f"Attempt {attempt + 1} failed ({error_type.value}). " f"Retrying in {delay:.2f}s...")
+                await asyncio.sleep(delay)
+
+        # All retries exhausted
+        if last_error is None:
+            raise RuntimeError("Retry failed but no error was captured")
+        raise last_error
+
+
+async def with_retry(
+    func: Callable,
+    max_retries: int = 3,
+    base_delay: float = 1.0,
+    *args,
+    **kwargs,
+) -> Any:
+    """
+    Convenience function for executing with retry.
+
+    Args:
+        func: Async function to execute
+        max_retries: Maximum number of retries
+        base_delay: Base delay in seconds
+        *args: Function arguments
+        **kwargs: Function keyword arguments
+
+    Returns:
+        Function result
+    """
+    policy = EnhancedRetryPolicy(max_retries=max_retries, base_delay=base_delay)
+    return await policy.execute_with_retry(func, *args, **kwargs)

aiecs/domain/agent/integration/role_config.py

@@ -0,0 +1,213 @@
+"""
+Role-Based Configuration
+
+Load agent configuration from role templates.
+"""
+
+import logging
+import yaml  # type: ignore[import-untyped]
+from typing import Dict, Any, Optional
+from pathlib import Path
+
+from ..models import AgentConfiguration
+
+logger = logging.getLogger(__name__)
+
+
+class RoleConfiguration:
+    """
+    Manages role-based agent configurations.
+
+    Example:
+        role_config = RoleConfiguration.load_from_file("roles/developer.yaml")
+        agent_config = role_config.to_agent_config()
+    """
+
+    def __init__(
+        self,
+        role_name: str,
+        goal: Optional[str] = None,
+        backstory: Optional[str] = None,
+        domain_knowledge: Optional[str] = None,
+        llm_model: Optional[str] = None,
+        temperature: float = 0.7,
+        max_tokens: Optional[int] = None,
+        tools: Optional[list] = None,
+        **kwargs,
+    ):
+        """
+        Initialize role configuration.
+
+        Args:
+            role_name: Role name
+            goal: Agent goal
+            backstory: Agent backstory
+            domain_knowledge: Domain knowledge
+            llm_model: LLM model to use
+            temperature: LLM temperature
+            max_tokens: Max tokens
+            tools: List of tool names
+            **kwargs: Additional configuration
+        """
+        self.role_name = role_name
+        self.goal = goal
+        self.backstory = backstory
+        self.domain_knowledge = domain_knowledge
+        self.llm_model = llm_model
+        self.temperature = temperature
+        self.max_tokens = max_tokens
+        self.tools = tools or []
+        self.additional_config = kwargs
+
+    def to_agent_config(self) -> AgentConfiguration:
+        """
+        Convert to AgentConfiguration.
+
+        Returns:
+            AgentConfiguration instance
+        """
+        return AgentConfiguration(  # type: ignore[call-arg]
+            goal=self.goal,
+            backstory=self.backstory,
+            domain_knowledge=self.domain_knowledge,
+            llm_model=self.llm_model,
+            temperature=self.temperature,
+            max_tokens=self.max_tokens if self.max_tokens is not None else 4096,  # type: ignore[arg-type]
+            **self.additional_config,
+        )
+
+    @classmethod
+    def load_from_file(cls, file_path: str) -> "RoleConfiguration":
+        """
+        Load role configuration from YAML file.
+
+        Args:
+            file_path: Path to YAML file
+
+        Returns:
+            RoleConfiguration instance
+        """
+        path = Path(file_path)
+
+        if not path.exists():
+            raise FileNotFoundError(f"Role configuration file not found: {file_path}")
+
+        with open(path, "r") as f:
+            data = yaml.safe_load(f)
+
+        logger.info(f"Loaded role configuration from {file_path}")
+        return cls(**data)
+
+    @classmethod
+    def load_from_dict(cls, data: Dict[str, Any]) -> "RoleConfiguration":
+        """
+        Load role configuration from dictionary.
+
+        Args:
+            data: Configuration dictionary
+
+        Returns:
+            RoleConfiguration instance
+        """
+        return cls(**data)
+
+    def merge_with(self, other: "RoleConfiguration") -> "RoleConfiguration":
+        """
+        Merge with another configuration (other takes precedence).
+
+        Args:
+            other: Other configuration
+
+        Returns:
+            New merged RoleConfiguration
+        """
+        merged_data = {
+            "role_name": other.role_name or self.role_name,
+            "goal": other.goal or self.goal,
+            "backstory": other.backstory or self.backstory,
+            "domain_knowledge": other.domain_knowledge or self.domain_knowledge,
+            "llm_model": other.llm_model or self.llm_model,
+            "temperature": (other.temperature if other.temperature != 0.7 else self.temperature),
+            "max_tokens": other.max_tokens or self.max_tokens,
+            "tools": other.tools if other.tools else self.tools,
+            **{**self.additional_config, **other.additional_config},
+        }
+        return RoleConfiguration(**merged_data)
+
+    def to_dict(self) -> Dict[str, Any]:
+        """Convert to dictionary."""
+        return {
+            "role_name": self.role_name,
+            "goal": self.goal,
+            "backstory": self.backstory,
+            "domain_knowledge": self.domain_knowledge,
+            "llm_model": self.llm_model,
+            "temperature": self.temperature,
+            "max_tokens": self.max_tokens,
+            "tools": self.tools,
+            **self.additional_config,
+        }
+
+
+def load_role_config(role_name: str, base_path: str = "./agent_roles") -> RoleConfiguration:
+    """
+    Load role configuration by name.
+
+    Args:
+        role_name: Role name
+        base_path: Base directory for role configurations
+
+    Returns:
+        RoleConfiguration instance
+    """
+    file_path = Path(base_path) / f"{role_name}.yaml"
+    return RoleConfiguration.load_from_file(str(file_path))
+
+
+# Predefined role templates
+ROLE_TEMPLATES = {
+    "developer": {
+        "role_name": "developer",
+        "goal": "Write clean, efficient, and maintainable code",
+        "backstory": ("You are an experienced software developer with expertise in " "multiple programming languages and best practices"),
+        "domain_knowledge": "Software development, design patterns, testing, debugging",
+        "temperature": 0.3,
+    },
+    "researcher": {
+        "role_name": "researcher",
+        "goal": "Gather, analyze, and synthesize information from various sources",
+        "backstory": "You are a meticulous researcher skilled at finding and evaluating information",
+        "domain_knowledge": "Research methodologies, critical analysis, information synthesis",
+        "temperature": 0.5,
+    },
+    "analyst": {
+        "role_name": "analyst",
+        "goal": "Analyze data and provide actionable insights",
+        "backstory": "You are a data analyst with strong analytical and problem-solving skills",
+        "domain_knowledge": "Data analysis, statistics, visualization, interpretation",
+        "temperature": 0.4,
+    },
+    "creative": {
+        "role_name": "creative",
+        "goal": "Generate creative and innovative ideas",
+        "backstory": "You are a creative thinker with a knack for innovative solutions",
+        "domain_knowledge": "Creative thinking, brainstorming, innovation",
+        "temperature": 0.9,
+    },
+}
+
+
+def get_role_template(role_name: str) -> RoleConfiguration:
+    """
+    Get predefined role template.
+
+    Args:
+        role_name: Role name
+
+    Returns:
+        RoleConfiguration instance
+    """
+    if role_name not in ROLE_TEMPLATES:
+        raise ValueError(f"Unknown role template: {role_name}")
+
+    return RoleConfiguration.load_from_dict(ROLE_TEMPLATES[role_name])