aiecs 1.5.1__py3-none-any.whl

aiecs/domain/agent/lifecycle.py

@@ -0,0 +1,296 @@
+"""
+Agent Lifecycle Management
+
+Manages agent lifecycle transitions and state management.
+"""
+
+import logging
+from typing import Dict, Any, Optional, List
+
+from .base_agent import BaseAIAgent
+from .models import AgentState
+from .registry import AgentRegistry, get_global_registry
+from .exceptions import (
+    AgentInitializationError,
+)
+
+logger = logging.getLogger(__name__)
+
+
+class AgentLifecycleManager:
+    """
+    Manages agent lifecycle: creation, initialization, activation, deactivation, shutdown.
+
+    Ensures proper state transitions and coordinates with registry.
+    """
+
+    def __init__(self, registry: Optional[AgentRegistry] = None):
+        """
+        Initialize lifecycle manager.
+
+        Args:
+            registry: Optional custom registry (uses global if not provided)
+        """
+        self.registry = registry or get_global_registry()
+        logger.info("AgentLifecycleManager initialized")
+
+    async def create_and_initialize(self, agent: BaseAIAgent) -> BaseAIAgent:
+        """
+        Register and initialize an agent.
+
+        Args:
+            agent: Agent to initialize
+
+        Returns:
+            Initialized agent
+
+        Raises:
+            AgentInitializationError: If initialization fails
+        """
+        try:
+            # Register agent
+            self.registry.register(agent)
+            logger.info(f"Agent {agent.agent_id} registered")
+
+            # Initialize agent
+            await agent.initialize()
+            logger.info(f"Agent {agent.agent_id} initialized")
+
+            return agent
+
+        except Exception as e:
+            logger.error(f"Failed to create and initialize agent {agent.agent_id}: {e}")
+
+            # Cleanup on failure
+            try:
+                if self.registry.exists(agent.agent_id):
+                    self.registry.unregister(agent.agent_id)
+            except Exception as cleanup_error:
+                logger.error(f"Cleanup failed: {cleanup_error}")
+
+            raise AgentInitializationError(
+                f"Agent initialization failed: {str(e)}",
+                agent_id=agent.agent_id,
+            )
+
+    async def activate(self, agent_id: str) -> None:
+        """
+        Activate an agent.
+
+        Args:
+            agent_id: Agent identifier
+
+        Raises:
+            AgentNotFoundError: If agent not found
+            InvalidStateTransitionError: If activation not allowed
+        """
+        agent = self.registry.get(agent_id)
+
+        try:
+            await agent.activate()
+            logger.info(f"Agent {agent_id} activated")
+        except Exception as e:
+            logger.error(f"Failed to activate agent {agent_id}: {e}")
+            raise
+
+    async def deactivate(self, agent_id: str) -> None:
+        """
+        Deactivate an agent.
+
+        Args:
+            agent_id: Agent identifier
+
+        Raises:
+            AgentNotFoundError: If agent not found
+            InvalidStateTransitionError: If deactivation not allowed
+        """
+        agent = self.registry.get(agent_id)
+
+        try:
+            await agent.deactivate()
+            logger.info(f"Agent {agent_id} deactivated")
+        except Exception as e:
+            logger.error(f"Failed to deactivate agent {agent_id}: {e}")
+            raise
+
+    async def shutdown(self, agent_id: str, unregister: bool = True) -> None:
+        """
+        Shutdown an agent.
+
+        Args:
+            agent_id: Agent identifier
+            unregister: Whether to unregister after shutdown
+
+        Raises:
+            AgentNotFoundError: If agent not found
+        """
+        agent = self.registry.get(agent_id)
+
+        try:
+            await agent.shutdown()
+            logger.info(f"Agent {agent_id} shut down")
+
+            if unregister:
+                self.registry.unregister(agent_id)
+                logger.info(f"Agent {agent_id} unregistered")
+
+        except Exception as e:
+            logger.error(f"Failed to shutdown agent {agent_id}: {e}")
+            raise
+
+    async def restart(self, agent_id: str) -> None:
+        """
+        Restart an agent (deactivate → initialize → activate).
+
+        Args:
+            agent_id: Agent identifier
+
+        Raises:
+            AgentNotFoundError: If agent not found
+        """
+        agent = self.registry.get(agent_id)
+
+        try:
+            # Deactivate
+            if agent.state in [AgentState.ACTIVE, AgentState.BUSY]:
+                await agent.deactivate()
+
+            # Re-initialize
+            await agent.initialize()
+
+            # Re-activate
+            await agent.activate()
+
+            logger.info(f"Agent {agent_id} restarted")
+
+        except Exception as e:
+            logger.error(f"Failed to restart agent {agent_id}: {e}")
+            raise
+
+    async def shutdown_all(self) -> Dict[str, Any]:
+        """
+        Shutdown all registered agents.
+
+        Returns:
+            Dictionary with shutdown results
+        """
+        results = {
+            "success": [],
+            "failed": [],
+            "total": self.registry.count(),
+        }
+
+        agents = self.registry.list_all()
+
+        for agent in agents:
+            try:
+                await self.shutdown(agent.agent_id, unregister=True)
+                results["success"].append(agent.agent_id)
+            except Exception as e:
+                logger.error(f"Failed to shutdown agent {agent.agent_id}: {e}")
+                results["failed"].append(
+                    {
+                        "agent_id": agent.agent_id,
+                        "error": str(e),
+                    }
+                )
+
+        logger.info(
+            f"Shutdown all agents: {len(results['success'])} succeeded, "
+            f"{len(results['failed'])} failed"
+        )
+
+        return results
+
+    def get_agent_status(self, agent_id: str) -> Dict[str, Any]:
+        """
+        Get agent status information.
+
+        Args:
+            agent_id: Agent identifier
+
+        Returns:
+            Status dictionary
+
+        Raises:
+            AgentNotFoundError: If agent not found
+        """
+        agent = self.registry.get(agent_id)
+
+        return {
+            "agent_id": agent.agent_id,
+            "name": agent.name,
+            "type": agent.agent_type.value,
+            "state": agent.state.value,
+            "version": agent.version,
+            "created_at": (agent.created_at.isoformat() if agent.created_at else None),
+            "last_active_at": (agent.last_active_at.isoformat() if agent.last_active_at else None),
+            "current_task_id": agent._current_task_id,
+            "metrics": {
+                "total_tasks_executed": agent.get_metrics().total_tasks_executed,
+                "successful_tasks": agent.get_metrics().successful_tasks,
+                "failed_tasks": agent.get_metrics().failed_tasks,
+                "average_execution_time": agent.get_metrics().average_execution_time,
+                "total_tool_calls": agent.get_metrics().total_tool_calls,
+            },
+        }
+
+    def list_agent_statuses(
+        self, agent_type: Optional[str] = None, state: Optional[str] = None
+    ) -> "List[Dict[str, Any]]":
+        """
+        List agent statuses with optional filtering.
+
+        Args:
+            agent_type: Optional filter by agent type
+            state: Optional filter by state
+
+        Returns:
+            List of status dictionaries
+        """
+        agents = self.registry.list_all()
+
+        # Filter by type
+        if agent_type:
+            from .models import AgentType
+
+            try:
+                type_enum = AgentType(agent_type)
+                agents = [a for a in agents if a.agent_type == type_enum]
+            except ValueError:
+                logger.warning(f"Invalid agent type: {agent_type}")
+
+        # Filter by state
+        if state:
+            from .models import AgentState
+
+            try:
+                state_enum = AgentState(state)
+                agents = [a for a in agents if a.state == state_enum]
+            except ValueError:
+                logger.warning(f"Invalid state: {state}")
+
+        return [self.get_agent_status(a.agent_id) for a in agents]
+
+
+# Global lifecycle manager
+_global_lifecycle_manager: Optional[AgentLifecycleManager] = None
+
+
+def get_global_lifecycle_manager() -> AgentLifecycleManager:
+    """
+    Get or create global lifecycle manager.
+
+    Returns:
+        Global AgentLifecycleManager instance
+    """
+    global _global_lifecycle_manager
+    if _global_lifecycle_manager is None:
+        _global_lifecycle_manager = AgentLifecycleManager()
+    return _global_lifecycle_manager
+
+
+def reset_global_lifecycle_manager() -> None:
+    """Reset global lifecycle manager (primarily for testing)."""
+    global _global_lifecycle_manager
+    _global_lifecycle_manager = None

aiecs/domain/agent/llm_agent.py

@@ -0,0 +1,300 @@
+"""
+LLM Agent
+
+Agent implementation powered by LLM for text generation and reasoning.
+"""
+
+import logging
+from typing import Dict, List, Any, Optional
+from datetime import datetime
+
+from aiecs.llm import BaseLLMClient, LLMMessage
+
+from .base_agent import BaseAIAgent
+from .models import AgentType, AgentConfiguration
+from .exceptions import TaskExecutionError
+
+logger = logging.getLogger(__name__)
+
+
+class LLMAgent(BaseAIAgent):
+    """
+    LLM-powered agent for text generation and reasoning.
+
+    This agent uses an LLM client to process tasks and generate responses.
+    """
+
+    def __init__(
+        self,
+        agent_id: str,
+        name: str,
+        llm_client: BaseLLMClient,
+        config: AgentConfiguration,
+        description: Optional[str] = None,
+        version: str = "1.0.0",
+    ):
+        """
+        Initialize LLM agent.
+
+        Args:
+            agent_id: Unique agent identifier
+            name: Agent name
+            llm_client: LLM client instance
+            config: Agent configuration
+            description: Optional description
+            version: Agent version
+        """
+        super().__init__(
+            agent_id=agent_id,
+            name=name,
+            agent_type=AgentType.CONVERSATIONAL,
+            config=config,
+            description=description or "LLM-powered conversational agent",
+            version=version,
+        )
+
+        self.llm_client = llm_client
+        self._system_prompt: Optional[str] = None
+        self._conversation_history: List[LLMMessage] = []
+
+        logger.info(f"LLMAgent initialized: {agent_id} with client {llm_client.provider_name}")
+
+    async def _initialize(self) -> None:
+        """Initialize LLM agent."""
+        # Build system prompt
+        self._system_prompt = self._build_system_prompt()
+        logger.debug(f"LLMAgent {self.agent_id} initialized with system prompt")
+
+    async def _shutdown(self) -> None:
+        """Shutdown LLM agent."""
+        # Clear conversation history
+        self._conversation_history.clear()
+
+        # Close LLM client if it has a close method
+        if hasattr(self.llm_client, "close"):
+            await self.llm_client.close()
+
+        logger.info(f"LLMAgent {self.agent_id} shut down")
+
+    def _build_system_prompt(self) -> str:
+        """Build system prompt from configuration."""
+        parts = []
+
+        if self._config.goal:
+            parts.append(f"Goal: {self._config.goal}")
+
+        if self._config.backstory:
+            parts.append(f"Background: {self._config.backstory}")
+
+        if self._config.domain_knowledge:
+            parts.append(f"Domain Knowledge: {self._config.domain_knowledge}")
+
+        if self._config.reasoning_guidance:
+            parts.append(f"Reasoning Approach: {self._config.reasoning_guidance}")
+
+        if not parts:
+            return "You are a helpful AI assistant."
+
+        return "\n\n".join(parts)
+
+    async def execute_task(self, task: Dict[str, Any], context: Dict[str, Any]) -> Dict[str, Any]:
+        """
+        Execute a task using the LLM.
+
+        Args:
+            task: Task specification with 'description' or 'prompt'
+            context: Execution context
+
+        Returns:
+            Execution result with 'output', 'reasoning', 'tokens_used'
+
+        Raises:
+            TaskExecutionError: If task execution fails
+        """
+        start_time = datetime.utcnow()
+
+        try:
+            # Extract task description
+            task_description = task.get("description") or task.get("prompt") or task.get("task")
+            if not task_description:
+                raise TaskExecutionError(
+                    "Task must contain 'description', 'prompt', or 'task' field",
+                    agent_id=self.agent_id,
+                )
+
+            # Transition to busy state
+            self._transition_state(self.state.__class__.BUSY)
+            self._current_task_id = task.get("task_id")
+
+            # Build messages
+            messages = self._build_messages(task_description, context)
+
+            # Call LLM
+            response = await self.llm_client.generate_text(
+                messages=messages,
+                model=self._config.llm_model,
+                temperature=self._config.temperature,
+                max_tokens=self._config.max_tokens,
+            )
+
+            # Extract result
+            output = response.content
+
+            # Store in conversation history if enabled
+            if self._config.memory_enabled:
+                self._conversation_history.append(LLMMessage(role="user", content=task_description))
+                self._conversation_history.append(LLMMessage(role="assistant", content=output))
+
+            # Calculate execution time
+            execution_time = (datetime.utcnow() - start_time).total_seconds()
+
+            # Update metrics
+            self.update_metrics(
+                execution_time=execution_time,
+                success=True,
+                tokens_used=getattr(response, "total_tokens", None),
+            )
+
+            # Transition back to active
+            self._transition_state(self.state.__class__.ACTIVE)
+            self._current_task_id = None
+            self.last_active_at = datetime.utcnow()
+
+            return {
+                "success": True,
+                "output": output,
+                "provider": response.provider,
+                "model": response.model,
+                "tokens_used": getattr(response, "total_tokens", None),
+                "execution_time": execution_time,
+                "timestamp": datetime.utcnow().isoformat(),
+            }
+
+        except Exception as e:
+            logger.error(f"Task execution failed for {self.agent_id}: {e}")
+
+            # Update metrics for failure
+            execution_time = (datetime.utcnow() - start_time).total_seconds()
+            self.update_metrics(execution_time=execution_time, success=False)
+
+            # Transition to error state
+            self._transition_state(self.state.__class__.ERROR)
+            self._current_task_id = None
+
+            raise TaskExecutionError(
+                f"Task execution failed: {str(e)}",
+                agent_id=self.agent_id,
+                task_id=task.get("task_id"),
+            )
+
+    async def process_message(
+        self, message: str, sender_id: Optional[str] = None
+    ) -> Dict[str, Any]:
+        """
+        Process an incoming message.
+
+        Args:
+            message: Message content
+            sender_id: Optional sender identifier
+
+        Returns:
+            Response dictionary with 'response', 'tokens_used'
+        """
+        try:
+            # Build task from message
+            task = {
+                "description": message,
+                "task_id": f"msg_{datetime.utcnow().timestamp()}",
+            }
+
+            # Execute as task
+            result = await self.execute_task(task, {"sender_id": sender_id})
+
+            return {
+                "response": result.get("output"),
+                "tokens_used": result.get("tokens_used"),
+                "timestamp": result.get("timestamp"),
+            }
+
+        except Exception as e:
+            logger.error(f"Message processing failed for {self.agent_id}: {e}")
+            raise
+
+    def _build_messages(self, user_message: str, context: Dict[str, Any]) -> List[LLMMessage]:
+        """
+        Build LLM messages from task and context.
+
+        Args:
+            user_message: User message
+            context: Context dictionary
+
+        Returns:
+            List of LLM messages
+        """
+        messages = []
+
+        # Add system prompt
+        if self._system_prompt:
+            messages.append(LLMMessage(role="system", content=self._system_prompt))
+
+        # Add conversation history if available and memory enabled
+        if self._config.memory_enabled and self._conversation_history:
+            # Limit history to prevent token overflow
+            max_history = 10  # Keep last 10 exchanges
+            messages.extend(self._conversation_history[-max_history:])
+
+        # Add additional context if provided
+        if context:
+            context_str = self._format_context(context)
+            if context_str:
+                messages.append(
+                    LLMMessage(
+                        role="system",
+                        content=f"Additional Context:\n{context_str}",
+                    )
+                )
+
+        # Add user message
+        messages.append(LLMMessage(role="user", content=user_message))
+
+        return messages
+
+    def _format_context(self, context: Dict[str, Any]) -> str:
+        """Format context dictionary as string."""
+        relevant_fields = []
+
+        # Filter out internal fields
+        for key, value in context.items():
+            if not key.startswith("_") and value is not None:
+                relevant_fields.append(f"{key}: {value}")
+
+        return "\n".join(relevant_fields) if relevant_fields else ""
+
+    def clear_conversation_history(self) -> None:
+        """Clear conversation history."""
+        self._conversation_history.clear()
+        logger.info(f"LLMAgent {self.agent_id} conversation history cleared")
+
+    def get_conversation_history(self) -> List[Dict[str, str]]:
+        """Get conversation history."""
+        return [{"role": msg.role, "content": msg.content} for msg in self._conversation_history]
+
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> "LLMAgent":
+        """
+        Deserialize LLMAgent from dictionary.
+
+        Note: LLM client must be provided separately as it cannot be serialized.
+
+        Args:
+            data: Dictionary representation
+
+        Returns:
+            LLMAgent instance
+        """
+        # This is a placeholder - actual implementation would require
+        # providing the LLM client separately
+        raise NotImplementedError(
+            "LLMAgent.from_dict requires LLM client to be provided separately. "
+            "Use constructor instead."
+        )

aiecs/domain/agent/memory/__init__.py

@@ -0,0 +1,12 @@
+"""
+Agent Memory Module
+
+Conversation memory and history management.
+"""
+
+from .conversation import ConversationMemory, Session
+
+__all__ = [
+    "ConversationMemory",
+    "Session",
+]