dacp 0.3.0__py3-none-any.whl → 0.3.2__py3-none-any.whl

dacp/logging_config.py

@@ -0,0 +1,129 @@
+"""
+DACP Logging Configuration
+
+Utilities for configuring logging for DACP components.
+"""
+
+import logging
+import sys
+from typing import Optional
+
+
+def setup_dacp_logging(
+    level: str = "INFO",
+    format_style: str = "detailed",
+    include_timestamp: bool = True,
+    log_file: Optional[str] = None,
+) -> None:
+    """
+    Set up logging for DACP components.
+
+    Args:
+        level: Logging level (DEBUG, INFO, WARNING, ERROR, CRITICAL)
+        format_style: Log format style ('simple', 'detailed', 'emoji')
+        include_timestamp: Whether to include timestamps in logs
+        log_file: Optional file path to also log to a file
+    """
+    # Define format styles
+    if format_style == "simple":
+        if include_timestamp:
+            log_format = "%(asctime)s - %(name)s - %(levelname)s - %(message)s"
+        else:
+            log_format = "%(name)s - %(levelname)s - %(message)s"
+    elif format_style == "detailed":
+        if include_timestamp:
+            log_format = (
+                "%(asctime)s - %(name)s:%(lineno)d - %(levelname)s - %(message)s"
+            )
+        else:
+            log_format = "%(name)s:%(lineno)d - %(levelname)s - %(message)s"
+    elif format_style == "emoji":
+        # Emoji format doesn't include logger name since emojis provide context
+        if include_timestamp:
+            log_format = "%(asctime)s - %(message)s"
+        else:
+            log_format = "%(message)s"
+    else:
+        raise ValueError(f"Unknown format_style: {format_style}")
+
+    # Configure root logger for DACP components
+    logger = logging.getLogger("dacp")
+    logger.setLevel(getattr(logging, level.upper()))
+
+    # Remove existing handlers to avoid duplicates
+    for handler in logger.handlers[:]:
+        logger.removeHandler(handler)
+
+    # Create formatter
+    formatter = logging.Formatter(
+        log_format, datefmt="%Y-%m-%d %H:%M:%S" if include_timestamp else None
+    )
+
+    # Console handler
+    console_handler = logging.StreamHandler(sys.stdout)
+    console_handler.setFormatter(formatter)
+    logger.addHandler(console_handler)
+
+    # Optional file handler
+    if log_file:
+        file_handler = logging.FileHandler(log_file)
+        file_handler.setFormatter(formatter)
+        logger.addHandler(file_handler)
+
+    # Prevent propagation to root logger to avoid duplicate messages
+    logger.propagate = False
+
+    logger.info(f"🚀 DACP logging configured: level={level}, style={format_style}")
+
+
+def set_dacp_log_level(level: str) -> None:
+    """
+    Set the log level for all DACP components.
+
+    Args:
+        level: Logging level (DEBUG, INFO, WARNING, ERROR, CRITICAL)
+    """
+    logger = logging.getLogger("dacp")
+    logger.setLevel(getattr(logging, level.upper()))
+    logger.info(f"📊 DACP log level changed to {level}")
+
+
+def disable_dacp_logging() -> None:
+    """Disable all DACP logging."""
+    logger = logging.getLogger("dacp")
+    logger.disabled = True
+
+
+def enable_dacp_logging() -> None:
+    """Re-enable DACP logging."""
+    logger = logging.getLogger("dacp")
+    logger.disabled = False
+
+
+def get_dacp_logger(name: str) -> logging.Logger:
+    """
+    Get a logger for a DACP component.
+
+    Args:
+        name: Logger name (usually __name__)
+
+    Returns:
+        Configured logger
+    """
+    return logging.getLogger(f"dacp.{name}")
+
+
+# Convenience functions for quick setup
+def enable_debug_logging(log_file: Optional[str] = None) -> None:
+    """Enable debug logging with detailed format."""
+    setup_dacp_logging(level="DEBUG", format_style="detailed", log_file=log_file)
+
+
+def enable_info_logging(log_file: Optional[str] = None) -> None:
+    """Enable info logging with emoji format."""
+    setup_dacp_logging(level="INFO", format_style="emoji", log_file=log_file)
+
+
+def enable_quiet_logging() -> None:
+    """Enable only error and critical logging."""
+    setup_dacp_logging(level="ERROR", format_style="simple", include_timestamp=False)

dacp/main.py

@@ -1,15 +1,9 @@
-from dacp.orchestrator import Orchestrator
+#!/usr/bin/env python3
+"""
+DACP Main Entry Point
 
-def main():
-    orchestrator = Orchestrator()
+This module provides examples and testing functionality for DACP.
+"""
 
-    # Agent registers itself with the orchestrator
-    hello_agent = HelloWorldAgent("hello_agent", orchestrator)
-
-    # Orchestrator sends a message to the agent and prints the response
-    input_message = {"name": "Alice"}
-    response = orchestrator.call_agent("hello_agent", input_message)
-    print("Orchestrator received:", response)
-
-if __name__ == "__main__":
-    main()
+print("DACP - Declarative Agent Communication Protocol")
+print("For examples, see the examples/ directory")

dacp/orchestrator.py

@@ -1,260 +1,284 @@
 """
-DACP Orchestrator - Manages agent registration and message routing.
+DACP Orchestrator - Agent management and message routing.
+
+This module provides the core orchestrator functionality for managing agents
+and routing messages between them.
 """
 
 import logging
-from typing import Dict, Any, Optional, List, Callable
-import uuid
-import json
-from .protocol import (
-    parse_agent_response,
-    is_tool_request,
-    get_tool_request,
-    wrap_tool_result,
-    is_final_response,
-    get_final_response,
-)
-from .tools import run_tool
-
-log = logging.getLogger(__name__)
+import time
+from typing import Dict, Any, List, Optional
+
+from .tools import execute_tool
+
+logger = logging.getLogger("dacp.orchestrator")
 
 
 class Agent:
-    """Base agent interface that all agents should implement."""
-    
+    """
+    Base agent class that all DACP agents should inherit from.
+
+    This provides the standard interface for agent communication.
+    """
+
     def handle_message(self, message: Dict[str, Any]) -> Dict[str, Any]:
-        """Handle incoming messages from the orchestrator."""
+        """
+        Handle incoming messages.
+
+        Args:
+            message: Message dictionary containing task and parameters
+
+        Returns:
+            Response dictionary with either 'response', 'tool_request', or 'error'
+        """
         raise NotImplementedError("Agents must implement handle_message method")
 
 
 class Orchestrator:
     """
     Central orchestrator for managing agents and routing messages.
-    Handles agent registration, message routing, and tool execution.
+
+    The orchestrator handles agent registration, message routing, tool execution,
+    and conversation history management.
     """
-    
-    def __init__(self):
-        self.agents: Dict[str, Any] = {}
+
+    def __init__(self, session_id: Optional[str] = None):
+        """Initialize orchestrator with optional session ID."""
+        self.agents: Dict[str, Agent] = {}
+        self.session_id = session_id or f"session_{int(time.time())}"
         self.conversation_history: List[Dict[str, Any]] = []
-        self.session_id = str(uuid.uuid4())
-        
-    def register_agent(self, agent_id: str, agent: Any) -> None:
+
+        logger.info(f"🎭 Orchestrator initialized with session ID: {self.session_id}")
+
+    def register_agent(self, name: str, agent: Agent) -> None:
         """
         Register an agent with the orchestrator.
-        
+
         Args:
-            agent_id: Unique identifier for the agent
-            agent: Agent instance that implements handle_message method
+            name: Unique name for the agent
+            agent: Agent instance implementing the Agent interface
         """
-        if not hasattr(agent, 'handle_message'):
-            raise ValueError(f"Agent {agent_id} must implement handle_message method")
-        
-        self.agents[agent_id] = agent
-        log.info(f"Registered agent: {agent_id}")
-        
-    def unregister_agent(self, agent_id: str) -> bool:
+        if not isinstance(agent, Agent):
+            raise ValueError("Agent must inherit from dacp.Agent base class")
+
+        self.agents[name] = agent
+        logger.info(
+            f"✅ Agent '{name}' registered successfully "
+            f"(type: {type(agent).__name__})"
+        )
+        logger.debug(f"📊 Total registered agents: {len(self.agents)}")
+
+    def unregister_agent(self, name: str) -> bool:
         """
         Unregister an agent from the orchestrator.
-        
+
         Args:
-            agent_id: ID of the agent to unregister
-            
+            name: Name of the agent to unregister
+
         Returns:
-            True if agent was found and removed, False otherwise
+            True if agent was unregistered, False if not found
         """
-        if agent_id in self.agents:
-            del self.agents[agent_id]
-            log.info(f"Unregistered agent: {agent_id}")
+        if name in self.agents:
+            del self.agents[name]
+            logger.info(f"🗑️  Agent '{name}' unregistered successfully")
+            logger.debug(f"📊 Remaining agents: {len(self.agents)}")
             return True
-        return False
-        
-    def get_agent(self, agent_id: str) -> Optional[Any]:
-        """Get an agent by ID."""
-        return self.agents.get(agent_id)
-        
+        else:
+            logger.warning(f"⚠️  Agent '{name}' not found for unregistration")
+            return False
+
     def list_agents(self) -> List[str]:
-        """Get list of registered agent IDs."""
+        """Get list of registered agent names."""
         return list(self.agents.keys())
-        
-    def send_message(self, agent_id: str, message: Dict[str, Any]) -> Dict[str, Any]:
+
+    def send_message(self, agent_name: str, message: Dict[str, Any]) -> Dict[str, Any]:
         """
         Send a message to a specific agent.
-        
+
         Args:
-            agent_id: ID of the target agent
-            message: Message to send
-            
+            agent_name: Name of the target agent
+            message: Message dictionary to send
+
         Returns:
-            Response from the agent
-            
-        Raises:
-            ValueError: If agent_id is not found
+            Response from the agent after processing
         """
-        if agent_id not in self.agents:
-            raise ValueError(f"Agent {agent_id} not found")
-            
-        agent = self.agents[agent_id]
-        
-        # Add metadata to message
-        enriched_message = {
-            "session_id": self.session_id,
-            "timestamp": self._get_timestamp(),
-            **message
-        }
-        
+        start_time = time.time()
+
+        logger.info(f"📨 Sending message to agent '{agent_name}'")
+        logger.debug(f"📋 Message content: {message}")
+
+        if agent_name not in self.agents:
+            error_msg = f"Agent '{agent_name}' not found"
+            logger.error(f"❌ {error_msg}")
+            return {"error": error_msg}
+
+        agent = self.agents[agent_name]
+
         try:
-            # Send message to agent
-            response = agent.handle_message(enriched_message)
-            
-            # Log the interaction
-            self.conversation_history.append({
-                "type": "message",
-                "agent_id": agent_id,
-                "message": enriched_message,
-                "response": response,
-                "timestamp": self._get_timestamp()
-            })
-            
+            logger.debug(f"🔄 Calling handle_message on agent '{agent_name}'")
+
+            # Call the agent's message handler
+            response = agent.handle_message(message)
+
+            duration = time.time() - start_time
+            logger.info(f"✅ Agent '{agent_name}' responded in {duration:.3f}s")
+            logger.debug(f"📤 Agent response: {response}")
+
+            # Check if agent requested tool execution
+            if isinstance(response, dict) and "tool_request" in response:
+                logger.info(f"🔧 Agent '{agent_name}' requested tool execution")
+                response = self._handle_tool_request(
+                    agent_name, response["tool_request"]
+                )
+
+            # Log the conversation
+            self._log_conversation(agent_name, message, response, duration)
+
             return response
-            
+
         except Exception as e:
-            error_response = {
-                "error": f"Agent {agent_id} failed to handle message: {str(e)}",
-                "agent_id": agent_id
-            }
-            log.error(f"Error sending message to agent {agent_id}: {e}")
+            duration = time.time() - start_time
+            error_msg = f"Error in agent '{agent_name}': {type(e).__name__}: {e}"
+            logger.error(f"❌ {error_msg}")
+            logger.debug("💥 Exception details", exc_info=True)
+
+            error_response = {"error": error_msg}
+            self._log_conversation(agent_name, message, error_response, duration)
+
             return error_response
-            
-    def broadcast_message(self, message: Dict[str, Any], exclude_agents: List[str] = None) -> Dict[str, Dict[str, Any]]:
+
+    def broadcast_message(self, message: Dict[str, Any]) -> Dict[str, Any]:
         """
-        Broadcast a message to all registered agents.
-        
+        Send a message to all registered agents.
+
         Args:
-            message: Message to broadcast
-            exclude_agents: List of agent IDs to exclude from broadcast
-            
+            message: Message dictionary to broadcast
+
         Returns:
-            Dictionary mapping agent_id to response
+            Dictionary mapping agent names to their responses
         """
-        exclude_agents = exclude_agents or []
+        logger.info(f"📢 Broadcasting message to {len(self.agents)} agents")
+        logger.debug(f"📋 Broadcast message: {message}")
+
         responses = {}
-        
-        for agent_id in self.agents:
-            if agent_id not in exclude_agents:
-                try:
-                    responses[agent_id] = self.send_message(agent_id, message)
-                except Exception as e:
-                    responses[agent_id] = {"error": str(e)}
-                    
+        start_time = time.time()
+
+        for agent_name in self.agents:
+            logger.debug(f"📨 Broadcasting to agent '{agent_name}'")
+            responses[agent_name] = self.send_message(agent_name, message)
+
+        duration = time.time() - start_time
+        logger.info(
+            f"✅ Broadcast completed in {duration:.3f}s "
+            f"({len(responses)} responses)"
+        )
+
         return responses
-        
-    def handle_tool_request(self, tool_name: str, args: Dict[str, Any]) -> Dict[str, Any]:
-        """
-        Handle a tool execution request.
-        
-        Args:
-            tool_name: Name of the tool to execute
-            args: Arguments for the tool
-            
-        Returns:
-            Tool execution result wrapped in protocol format
-        """
-        try:
-            result = run_tool(tool_name, args)
-            return wrap_tool_result(tool_name, result)
-        except Exception as e:
-            error_result = {
-                "success": False,
-                "error": str(e),
-                "tool_name": tool_name,
-                "args": args
-            }
-            return wrap_tool_result(tool_name, error_result)
-            
-    def process_agent_response(self, agent_id: str, response: Any) -> Dict[str, Any]:
+
+    def _handle_tool_request(
+        self, agent_name: str, tool_request: Dict[str, Any]
+    ) -> Dict[str, Any]:
         """
-        Process an agent response, handling tool requests and final responses.
-        
+        Handle tool execution request from an agent.
+
         Args:
-            agent_id: ID of the agent that sent the response
-            response: Agent response (string or dict)
-            
+            agent_name: Name of the requesting agent
+            tool_request: Tool request dictionary with 'name' and 'args'
+
         Returns:
-            Processed response
+            Tool execution result
         """
+        tool_name = tool_request.get("name")
+        tool_args = tool_request.get("args", {})
+
+        if not tool_name:
+            return {"error": "Tool name is required"}
+
+        logger.info(f"🛠️  Executing tool: '{tool_name}' with args: {tool_args}")
+
+        start_time = time.time()
+
         try:
-            # Parse the agent response
-            parsed_response = parse_agent_response(response)
-            
-            # Check if it's a tool request
-            if is_tool_request(parsed_response):
-                tool_name, args = get_tool_request(parsed_response)
-                log.info(f"Agent {agent_id} requested tool: {tool_name}")
-                
-                # Execute the tool
-                tool_result = self.handle_tool_request(tool_name, args)
-                
-                # Log tool execution
-                self.conversation_history.append({
-                    "type": "tool_execution",
-                    "agent_id": agent_id,
-                    "tool_name": tool_name,
-                    "args": args,
-                    "result": tool_result,
-                    "timestamp": self._get_timestamp()
-                })
-                
-                return tool_result
-                
-            # Check if it's a final response
-            elif is_final_response(parsed_response):
-                final_response = get_final_response(parsed_response)
-                log.info(f"Agent {agent_id} sent final response")
-                return final_response
-                
-            else:
-                # Return the parsed response as-is
-                return parsed_response
-                
+            result = execute_tool(tool_name, tool_args)
+            duration = time.time() - start_time
+
+            logger.info(
+                f"✅ Tool '{tool_name}' executed successfully in {duration:.3f}s"
+            )
+            logger.debug(f"🔧 Tool result: {result}")
+
+            return {"tool_result": {"name": tool_name, "result": result}}
+
         except Exception as e:
-            log.error(f"Error processing agent response from {agent_id}: {e}")
-            return {
-                "error": f"Failed to process response: {str(e)}",
-                "original_response": response
-            }
-            
-    def get_conversation_history(self, agent_id: str = None) -> List[Dict[str, Any]]:
+            duration = time.time() - start_time
+            error_msg = f"Tool '{tool_name}' failed: {type(e).__name__}: {e}"
+            logger.error(f"❌ {error_msg}")
+
+            return {"error": error_msg}
+
+    def _log_conversation(
+        self,
+        agent_name: str,
+        message: Dict[str, Any],
+        response: Dict[str, Any],
+        duration: float,
+    ) -> None:
+        """Log conversation entry to history."""
+        logger.debug("💾 Logging conversation entry")
+
+        entry = {
+            "timestamp": time.time(),
+            "session_id": self.session_id,
+            "agent_name": agent_name,
+            "message": message,
+            "response": response,
+            "duration": duration,
+        }
+
+        self.conversation_history.append(entry)
+
+        # Keep history manageable (last 1000 entries)
+        if len(self.conversation_history) > 1000:
+            self.conversation_history = self.conversation_history[-1000:]
+            logger.debug("🗂️  Conversation history trimmed to 1000 entries")
+
+    def get_conversation_history(
+        self, limit: Optional[int] = None
+    ) -> List[Dict[str, Any]]:
         """
-        Get conversation history, optionally filtered by agent.
-        
+        Get conversation history.
+
         Args:
-            agent_id: Optional agent ID to filter by
-            
+            limit: Maximum number of entries to return (None for all)
+
         Returns:
             List of conversation entries
         """
-        if agent_id:
-            return [
-                entry for entry in self.conversation_history 
-                if entry.get("agent_id") == agent_id
-            ]
-        return self.conversation_history.copy()
-        
-    def clear_history(self) -> None:
+        if limit is None:
+            return self.conversation_history.copy()
+        else:
+            return self.conversation_history[-limit:].copy()
+
+    def clear_conversation_history(self) -> None:
         """Clear conversation history."""
         self.conversation_history.clear()
-        log.info("Conversation history cleared")
-        
-    def get_session_info(self) -> Dict[str, Any]:
-        """Get current session information."""
+        logger.info("🗑️  Conversation history cleared")
+
+    def get_session_metadata(self) -> Dict[str, Any]:
+        """Get session metadata and statistics."""
         return {
             "session_id": self.session_id,
-            "registered_agents": self.list_agents(),
-            "conversation_length": len(self.conversation_history),
-            "timestamp": self._get_timestamp()
+            "registered_agents": len(self.agents),
+            "agent_names": list(self.agents.keys()),
+            "conversation_entries": len(self.conversation_history),
+            "start_time": (
+                self.conversation_history[0]["timestamp"]
+                if self.conversation_history
+                else None
+            ),
+            "last_activity": (
+                self.conversation_history[-1]["timestamp"]
+                if self.conversation_history
+                else None
+            ),
         }
-        
-    def _get_timestamp(self) -> str:
-        """Get current timestamp in ISO format."""
-        from datetime import datetime
-        return datetime.utcnow().isoformat() + "Z"