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

dacp/__init__.py

@@ -17,22 +17,43 @@ from .tools import (
 from .llm import call_llm
 from .intelligence import invoke_intelligence
 from .orchestrator import Orchestrator, Agent
+from .logging_config import (
+    setup_dacp_logging,
+    enable_debug_logging,
+    enable_info_logging,
+    enable_quiet_logging,
+    set_dacp_log_level,
+    disable_dacp_logging,
+    enable_dacp_logging,
+)
 
 __version__ = "0.3.0"
 
 __all__ = [
+    # Protocol functions
     "parse_agent_response",
-    "is_tool_request",
+    "is_tool_request", 
     "get_tool_request",
     "wrap_tool_result",
     "is_final_response",
     "get_final_response",
+    # Tool functions
     "register_tool",
     "run_tool",
     "TOOL_REGISTRY",
     "file_writer",
+    # LLM functions
     "call_llm",
     "invoke_intelligence",
+    # Agent orchestration
     "Orchestrator",
     "Agent",
+    # Logging configuration
+    "setup_dacp_logging",
+    "enable_debug_logging",
+    "enable_info_logging",
+    "enable_quiet_logging",
+    "set_dacp_log_level",
+    "disable_dacp_logging",
+    "enable_dacp_logging",
 ]

dacp/intelligence.py

@@ -6,7 +6,8 @@ import os
 import logging
 from typing import Dict, Any, Optional
 
-log = logging.getLogger(__name__)
+# Set up logger for this module
+logger = logging.getLogger("dacp.intelligence")
 
 
 class IntelligenceError(Exception):
@@ -42,27 +43,58 @@ def invoke_intelligence(prompt: str, config: Dict[str, Any]) -> str:
     """
     engine = config.get("engine")
     if not engine:
+        logger.error("❌ Missing 'engine' in intelligence configuration")
         raise ConfigurationError("Missing 'engine' in intelligence configuration")
     
     engine = engine.lower()
+    model = config.get("model", "default")
     
-    if engine == "openai":
-        return _invoke_openai(prompt, config)
-    elif engine == "anthropic":
-        return _invoke_anthropic(prompt, config)
-    elif engine == "azure":
-        return _invoke_azure_openai(prompt, config)
-    elif engine == "local":
-        return _invoke_local(prompt, config)
-    else:
-        raise UnsupportedProviderError(f"Unsupported intelligence engine: {engine}")
+    logger.info(f"🧠 Invoking intelligence: engine='{engine}', model='{model}'")
+    logger.debug(f"📋 Prompt length: {len(prompt)} characters")
+    logger.debug(f"⚙️  Full config: {_sanitize_config_for_logging(config)}")
+    
+    import time
+    start_time = time.time()
+    
+    try:
+        if engine == "openai":
+            result = _invoke_openai(prompt, config)
+        elif engine == "anthropic":
+            result = _invoke_anthropic(prompt, config)
+        elif engine == "azure":
+            result = _invoke_azure_openai(prompt, config)
+        elif engine == "local":
+            result = _invoke_local(prompt, config)
+        else:
+            logger.error(f"❌ Unsupported intelligence engine: {engine}")
+            raise UnsupportedProviderError(f"Unsupported intelligence engine: {engine}")
+        
+        execution_time = time.time() - start_time
+        logger.info(f"✅ Intelligence response received in {execution_time:.3f}s (length: {len(result)} chars)")
+        logger.debug(f"📤 Response preview: {result[:100]}{'...' if len(result) > 100 else ''}")
+        
+        return result
+        
+    except (IntelligenceError, UnsupportedProviderError, ConfigurationError):
+        # Re-raise our own exceptions without modification
+        execution_time = time.time() - start_time
+        logger.error(f"❌ Intelligence call failed after {execution_time:.3f}s")
+        raise
+    except Exception as e:
+        execution_time = time.time() - start_time
+        logger.error(f"❌ Unexpected intelligence error after {execution_time:.3f}s: {type(e).__name__}: {e}")
+        raise IntelligenceError(f"Unexpected error: {e}")
 
 
 def _invoke_openai(prompt: str, config: Dict[str, Any]) -> str:
     """Invoke OpenAI provider."""
+    logger.debug("🔵 Initializing OpenAI provider")
+    
     try:
         import openai
+        logger.debug("✅ OpenAI package imported successfully")
     except ImportError:
+        logger.error("❌ OpenAI package not installed")
         raise IntelligenceError("OpenAI package not installed. Run: pip install openai")
     
     model = config.get("model", "gpt-4")
@@ -71,11 +103,17 @@ def _invoke_openai(prompt: str, config: Dict[str, Any]) -> str:
     temperature = config.get("temperature", 0.7)
     max_tokens = config.get("max_tokens", 150)
     
+    logger.debug(f"🔧 OpenAI config: model={model}, base_url={base_url}, temp={temperature}, max_tokens={max_tokens}")
+    
     if not api_key:
+        logger.error("❌ OpenAI API key not found")
         raise ConfigurationError("OpenAI API key not found in config or OPENAI_API_KEY environment variable")
     
     try:
+        logger.debug("🔗 Creating OpenAI client")
         client = openai.OpenAI(api_key=api_key, base_url=base_url)
+        
+        logger.debug("📡 Sending request to OpenAI API")
         response = client.chat.completions.create(
             model=model,
             messages=[{"role": "user", "content": prompt}],
@@ -85,19 +123,26 @@ def _invoke_openai(prompt: str, config: Dict[str, Any]) -> str:
         
         content = response.choices[0].message.content
         if content is None:
+            logger.error("❌ OpenAI returned empty response")
             raise IntelligenceError("OpenAI returned empty response")
+        
+        logger.debug(f"✅ OpenAI API call successful")
         return content
         
     except Exception as e:
-        log.error(f"OpenAI API error: {e}")
+        logger.error(f"❌ OpenAI API error: {type(e).__name__}: {e}")
         raise IntelligenceError(f"OpenAI API error: {e}")
 
 
 def _invoke_anthropic(prompt: str, config: Dict[str, Any]) -> str:
     """Invoke Anthropic (Claude) provider."""
+    logger.debug("🟣 Initializing Anthropic provider")
+    
     try:
         import anthropic
+        logger.debug("✅ Anthropic package imported successfully")
     except ImportError:
+        logger.error("❌ Anthropic package not installed")
         raise IntelligenceError("Anthropic package not installed. Run: pip install anthropic")
     
     model = config.get("model", "claude-3-haiku-20240307")
@@ -106,11 +151,17 @@ def _invoke_anthropic(prompt: str, config: Dict[str, Any]) -> str:
     max_tokens = config.get("max_tokens", 150)
     temperature = config.get("temperature", 0.7)
     
+    logger.debug(f"🔧 Anthropic config: model={model}, base_url={base_url}, temp={temperature}, max_tokens={max_tokens}")
+    
     if not api_key:
+        logger.error("❌ Anthropic API key not found")
         raise ConfigurationError("Anthropic API key not found in config or ANTHROPIC_API_KEY environment variable")
     
     try:
+        logger.debug("🔗 Creating Anthropic client")
         client = anthropic.Anthropic(api_key=api_key, base_url=base_url)
+        
+        logger.debug("📡 Sending request to Anthropic API")
         response = client.messages.create(
             model=model,
             max_tokens=max_tokens,
@@ -119,21 +170,28 @@ def _invoke_anthropic(prompt: str, config: Dict[str, Any]) -> str:
         )
         
         if not response.content or len(response.content) == 0:
+            logger.error("❌ Anthropic returned empty response")
             raise IntelligenceError("Anthropic returned empty response")
         
         # Anthropic returns a list of content blocks
-        return response.content[0].text
+        result = response.content[0].text
+        logger.debug(f"✅ Anthropic API call successful")
+        return result
         
     except Exception as e:
-        log.error(f"Anthropic API error: {e}")
+        logger.error(f"❌ Anthropic API error: {type(e).__name__}: {e}")
         raise IntelligenceError(f"Anthropic API error: {e}")
 
 
 def _invoke_azure_openai(prompt: str, config: Dict[str, Any]) -> str:
     """Invoke Azure OpenAI provider."""
+    logger.debug("🔷 Initializing Azure OpenAI provider")
+    
     try:
         import openai
+        logger.debug("✅ OpenAI package imported successfully")
     except ImportError:
+        logger.error("❌ OpenAI package not installed")
         raise IntelligenceError("OpenAI package not installed. Run: pip install openai")
     
     model = config.get("model", "gpt-4")
@@ -143,19 +201,25 @@ def _invoke_azure_openai(prompt: str, config: Dict[str, Any]) -> str:
     temperature = config.get("temperature", 0.7)
     max_tokens = config.get("max_tokens", 150)
     
+    logger.debug(f"🔧 Azure config: model={model}, endpoint={endpoint}, api_version={api_version}, temp={temperature}, max_tokens={max_tokens}")
+    
     if not api_key:
+        logger.error("❌ Azure OpenAI API key not found")
         raise ConfigurationError("Azure OpenAI API key not found in config or AZURE_OPENAI_API_KEY environment variable")
     
     if not endpoint:
+        logger.error("❌ Azure OpenAI endpoint not found")
         raise ConfigurationError("Azure OpenAI endpoint not found in config or AZURE_OPENAI_ENDPOINT environment variable")
     
     try:
+        logger.debug("🔗 Creating Azure OpenAI client")
         client = openai.AzureOpenAI(
             api_key=api_key,
             azure_endpoint=endpoint,
             api_version=api_version
         )
         
+        logger.debug("📡 Sending request to Azure OpenAI API")
         response = client.chat.completions.create(
             model=model,
             messages=[{"role": "user", "content": prompt}],
@@ -165,11 +229,14 @@ def _invoke_azure_openai(prompt: str, config: Dict[str, Any]) -> str:
         
         content = response.choices[0].message.content
         if content is None:
+            logger.error("❌ Azure OpenAI returned empty response")
             raise IntelligenceError("Azure OpenAI returned empty response")
+        
+        logger.debug(f"✅ Azure OpenAI API call successful")
         return content
         
     except Exception as e:
-        log.error(f"Azure OpenAI API error: {e}")
+        logger.error(f"❌ Azure OpenAI API error: {type(e).__name__}: {e}")
         raise IntelligenceError(f"Azure OpenAI API error: {e}")
 
 
@@ -182,9 +249,13 @@ def _invoke_local(prompt: str, config: Dict[str, Any]) -> str:
     temperature = config.get("temperature", 0.7)
     max_tokens = config.get("max_tokens", 150)
     
+    logger.debug(f"🟢 Initializing local provider")
+    logger.debug(f"🔧 Local config: model={model}, endpoint={endpoint}, temp={temperature}, max_tokens={max_tokens}")
+    
     try:
         # Format for Ollama API
         if "ollama" in endpoint or ":11434" in endpoint:
+            logger.debug("📦 Using Ollama API format")
             payload = {
                 "model": model,
                 "prompt": prompt,
@@ -195,7 +266,7 @@ def _invoke_local(prompt: str, config: Dict[str, Any]) -> str:
                 }
             }
         else:
-            # Generic local API format
+            logger.debug("📦 Using generic local API format")
             payload = {
                 "model": model,
                 "prompt": prompt,
@@ -203,6 +274,7 @@ def _invoke_local(prompt: str, config: Dict[str, Any]) -> str:
                 "max_tokens": max_tokens
             }
         
+        logger.debug(f"📡 Sending request to local endpoint: {endpoint}")
         response = requests.post(endpoint, json=payload, timeout=30)
         response.raise_for_status()
         
@@ -210,19 +282,25 @@ def _invoke_local(prompt: str, config: Dict[str, Any]) -> str:
         
         # Handle different response formats
         if "response" in result:
-            return result["response"]  # Ollama format
+            response_text = result["response"]  # Ollama format
+            logger.debug("✅ Local API call successful (Ollama format)")
         elif "text" in result:
-            return result["text"]      # Generic format
+            response_text = result["text"]      # Generic format
+            logger.debug("✅ Local API call successful (generic format)")
         elif "choices" in result and len(result["choices"]) > 0:
-            return result["choices"][0].get("text", "")  # OpenAI-compatible format
+            response_text = result["choices"][0].get("text", "")  # OpenAI-compatible format
+            logger.debug("✅ Local API call successful (OpenAI-compatible format)")
         else:
+            logger.error(f"❌ Unexpected response format from local provider: {result}")
             raise IntelligenceError(f"Unexpected response format from local provider: {result}")
+        
+        return response_text
             
     except requests.RequestException as e:
-        log.error(f"Local provider request error: {e}")
+        logger.error(f"❌ Local provider request error: {type(e).__name__}: {e}")
         raise IntelligenceError(f"Local provider request error: {e}")
     except Exception as e:
-        log.error(f"Local provider error: {e}")
+        logger.error(f"❌ Local provider error: {type(e).__name__}: {e}")
         raise IntelligenceError(f"Local provider error: {e}")
 
 
@@ -244,29 +322,57 @@ def validate_config(config: Dict[str, Any]) -> bool:
     Raises:
         ConfigurationError: If configuration is invalid
     """
+    logger.debug(f"🔍 Validating intelligence configuration")
+    
     if not isinstance(config, dict):
+        logger.error("❌ Configuration must be a dictionary")
         raise ConfigurationError("Configuration must be a dictionary")
     
     engine = config.get("engine")
     if not engine:
+        logger.error("❌ Missing 'engine' in configuration")
         raise ConfigurationError("Missing 'engine' in configuration")
     
     if engine.lower() not in get_supported_engines():
+        logger.error(f"❌ Unsupported engine: {engine}")
         raise ConfigurationError(f"Unsupported engine: {engine}. Supported engines: {get_supported_engines()}")
     
     # Engine-specific validation
     engine = engine.lower()
+    logger.debug(f"🔧 Validating {engine} specific configuration")
     
     if engine in ["openai", "azure"]:
         if not config.get("api_key") and not os.getenv("OPENAI_API_KEY") and not os.getenv("AZURE_OPENAI_API_KEY"):
+            logger.error(f"❌ API key required for {engine} engine")
             raise ConfigurationError(f"API key required for {engine} engine")
     
     elif engine == "anthropic":
         if not config.get("api_key") and not os.getenv("ANTHROPIC_API_KEY"):
+            logger.error("❌ API key required for Anthropic engine")
             raise ConfigurationError("API key required for Anthropic engine")
     
     elif engine == "local":
         if not config.get("endpoint"):
             config["endpoint"] = "http://localhost:11434/api/generate"  # Default to Ollama
+            logger.debug("🔧 Set default endpoint for local engine")
+    
+    logger.debug(f"✅ Configuration validation successful for {engine}")
+    return True
+
+
+def _sanitize_config_for_logging(config: Dict[str, Any]) -> Dict[str, Any]:
+    """Sanitize config for logging by masking sensitive data."""
+    sanitized = config.copy()
+    
+    # Mask sensitive fields
+    sensitive_fields = ['api_key', 'password', 'token', 'secret']
+    for field in sensitive_fields:
+        if field in sanitized and sanitized[field]:
+            # Show first 4 and last 4 characters, mask the rest
+            value = str(sanitized[field])
+            if len(value) > 8:
+                sanitized[field] = f"{value[:4]}...{value[-4:]}"
+            else:
+                sanitized[field] = "***"
     
-    return True 
+    return sanitized 

dacp/logging_config.py

@@ -0,0 +1,128 @@
+"""
+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/orchestrator.py

@@ -3,9 +3,9 @@ DACP Orchestrator - Manages agent registration and message routing.
 """
 
 import logging
-from typing import Dict, Any, Optional, List, Callable
-import uuid
-import json
+import time
+from typing import Dict, Any, List, Optional
+from .tools import run_tool, TOOL_REGISTRY
 from .protocol import (
     parse_agent_response,
     is_tool_request,
@@ -14,30 +14,31 @@ from .protocol import (
     is_final_response,
     get_final_response,
 )
-from .tools import run_tool
 
-log = logging.getLogger(__name__)
+# Set up logger for this module
+logger = logging.getLogger("dacp.orchestrator")
 
 
 class Agent:
-    """Base agent interface that all agents should implement."""
+    """Base class for DACP agents."""
     
     def handle_message(self, message: Dict[str, Any]) -> Dict[str, Any]:
-        """Handle incoming messages from the orchestrator."""
+        """Handle an incoming message. Subclasses should override this method."""
         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.
     """
     
     def __init__(self):
+        """Initialize the orchestrator."""
         self.agents: Dict[str, Any] = {}
         self.conversation_history: List[Dict[str, Any]] = []
-        self.session_id = str(uuid.uuid4())
-        
+        self.session_id = f"session_{int(time.time())}"
+        logger.info(f"🎭 Orchestrator initialized with session ID: {self.session_id}")
+    
     def register_agent(self, agent_id: str, agent: Any) -> None:
         """
         Register an agent with the orchestrator.
@@ -47,183 +48,145 @@ class Orchestrator:
             agent: Agent instance that implements handle_message method
         """
         if not hasattr(agent, 'handle_message'):
-            raise ValueError(f"Agent {agent_id} must implement handle_message method")
+            logger.error(f"❌ Agent '{agent_id}' does not implement handle_message method")
+            raise ValueError(f"Agent must implement handle_message method")
         
         self.agents[agent_id] = agent
-        log.info(f"Registered agent: {agent_id}")
-        
+        logger.info(f"✅ Agent '{agent_id}' registered successfully (type: {type(agent).__name__})")
+        logger.debug(f"📊 Total registered agents: {len(self.agents)}")
+    
     def unregister_agent(self, agent_id: str) -> bool:
         """
         Unregister an agent from the orchestrator.
         
         Args:
-            agent_id: ID of the agent to unregister
+            agent_id: Unique identifier for the agent
             
         Returns:
-            True if agent was found and removed, False otherwise
+            True if agent was successfully unregistered, False if not found
         """
         if agent_id in self.agents:
+            agent_type = type(self.agents[agent_id]).__name__
             del self.agents[agent_id]
-            log.info(f"Unregistered agent: {agent_id}")
+            logger.info(f"🗑️  Agent '{agent_id}' unregistered successfully (was type: {agent_type})")
+            logger.debug(f"📊 Remaining registered 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)
-        
-    def list_agents(self) -> List[str]:
-        """Get list of registered agent IDs."""
-        return list(self.agents.keys())
-        
+        else:
+            logger.warning(f"⚠️  Attempted to unregister unknown agent: '{agent_id}'")
+            return False
+    
     def send_message(self, agent_id: str, message: Dict[str, Any]) -> Dict[str, Any]:
         """
         Send a message to a specific agent.
         
         Args:
-            agent_id: ID of the target agent
+            agent_id: Target agent identifier
             message: Message to send
             
         Returns:
-            Response from the agent
-            
-        Raises:
-            ValueError: If agent_id is not found
+            Response from the agent (or error if agent not found)
         """
+        logger.info(f"📨 Sending message to agent '{agent_id}'")
+        logger.debug(f"📋 Message content: {message}")
+        
         if agent_id not in self.agents:
-            raise ValueError(f"Agent {agent_id} not found")
-            
-        agent = self.agents[agent_id]
+            error_msg = f"Agent '{agent_id}' not found"
+            logger.error(f"❌ {error_msg}")
+            logger.debug(f"📊 Available agents: {list(self.agents.keys())}")
+            return {"error": error_msg}
         
-        # Add metadata to message
-        enriched_message = {
-            "session_id": self.session_id,
-            "timestamp": self._get_timestamp(),
-            **message
-        }
+        agent = self.agents[agent_id]
         
         try:
-            # Send message to agent
-            response = agent.handle_message(enriched_message)
+            start_time = time.time()
+            logger.debug(f"🔄 Calling handle_message on agent '{agent_id}'")
             
-            # Log the interaction
-            self.conversation_history.append({
-                "type": "message",
-                "agent_id": agent_id,
-                "message": enriched_message,
-                "response": response,
-                "timestamp": self._get_timestamp()
-            })
+            response = agent.handle_message(message)
             
+            processing_time = time.time() - start_time
+            logger.info(f"✅ Agent '{agent_id}' responded in {processing_time:.3f}s")
+            logger.debug(f"📤 Agent response: {response}")
+            
+            # Check if agent requested a tool
+            if is_tool_request(response):
+                logger.info(f"🔧 Agent '{agent_id}' requested tool execution")
+                tool_name, tool_args = get_tool_request(response)
+                logger.info(f"🛠️  Executing tool: '{tool_name}' with args: {tool_args}")
+                
+                if tool_name in TOOL_REGISTRY:
+                    try:
+                        tool_start_time = time.time()
+                        tool_result = run_tool(tool_name, tool_args)
+                        tool_execution_time = time.time() - tool_start_time
+                        
+                        logger.info(f"✅ Tool '{tool_name}' executed successfully in {tool_execution_time:.3f}s")
+                        logger.debug(f"🔧 Tool result: {tool_result}")
+                        
+                        wrapped_result = wrap_tool_result(tool_name, tool_result)
+                        
+                        # Log the conversation
+                        self._log_conversation(agent_id, message, wrapped_result, tool_used=tool_name)
+                        
+                        return wrapped_result
+                        
+                    except Exception as e:
+                        error_msg = f"Tool '{tool_name}' execution failed: {str(e)}"
+                        logger.error(f"❌ {error_msg}")
+                        error_response = {"error": error_msg}
+                        self._log_conversation(agent_id, message, error_response, tool_used=tool_name)
+                        return error_response
+                else:
+                    error_msg = f"Unknown tool requested: '{tool_name}'"
+                    logger.error(f"❌ {error_msg}")
+                    logger.debug(f"📊 Available tools: {list(TOOL_REGISTRY.keys())}")
+                    error_response = {"error": error_msg}
+                    self._log_conversation(agent_id, message, error_response)
+                    return error_response
+            
+            # Log successful conversation
+            self._log_conversation(agent_id, message, response)
             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}")
+            error_msg = f"Agent '{agent_id}' error: {str(e)}"
+            logger.error(f"❌ {error_msg}")
+            logger.debug(f"🐛 Exception details: {type(e).__name__}: {e}")
+            error_response = {"error": error_msg}
+            self._log_conversation(agent_id, message, error_response)
             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], exclude_agents: Optional[List[str]] = None) -> Dict[str, Dict[str, Any]]:
         """
-        Broadcast a message to all registered agents.
+        Send a message to all registered agents (optionally excluding some).
         
         Args:
             message: Message to broadcast
             exclude_agents: List of agent IDs to exclude from broadcast
             
         Returns:
-            Dictionary mapping agent_id to response
+            Dict mapping agent IDs to their responses
         """
         exclude_agents = exclude_agents or []
-        responses = {}
+        target_agents = [aid for aid in self.agents.keys() if aid not in exclude_agents]
         
-        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)}
-                    
-        return responses
+        logger.info(f"📡 Broadcasting message to {len(target_agents)} agents")
+        logger.debug(f"🎯 Target agents: {target_agents}")
+        if exclude_agents:
+            logger.debug(f"🚫 Excluded agents: {exclude_agents}")
         
-    def handle_tool_request(self, tool_name: str, args: Dict[str, Any]) -> Dict[str, Any]:
-        """
-        Handle a tool execution request.
+        responses = {}
+        start_time = time.time()
         
-        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]:
-        """
-        Process an agent response, handling tool requests and final responses.
+        for agent_id in target_agents:
+            logger.debug(f"📨 Broadcasting to agent '{agent_id}'")
+            responses[agent_id] = self.send_message(agent_id, message)
         
-        Args:
-            agent_id: ID of the agent that sent the response
-            response: Agent response (string or dict)
-            
-        Returns:
-            Processed response
-        """
-        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
-                
-        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]]:
+        broadcast_time = time.time() - start_time
+        logger.info(f"✅ Broadcast completed in {broadcast_time:.3f}s")
+        
+        return responses
+    
+    def get_conversation_history(self, agent_id: Optional[str] = None) -> List[Dict[str, Any]]:
         """
         Get conversation history, optionally filtered by agent.
         
@@ -233,28 +196,53 @@ class Orchestrator:
         Returns:
             List of conversation entries
         """
-        if agent_id:
-            return [
+        if agent_id is None:
+            logger.debug(f"📚 Retrieving full conversation history ({len(self.conversation_history)} entries)")
+            return self.conversation_history.copy()
+        else:
+            filtered_history = [
                 entry for entry in self.conversation_history 
                 if entry.get("agent_id") == agent_id
             ]
-        return self.conversation_history.copy()
-        
+            logger.debug(f"📚 Retrieving conversation history for '{agent_id}' ({len(filtered_history)} entries)")
+            return filtered_history
+    
     def clear_history(self) -> None:
-        """Clear conversation history."""
+        """Clear the conversation history."""
+        old_count = len(self.conversation_history)
         self.conversation_history.clear()
-        log.info("Conversation history cleared")
-        
+        logger.info(f"🗑️  Conversation history cleared ({old_count} entries removed)")
+    
     def get_session_info(self) -> Dict[str, Any]:
-        """Get current session information."""
-        return {
+        """
+        Get current session information.
+        
+        Returns:
+            Dict containing session metadata
+        """
+        info = {
             "session_id": self.session_id,
-            "registered_agents": self.list_agents(),
-            "conversation_length": len(self.conversation_history),
-            "timestamp": self._get_timestamp()
+            "registered_agents": list(self.agents.keys()),
+            "conversation_count": len(self.conversation_history),
+            "available_tools": list(TOOL_REGISTRY.keys())
         }
+        logger.debug(f"📊 Session info requested: {info}")
+        return info
+    
+    def _log_conversation(self, agent_id: str, message: Dict[str, Any], response: Dict[str, Any], tool_used: Optional[str] = None) -> None:
+        """Log a conversation entry."""
+        entry = {
+            "timestamp": time.time(),
+            "agent_id": agent_id,
+            "message": message,
+            "response": response,
+            "session_id": self.session_id
+        }
+        
+        if tool_used:
+            entry["tool_used"] = tool_used
+            logger.debug(f"💾 Logging conversation with tool usage: {tool_used}")
+        else:
+            logger.debug(f"💾 Logging conversation entry")
         
-    def _get_timestamp(self) -> str:
-        """Get current timestamp in ISO format."""
-        from datetime import datetime
-        return datetime.utcnow().isoformat() + "Z"
+        self.conversation_history.append(entry)

dacp/tools.py

@@ -1,21 +1,43 @@
+import logging
 from typing import Dict, Any, Callable
 from pathlib import Path
 
+# Set up logger for this module
+logger = logging.getLogger("dacp.tools")
+
 TOOL_REGISTRY: Dict[str, Callable[..., Dict[str, Any]]] = {}
 
 
 def register_tool(tool_id: str, func: Callable[..., Dict[str, Any]]) -> None:
     """Register a tool function."""
     TOOL_REGISTRY[tool_id] = func
+    logger.info(f"🔧 Tool '{tool_id}' registered successfully (function: {func.__name__})")
+    logger.debug(f"📊 Total registered tools: {len(TOOL_REGISTRY)}")
 
 
 def run_tool(tool_id: str, args: Dict[str, Any]) -> Dict[str, Any]:
     """Run a registered tool with the given arguments."""
     if tool_id not in TOOL_REGISTRY:
+        logger.error(f"❌ Unknown tool requested: '{tool_id}'")
+        logger.debug(f"📊 Available tools: {list(TOOL_REGISTRY.keys())}")
         raise ValueError(f"Unknown tool: {tool_id}")
 
     tool_func = TOOL_REGISTRY[tool_id]
-    return tool_func(**args)
+    logger.debug(f"🛠️  Executing tool '{tool_id}' with args: {args}")
+    
+    import time
+    start_time = time.time()
+    
+    try:
+        result = tool_func(**args)
+        execution_time = time.time() - start_time
+        logger.info(f"✅ Tool '{tool_id}' executed successfully in {execution_time:.3f}s")
+        logger.debug(f"🔧 Tool result: {result}")
+        return result
+    except Exception as e:
+        execution_time = time.time() - start_time
+        logger.error(f"❌ Tool '{tool_id}' failed after {execution_time:.3f}s: {type(e).__name__}: {e}")
+        raise
 
 
 def file_writer(path: str, content: str) -> Dict[str, Any]:
@@ -29,20 +51,27 @@ def file_writer(path: str, content: str) -> Dict[str, Any]:
     Returns:
         Dict with success status and file path
     """
+    logger.debug(f"📝 Writing to file: {path} ({len(content)} characters)")
+    
     try:
         # Create parent directories if they don't exist
-        Path(path).parent.mkdir(parents=True, exist_ok=True)
+        parent_dir = Path(path).parent
+        if not parent_dir.exists():
+            logger.debug(f"📁 Creating parent directories: {parent_dir}")
+            parent_dir.mkdir(parents=True, exist_ok=True)
 
         # Write the content to the file
         with open(path, "w", encoding="utf-8") as f:
             f.write(content)
 
+        logger.info(f"✅ File written successfully: {path}")
         return {
             "success": True,
             "path": path,
             "message": f"Successfully wrote {len(content)} characters to {path}",
         }
     except Exception as e:
+        logger.error(f"❌ Failed to write file {path}: {type(e).__name__}: {e}")
         return {
             "success": False,
             "path": path,
@@ -52,4 +81,6 @@ def file_writer(path: str, content: str) -> Dict[str, Any]:
 
 
 # Register the built-in file_writer tool
+logger.debug("🏗️  Registering built-in tools...")
 register_tool("file_writer", file_writer)
+logger.debug("✅ Built-in tools registration complete")

{dacp-0.3.0.dist-info → dacp-0.3.1.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dacp
-Version: 0.3.0
+Version: 0.3.1
 Summary: Declarative Agent Communication Protocol - A protocol for managing LLM/agent communications and tool function calls
 Author-email: Andrew Whitehouse <andrew.whitehouse@example.com>
 License: MIT
@@ -132,6 +132,16 @@ response = dacp.call_llm("What is the weather like today?")
 
 - `call_llm(prompt: str, model: str = "gpt-4") -> str`: Call OpenAI (legacy function)
 
+### Logging
+
+- `enable_info_logging(log_file: str = None) -> None`: Enable info-level logging with emoji format
+- `enable_debug_logging(log_file: str = None) -> None`: Enable debug logging with detailed format  
+- `enable_quiet_logging() -> None`: Enable only error and critical logging
+- `setup_dacp_logging(level, format_style, include_timestamp, log_file) -> None`: Custom logging setup
+- `set_dacp_log_level(level: str) -> None`: Change log level dynamically
+- `disable_dacp_logging() -> None`: Disable all DACP logging
+- `enable_dacp_logging() -> None`: Re-enable DACP logging
+
 ### Protocol
 
 - `parse_agent_response(response: str | dict) -> dict`: Parse agent response
@@ -348,6 +358,91 @@ else:
 - ✅ Returns detailed success/error information
 - ✅ Safe error handling
 
+## Logging
+
+DACP includes comprehensive logging to help you monitor agent operations, tool executions, and intelligence calls.
+
+### Quick Setup
+
+```python
+import dacp
+
+# Enable info-level logging with emoji format (recommended for production)
+dacp.enable_info_logging()
+
+# Enable debug logging for development (shows detailed information)
+dacp.enable_debug_logging()
+
+# Enable quiet logging (errors only)
+dacp.enable_quiet_logging()
+```
+
+### Custom Configuration
+
+```python
+# Full control over logging configuration
+dacp.setup_dacp_logging(
+    level="INFO",                    # DEBUG, INFO, WARNING, ERROR, CRITICAL
+    format_style="emoji",            # "simple", "detailed", "emoji"
+    include_timestamp=True,          # Include timestamps
+    log_file="dacp.log"              # Optional: also log to file
+)
+
+# Change log level dynamically
+dacp.set_dacp_log_level("DEBUG")
+
+# Disable/enable logging
+dacp.disable_dacp_logging()
+dacp.enable_dacp_logging()
+```
+
+### What Gets Logged
+
+With logging enabled, you'll see:
+
+- **🎭 Agent Registration**: When agents are registered/unregistered
+- **📨 Message Routing**: Messages sent to agents and broadcast operations  
+- **🔧 Tool Execution**: Tool calls, execution time, and results
+- **🧠 Intelligence Calls**: LLM provider calls, configuration, and performance
+- **❌ Errors**: Detailed error information with context
+- **📊 Performance**: Execution times for operations
+
+### Log Format Examples
+
+**Emoji Format** (clean, production-friendly):
+```
+2025-07-02 09:54:58 - 🎭 Orchestrator initialized with session ID: session_1751414098
+2025-07-02 09:54:58 - ✅ Agent 'demo-agent' registered successfully (type: MyAgent)
+2025-07-02 09:54:58 - 📨 Sending message to agent 'demo-agent'
+2025-07-02 09:54:58 - 🔧 Agent 'demo-agent' requested tool execution
+2025-07-02 09:54:58 - 🛠️  Executing tool: 'file_writer' with args: {...}
+2025-07-02 09:54:58 - ✅ Tool 'file_writer' executed successfully in 0.001s
+```
+
+**Detailed Format** (development/debugging):
+```
+2025-07-02 09:54:58 - dacp.orchestrator:89 - INFO - 📨 Sending message to agent 'demo-agent'
+2025-07-02 09:54:58 - dacp.orchestrator:90 - DEBUG - 📋 Message content: {'task': 'greet'}
+2025-07-02 09:54:58 - dacp.tools:26 - DEBUG - 🛠️  Executing tool 'file_writer' with args: {...}
+```
+
+### Example Usage
+
+```python
+import dacp
+
+# Enable logging
+dacp.enable_info_logging()
+
+# Create and use components - logging happens automatically
+orchestrator = dacp.Orchestrator()
+agent = MyAgent()
+orchestrator.register_agent("my-agent", agent)
+
+# This will log the message sending, tool execution, etc.
+response = orchestrator.send_message("my-agent", {"task": "process"})
+```
+
 ## Development
 
 ```bash

dacp-0.3.1.dist-info/RECORD

@@ -0,0 +1,15 @@
+dacp/__init__.py,sha256=qTwsfYAnuq4PiE_1Vm6gK7VAycBEz_K6C2hzmPOODI0,1352
+dacp/exceptions.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+dacp/intelligence.py,sha256=dyVxbVHAX56tsgC-_C9jNTov9PstPTiGehBS4L57lXw,15002
+dacp/llm.py,sha256=JxHqM-aIm9pAMcVHQevbJGxrlBH4uV1ngRQdvyp9L3A,827
+dacp/logging_config.py,sha256=FqQp650BwQLKM32L0ITYjadXXzG22KbjsL21_JlK9LM,3950
+dacp/main.py,sha256=ZcJLymC9S5A4iO4yV7X178RLlhDrDuAwirdevUD5Yn0,470
+dacp/orchestrator.py,sha256=oJ0C27qMBVgAW8jPqTvNhVOuaYBn5wRa2kJIej05iac,10065
+dacp/protocol.py,sha256=DVhLTdyDVlAu8ETSEX8trPeycKfMeirHwcWQ8-BY7eA,1026
+dacp/tools.py,sha256=9YNBg-YJtAWKNo88VXgQ6bedu_4Z3pGWq2QWVXPJg30,3009
+dacp/types.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+dacp-0.3.1.dist-info/licenses/LICENSE,sha256=tb5kgUYRypHqAy8wlrJUBSYI5l1SBmawSYHmCC-MVW0,1074
+dacp-0.3.1.dist-info/METADATA,sha256=CAs6fi58DLlSzcKkn8uPMKd1QP19yPWbFNKF71Z8Q5s,14506
+dacp-0.3.1.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+dacp-0.3.1.dist-info/top_level.txt,sha256=Qxy0cy5jl7ttTQoGFlY9LXB6CbSvsekJ2y0P8I7L1zA,5
+dacp-0.3.1.dist-info/RECORD,,

dacp-0.3.0.dist-info/RECORD

@@ -1,14 +0,0 @@
-dacp/__init__.py,sha256=-EFiHyOWg8IcG2FI-Hmd9wrHicGi8qAMv0cPwz0oCiU,833
-dacp/exceptions.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-dacp/intelligence.py,sha256=SGLaq6dlJmeDqP0ZgT6bR_4WahNf-K7qWBaTG3yqBMI,9487
-dacp/llm.py,sha256=JxHqM-aIm9pAMcVHQevbJGxrlBH4uV1ngRQdvyp9L3A,827
-dacp/main.py,sha256=ZcJLymC9S5A4iO4yV7X178RLlhDrDuAwirdevUD5Yn0,470
-dacp/orchestrator.py,sha256=PIur8Kts-vtUchmo7E8B59ZLm6s7C7yQ0ScK9E5FXhE,8756
-dacp/protocol.py,sha256=DVhLTdyDVlAu8ETSEX8trPeycKfMeirHwcWQ8-BY7eA,1026
-dacp/tools.py,sha256=FLgZa5Brni9H3Hyn336k3DGoVxIa_1rFM4WpIRXzVbc,1569
-dacp/types.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-dacp-0.3.0.dist-info/licenses/LICENSE,sha256=tb5kgUYRypHqAy8wlrJUBSYI5l1SBmawSYHmCC-MVW0,1074
-dacp-0.3.0.dist-info/METADATA,sha256=J9bKw2rxID--1fqZ9Z33lSs2SKTmat72zVLj-DUirU0,11220
-dacp-0.3.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-dacp-0.3.0.dist-info/top_level.txt,sha256=Qxy0cy5jl7ttTQoGFlY9LXB6CbSvsekJ2y0P8I7L1zA,5
-dacp-0.3.0.dist-info/RECORD,,