aiecs 1.5.1__py3-none-any.whl

aiecs/domain/agent/observability.py

@@ -0,0 +1,407 @@
+"""
+Agent Observability
+
+Observer pattern and controllers for monitoring agent behavior.
+"""
+
+import logging
+from typing import Dict, Any, List, Protocol
+from datetime import datetime
+
+from .base_agent import BaseAIAgent
+from .models import AgentState
+
+logger = logging.getLogger(__name__)
+
+
+class AgentObserver(Protocol):
+    """Protocol for observing agent events."""
+
+    def on_state_changed(
+        self,
+        agent_id: str,
+        old_state: AgentState,
+        new_state: AgentState,
+        timestamp: datetime,
+    ) -> None:
+        """
+        Called when agent state changes.
+
+        Args:
+            agent_id: Agent identifier
+            old_state: Previous state
+            new_state: New state
+            timestamp: Change timestamp
+        """
+        ...
+
+    def on_task_started(
+        self,
+        agent_id: str,
+        task_id: str,
+        task: Dict[str, Any],
+        timestamp: datetime,
+    ) -> None:
+        """
+        Called when agent starts a task.
+
+        Args:
+            agent_id: Agent identifier
+            task_id: Task identifier
+            task: Task specification
+            timestamp: Start timestamp
+        """
+        ...
+
+    def on_task_completed(
+        self,
+        agent_id: str,
+        task_id: str,
+        result: Dict[str, Any],
+        timestamp: datetime,
+    ) -> None:
+        """
+        Called when agent completes a task.
+
+        Args:
+            agent_id: Agent identifier
+            task_id: Task identifier
+            result: Task result
+            timestamp: Completion timestamp
+        """
+        ...
+
+    def on_task_failed(
+        self,
+        agent_id: str,
+        task_id: str,
+        error: Exception,
+        timestamp: datetime,
+    ) -> None:
+        """
+        Called when agent task fails.
+
+        Args:
+            agent_id: Agent identifier
+            task_id: Task identifier
+            error: Error that occurred
+            timestamp: Failure timestamp
+        """
+        ...
+
+    def on_tool_called(
+        self,
+        agent_id: str,
+        tool_name: str,
+        parameters: Dict[str, Any],
+        timestamp: datetime,
+    ) -> None:
+        """
+        Called when agent calls a tool.
+
+        Args:
+            agent_id: Agent identifier
+            tool_name: Tool name
+            parameters: Tool parameters
+            timestamp: Call timestamp
+        """
+        ...
+
+
+class LoggingObserver:
+    """Observer that logs agent events."""
+
+    def __init__(self, log_level: int = logging.INFO):
+        """
+        Initialize logging observer.
+
+        Args:
+            log_level: Logging level
+        """
+        self.logger = logging.getLogger(f"{__name__}.LoggingObserver")
+        self.log_level = log_level
+
+    def on_state_changed(
+        self,
+        agent_id: str,
+        old_state: AgentState,
+        new_state: AgentState,
+        timestamp: datetime,
+    ) -> None:
+        """Log state change."""
+        self.logger.log(
+            self.log_level,
+            f"Agent {agent_id}: {old_state.value} → {new_state.value}",
+        )
+
+    def on_task_started(
+        self,
+        agent_id: str,
+        task_id: str,
+        task: Dict[str, Any],
+        timestamp: datetime,
+    ) -> None:
+        """Log task start."""
+        self.logger.log(self.log_level, f"Agent {agent_id}: Task {task_id} started")
+
+    def on_task_completed(
+        self,
+        agent_id: str,
+        task_id: str,
+        result: Dict[str, Any],
+        timestamp: datetime,
+    ) -> None:
+        """Log task completion."""
+        self.logger.log(self.log_level, f"Agent {agent_id}: Task {task_id} completed")
+
+    def on_task_failed(
+        self,
+        agent_id: str,
+        task_id: str,
+        error: Exception,
+        timestamp: datetime,
+    ) -> None:
+        """Log task failure."""
+        self.logger.log(
+            self.log_level,
+            f"Agent {agent_id}: Task {task_id} failed - {str(error)}",
+        )
+
+    def on_tool_called(
+        self,
+        agent_id: str,
+        tool_name: str,
+        parameters: Dict[str, Any],
+        timestamp: datetime,
+    ) -> None:
+        """Log tool call."""
+        self.logger.log(self.log_level, f"Agent {agent_id}: Tool '{tool_name}' called")
+
+
+class MetricsObserver:
+    """Observer that collects metrics."""
+
+    def __init__(self):
+        """Initialize metrics observer."""
+        self.state_changes: List[Dict[str, Any]] = []
+        self.task_events: List[Dict[str, Any]] = []
+        self.tool_calls: List[Dict[str, Any]] = []
+
+    def on_state_changed(
+        self,
+        agent_id: str,
+        old_state: AgentState,
+        new_state: AgentState,
+        timestamp: datetime,
+    ) -> None:
+        """Record state change."""
+        self.state_changes.append(
+            {
+                "agent_id": agent_id,
+                "old_state": old_state.value,
+                "new_state": new_state.value,
+                "timestamp": timestamp.isoformat(),
+            }
+        )
+
+    def on_task_started(
+        self,
+        agent_id: str,
+        task_id: str,
+        task: Dict[str, Any],
+        timestamp: datetime,
+    ) -> None:
+        """Record task start."""
+        self.task_events.append(
+            {
+                "agent_id": agent_id,
+                "task_id": task_id,
+                "event": "started",
+                "timestamp": timestamp.isoformat(),
+            }
+        )
+
+    def on_task_completed(
+        self,
+        agent_id: str,
+        task_id: str,
+        result: Dict[str, Any],
+        timestamp: datetime,
+    ) -> None:
+        """Record task completion."""
+        self.task_events.append(
+            {
+                "agent_id": agent_id,
+                "task_id": task_id,
+                "event": "completed",
+                "timestamp": timestamp.isoformat(),
+            }
+        )
+
+    def on_task_failed(
+        self,
+        agent_id: str,
+        task_id: str,
+        error: Exception,
+        timestamp: datetime,
+    ) -> None:
+        """Record task failure."""
+        self.task_events.append(
+            {
+                "agent_id": agent_id,
+                "task_id": task_id,
+                "event": "failed",
+                "error": str(error),
+                "timestamp": timestamp.isoformat(),
+            }
+        )
+
+    def on_tool_called(
+        self,
+        agent_id: str,
+        tool_name: str,
+        parameters: Dict[str, Any],
+        timestamp: datetime,
+    ) -> None:
+        """Record tool call."""
+        self.tool_calls.append(
+            {
+                "agent_id": agent_id,
+                "tool_name": tool_name,
+                "timestamp": timestamp.isoformat(),
+            }
+        )
+
+    def get_metrics(self) -> Dict[str, Any]:
+        """Get collected metrics."""
+        return {
+            "state_changes": len(self.state_changes),
+            "task_events": len(self.task_events),
+            "tool_calls": len(self.tool_calls),
+            "state_changes_data": self.state_changes,
+            "task_events_data": self.task_events,
+            "tool_calls_data": self.tool_calls,
+        }
+
+    def clear(self) -> None:
+        """Clear all metrics."""
+        self.state_changes.clear()
+        self.task_events.clear()
+        self.tool_calls.clear()
+
+
+class AgentController:
+    """
+    Controller for managing agent execution and monitoring.
+
+    Integrates with observers for event tracking.
+    """
+
+    def __init__(self, agent: BaseAIAgent):
+        """
+        Initialize agent controller.
+
+        Args:
+            agent: Agent to control
+        """
+        self.agent = agent
+        self.observers: List[AgentObserver] = []
+        logger.info(f"AgentController initialized for agent {agent.agent_id}")
+
+    def add_observer(self, observer: AgentObserver) -> None:
+        """
+        Add an observer.
+
+        Args:
+            observer: Observer to add
+        """
+        self.observers.append(observer)
+        logger.debug(f"Observer added to agent {self.agent.agent_id}")
+
+    def remove_observer(self, observer: AgentObserver) -> None:
+        """
+        Remove an observer.
+
+        Args:
+            observer: Observer to remove
+        """
+        if observer in self.observers:
+            self.observers.remove(observer)
+            logger.debug(f"Observer removed from agent {self.agent.agent_id}")
+
+    def notify_state_changed(self, old_state: AgentState, new_state: AgentState) -> None:
+        """Notify observers of state change."""
+        timestamp = datetime.utcnow()
+        for observer in self.observers:
+            try:
+                observer.on_state_changed(self.agent.agent_id, old_state, new_state, timestamp)
+            except Exception as e:
+                logger.error(f"Observer notification failed: {e}")
+
+    def notify_task_started(self, task_id: str, task: Dict[str, Any]) -> None:
+        """Notify observers of task start."""
+        timestamp = datetime.utcnow()
+        for observer in self.observers:
+            try:
+                observer.on_task_started(self.agent.agent_id, task_id, task, timestamp)
+            except Exception as e:
+                logger.error(f"Observer notification failed: {e}")
+
+    def notify_task_completed(self, task_id: str, result: Dict[str, Any]) -> None:
+        """Notify observers of task completion."""
+        timestamp = datetime.utcnow()
+        for observer in self.observers:
+            try:
+                observer.on_task_completed(self.agent.agent_id, task_id, result, timestamp)
+            except Exception as e:
+                logger.error(f"Observer notification failed: {e}")
+
+    def notify_task_failed(self, task_id: str, error: Exception) -> None:
+        """Notify observers of task failure."""
+        timestamp = datetime.utcnow()
+        for observer in self.observers:
+            try:
+                observer.on_task_failed(self.agent.agent_id, task_id, error, timestamp)
+            except Exception as e:
+                logger.error(f"Observer notification failed: {e}")
+
+    def notify_tool_called(self, tool_name: str, parameters: Dict[str, Any]) -> None:
+        """Notify observers of tool call."""
+        timestamp = datetime.utcnow()
+        for observer in self.observers:
+            try:
+                observer.on_tool_called(self.agent.agent_id, tool_name, parameters, timestamp)
+            except Exception as e:
+                logger.error(f"Observer notification failed: {e}")
+
+    async def execute_task_with_observation(
+        self, task: Dict[str, Any], context: Dict[str, Any]
+    ) -> Dict[str, Any]:
+        """
+        Execute task with observer notifications.
+
+        Args:
+            task: Task specification
+            context: Execution context
+
+        Returns:
+            Task result
+        """
+        task_id = task.get("task_id", f"task_{datetime.utcnow().timestamp()}")
+
+        # Notify start
+        self.notify_task_started(task_id, task)
+
+        try:
+            # Execute task
+            result = await self.agent.execute_task(task, context)
+
+            # Notify completion
+            self.notify_task_completed(task_id, result)
+
+            return result
+
+        except Exception as e:
+            # Notify failure
+            self.notify_task_failed(task_id, e)
+            raise

aiecs/domain/agent/persistence.py

@@ -0,0 +1,289 @@
+"""
+Agent Persistence
+
+Interfaces and implementations for saving/loading agent state.
+"""
+
+import logging
+import json
+from typing import Dict, Any, Optional, Protocol
+from datetime import datetime
+
+from .base_agent import BaseAIAgent
+from .exceptions import SerializationError
+
+logger = logging.getLogger(__name__)
+
+
+class AgentPersistence(Protocol):
+    """Protocol for agent persistence implementations."""
+
+    async def save(self, agent: BaseAIAgent) -> None:
+        """
+        Save agent state.
+
+        Args:
+            agent: Agent to save
+        """
+        ...
+
+    async def load(self, agent_id: str) -> Dict[str, Any]:
+        """
+        Load agent state.
+
+        Args:
+            agent_id: Agent identifier
+
+        Returns:
+            Agent state dictionary
+        """
+        ...
+
+    async def exists(self, agent_id: str) -> bool:
+        """
+        Check if agent state exists.
+
+        Args:
+            agent_id: Agent identifier
+
+        Returns:
+            True if exists
+        """
+        ...
+
+    async def delete(self, agent_id: str) -> None:
+        """
+        Delete agent state.
+
+        Args:
+            agent_id: Agent identifier
+        """
+        ...
+
+
+class InMemoryPersistence:
+    """In-memory agent persistence (for testing/development)."""
+
+    def __init__(self):
+        """Initialize in-memory storage."""
+        self._storage: Dict[str, Dict[str, Any]] = {}
+        logger.info("InMemoryPersistence initialized")
+
+    async def save(self, agent: BaseAIAgent) -> None:
+        """Save agent state to memory."""
+        try:
+            state = agent.to_dict()
+            # Convert any remaining datetime objects to ISO strings
+            state = self._serialize_datetimes(state)
+            self._storage[agent.agent_id] = {
+                "state": state,
+                "saved_at": datetime.utcnow().isoformat(),
+            }
+            logger.debug(f"Agent {agent.agent_id} saved to memory")
+        except Exception as e:
+            logger.error(f"Failed to save agent {agent.agent_id}: {e}")
+            raise SerializationError(f"Failed to save agent: {str(e)}")
+
+    def _serialize_datetimes(self, obj: Any) -> Any:
+        """Recursively serialize datetime objects to ISO strings."""
+        if isinstance(obj, dict):
+            return {k: self._serialize_datetimes(v) for k, v in obj.items()}
+        elif isinstance(obj, list):
+            return [self._serialize_datetimes(item) for item in obj]
+        elif isinstance(obj, datetime):
+            return obj.isoformat()
+        else:
+            return obj
+
+    async def load(self, agent_id: str) -> Dict[str, Any]:
+        """Load agent state from memory."""
+        if agent_id not in self._storage:
+            raise KeyError(f"Agent {agent_id} not found in storage")
+
+        data = self._storage[agent_id]
+        logger.debug(f"Agent {agent_id} loaded from memory")
+        return data["state"]
+
+    async def exists(self, agent_id: str) -> bool:
+        """Check if agent exists in memory."""
+        return agent_id in self._storage
+
+    async def delete(self, agent_id: str) -> None:
+        """Delete agent from memory."""
+        if agent_id in self._storage:
+            del self._storage[agent_id]
+            logger.debug(f"Agent {agent_id} deleted from memory")
+
+    def clear(self) -> None:
+        """Clear all stored agents."""
+        self._storage.clear()
+        logger.info("InMemoryPersistence cleared")
+
+
+class FilePersistence:
+    """File-based agent persistence."""
+
+    def __init__(self, base_path: str = "./agent_states"):
+        """
+        Initialize file-based storage.
+
+        Args:
+            base_path: Base directory for agent states
+        """
+        import os
+
+        self.base_path = base_path
+        os.makedirs(base_path, exist_ok=True)
+        logger.info(f"FilePersistence initialized with base_path: {base_path}")
+
+    def _get_file_path(self, agent_id: str) -> str:
+        """Get file path for agent."""
+        import os
+
+        # Sanitize agent_id for filesystem
+        safe_id = agent_id.replace("/", "_").replace("\\", "_")
+        return os.path.join(self.base_path, f"{safe_id}.json")
+
+    async def save(self, agent: BaseAIAgent) -> None:
+        """Save agent state to file."""
+        try:
+            state = agent.to_dict()
+            # Convert any remaining datetime objects to ISO strings for JSON
+            # serialization
+            state = self._serialize_datetimes(state)
+            file_path = self._get_file_path(agent.agent_id)
+
+            data = {
+                "state": state,
+                "saved_at": datetime.utcnow().isoformat(),
+            }
+
+            with open(file_path, "w") as f:
+                # default=str handles any remaining non-serializable objects
+                json.dump(data, f, indent=2, default=str)
+
+            logger.debug(f"Agent {agent.agent_id} saved to {file_path}")
+        except Exception as e:
+            logger.error(f"Failed to save agent {agent.agent_id}: {e}")
+            raise SerializationError(f"Failed to save agent: {str(e)}")
+
+    def _serialize_datetimes(self, obj: Any) -> Any:
+        """Recursively serialize datetime objects to ISO strings."""
+        if isinstance(obj, dict):
+            return {k: self._serialize_datetimes(v) for k, v in obj.items()}
+        elif isinstance(obj, list):
+            return [self._serialize_datetimes(item) for item in obj]
+        elif isinstance(obj, datetime):
+            return obj.isoformat()
+        else:
+            return obj
+
+    async def load(self, agent_id: str) -> Dict[str, Any]:
+        """Load agent state from file."""
+        file_path = self._get_file_path(agent_id)
+
+        try:
+            with open(file_path, "r") as f:
+                data = json.load(f)
+
+            logger.debug(f"Agent {agent_id} loaded from {file_path}")
+            return data["state"]
+        except FileNotFoundError:
+            raise KeyError(f"Agent {agent_id} not found in storage")
+        except Exception as e:
+            logger.error(f"Failed to load agent {agent_id}: {e}")
+            raise SerializationError(f"Failed to load agent: {str(e)}")
+
+    async def exists(self, agent_id: str) -> bool:
+        """Check if agent file exists."""
+        import os
+
+        file_path = self._get_file_path(agent_id)
+        return os.path.exists(file_path)
+
+    async def delete(self, agent_id: str) -> None:
+        """Delete agent file."""
+        import os
+
+        file_path = self._get_file_path(agent_id)
+
+        try:
+            if os.path.exists(file_path):
+                os.remove(file_path)
+                logger.debug(f"Agent {agent_id} deleted from {file_path}")
+        except Exception as e:
+            logger.error(f"Failed to delete agent {agent_id}: {e}")
+            raise
+
+
+class AgentStateSerializer:
+    """
+    Helper class for serializing/deserializing agent state.
+
+    Handles complex types that need special serialization.
+    """
+
+    @staticmethod
+    def serialize(agent: BaseAIAgent) -> Dict[str, Any]:
+        """
+        Serialize agent to dictionary.
+
+        Args:
+            agent: Agent to serialize
+
+        Returns:
+            Serialized state dictionary
+        """
+        return agent.to_dict()
+
+    @staticmethod
+    def deserialize(data: Dict[str, Any]) -> Dict[str, Any]:
+        """
+        Deserialize agent state.
+
+        Args:
+            data: Serialized state
+
+        Returns:
+            Deserialized state dictionary
+
+        Note: This returns a state dictionary, not an agent instance.
+        Agent reconstruction requires the appropriate agent class.
+        """
+        # In the future, this could handle type conversion, validation, etc.
+        return data
+
+
+# Global persistence instance
+_global_persistence: Optional[AgentPersistence] = None
+
+
+def get_global_persistence() -> AgentPersistence:
+    """
+    Get or create global persistence instance.
+
+    Returns:
+        Global persistence instance (defaults to InMemoryPersistence)
+    """
+    global _global_persistence
+    if _global_persistence is None:
+        _global_persistence = InMemoryPersistence()
+    return _global_persistence
+
+
+def set_global_persistence(persistence: AgentPersistence) -> None:
+    """
+    Set global persistence instance.
+
+    Args:
+        persistence: Persistence implementation to use
+    """
+    global _global_persistence
+    _global_persistence = persistence
+    logger.info(f"Global persistence set to {type(persistence).__name__}")
+
+
+def reset_global_persistence() -> None:
+    """Reset global persistence (primarily for testing)."""
+    global _global_persistence
+    _global_persistence = None