aiecs 1.3.8__py3-none-any.whl → 1.4.1__py3-none-any.whl

aiecs/domain/agent/llm_agent.py

@@ -0,0 +1,309 @@
+"""
+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, LLMResponse
+
+from .base_agent import BaseAIAgent
+from .models import AgentType, AgentConfiguration
+from .exceptions import TaskExecutionError, AgentInitializationError
+
+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,13 @@
+"""
+Agent Memory Module
+
+Conversation memory and history management.
+"""
+
+from .conversation import ConversationMemory, Session
+
+__all__ = [
+    "ConversationMemory",
+    "Session",
+]
+

aiecs/domain/agent/memory/conversation.py

@@ -0,0 +1,216 @@
+"""
+Conversation Memory
+
+Multi-turn conversation handling with session management.
+"""
+
+import logging
+from typing import Dict, List, Optional
+from datetime import datetime
+from dataclasses import dataclass, field
+
+from aiecs.llm import LLMMessage
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class Session:
+    """Conversation session."""
+    session_id: str
+    agent_id: str
+    created_at: datetime = field(default_factory=datetime.utcnow)
+    last_activity: datetime = field(default_factory=datetime.utcnow)
+    messages: List[LLMMessage] = field(default_factory=list)
+    metadata: Dict = field(default_factory=dict)
+
+    def add_message(self, role: str, content: str) -> None:
+        """Add message to session."""
+        self.messages.append(LLMMessage(role=role, content=content))
+        self.last_activity = datetime.utcnow()
+
+    def get_recent_messages(self, limit: int) -> List[LLMMessage]:
+        """Get recent messages."""
+        return self.messages[-limit:] if limit else self.messages
+
+    def clear(self) -> None:
+        """Clear session messages."""
+        self.messages.clear()
+
+
+class ConversationMemory:
+    """
+    Manages multi-turn conversations with session isolation.
+
+    Example:
+        memory = ConversationMemory(agent_id="agent-1")
+        session_id = memory.create_session()
+        memory.add_message(session_id, "user", "Hello")
+        memory.add_message(session_id, "assistant", "Hi there!")
+        history = memory.get_history(session_id)
+    """
+
+    def __init__(self, agent_id: str, max_sessions: int = 100):
+        """
+        Initialize conversation memory.
+
+        Args:
+            agent_id: Agent identifier
+            max_sessions: Maximum number of sessions to keep
+        """
+        self.agent_id = agent_id
+        self.max_sessions = max_sessions
+        self._sessions: Dict[str, Session] = {}
+        logger.info(f"ConversationMemory initialized for agent {agent_id}")
+
+    def create_session(self, session_id: Optional[str] = None) -> str:
+        """
+        Create a new conversation session.
+
+        Args:
+            session_id: Optional custom session ID
+
+        Returns:
+            Session ID
+        """
+        if session_id is None:
+            session_id = f"session_{datetime.utcnow().timestamp()}"
+
+        if session_id in self._sessions:
+            logger.warning(f"Session {session_id} already exists")
+            return session_id
+
+        self._sessions[session_id] = Session(
+            session_id=session_id,
+            agent_id=self.agent_id
+        )
+
+        # Cleanup old sessions if limit exceeded
+        if len(self._sessions) > self.max_sessions:
+            self._cleanup_old_sessions()
+
+        logger.debug(f"Session {session_id} created")
+        return session_id
+
+    def add_message(
+        self,
+        session_id: str,
+        role: str,
+        content: str
+    ) -> None:
+        """
+        Add message to session.
+
+        Args:
+            session_id: Session ID
+            role: Message role
+            content: Message content
+        """
+        if session_id not in self._sessions:
+            logger.warning(f"Session {session_id} not found, creating it")
+            self.create_session(session_id)
+
+        self._sessions[session_id].add_message(role, content)
+
+    def get_history(
+        self,
+        session_id: str,
+        limit: Optional[int] = None
+    ) -> List[LLMMessage]:
+        """
+        Get conversation history for session.
+
+        Args:
+            session_id: Session ID
+            limit: Optional limit on number of messages
+
+        Returns:
+            List of messages
+        """
+        if session_id not in self._sessions:
+            return []
+
+        session = self._sessions[session_id]
+        return session.get_recent_messages(limit) if limit else session.messages.copy()
+
+    def format_history(
+        self,
+        session_id: str,
+        limit: Optional[int] = None
+    ) -> str:
+        """
+        Format conversation history as string.
+
+        Args:
+            session_id: Session ID
+            limit: Optional limit on number of messages
+
+        Returns:
+            Formatted history string
+        """
+        history = self.get_history(session_id, limit)
+        lines = []
+        for msg in history:
+            lines.append(f"{msg.role.upper()}: {msg.content}")
+        return "\n".join(lines)
+
+    def clear_session(self, session_id: str) -> None:
+        """
+        Clear session messages.
+
+        Args:
+            session_id: Session ID
+        """
+        if session_id in self._sessions:
+            self._sessions[session_id].clear()
+            logger.debug(f"Session {session_id} cleared")
+
+    def delete_session(self, session_id: str) -> None:
+        """
+        Delete session.
+
+        Args:
+            session_id: Session ID
+        """
+        if session_id in self._sessions:
+            del self._sessions[session_id]
+            logger.debug(f"Session {session_id} deleted")
+
+    def get_session(self, session_id: str) -> Optional[Session]:
+        """
+        Get session object.
+
+        Args:
+            session_id: Session ID
+
+        Returns:
+            Session or None
+        """
+        return self._sessions.get(session_id)
+
+    def list_sessions(self) -> List[str]:
+        """List all session IDs."""
+        return list(self._sessions.keys())
+
+    def _cleanup_old_sessions(self) -> None:
+        """Remove oldest sessions to maintain limit."""
+        # Sort by last activity
+        sorted_sessions = sorted(
+            self._sessions.items(),
+            key=lambda x: x[1].last_activity
+        )
+
+        # Remove oldest sessions
+        num_to_remove = len(self._sessions) - self.max_sessions
+        for session_id, _ in sorted_sessions[:num_to_remove]:
+            del self._sessions[session_id]
+            logger.debug(f"Removed old session {session_id}")
+
+    def get_stats(self) -> Dict:
+        """Get memory statistics."""
+        return {
+            "agent_id": self.agent_id,
+            "total_sessions": len(self._sessions),
+            "total_messages": sum(len(s.messages) for s in self._sessions.values()),
+        }
+

aiecs/domain/agent/migration/__init__.py

@@ -0,0 +1,15 @@
+"""
+Migration Utilities
+
+Tools for migrating from legacy agents and LangChain to BaseAIAgent.
+"""
+
+from .legacy_wrapper import LegacyAgentWrapper
+from .conversion import convert_langchain_prompt, convert_legacy_config
+
+__all__ = [
+    "LegacyAgentWrapper",
+    "convert_langchain_prompt",
+    "convert_legacy_config",
+]
+