dacp 0.3.0__tar.gz → 0.3.1__tar.gz

{dacp-0.3.0 → dacp-0.3.1}/PKG-INFO

@@ -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.0 → dacp-0.3.1}/README.md

@@ -85,6 +85,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
@@ -301,6 +311,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.0 → dacp-0.3.1}/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-0.3.0 → dacp-0.3.1}/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