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

dacp/tools.py

@@ -1,86 +1,105 @@
+"""
+DACP Tools - Built-in tool implementations.
+
+This module provides the core tool functionality including tool registry,
+execution, and built-in tools like file_writer.
+"""
+
 import logging
-from typing import Dict, Any, Callable
 from pathlib import Path
+from typing import Dict, Any, Callable
 
-# Set up logger for this module
 logger = logging.getLogger("dacp.tools")
 
-TOOL_REGISTRY: Dict[str, Callable[..., Dict[str, Any]]] = {}
+# Global tool registry
+TOOL_REGISTRY: Dict[str, Callable[[Dict[str, Any]], 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 register_tool(name: str, func: Callable[[Dict[str, Any]], Dict[str, Any]]) -> None:
+    """
+    Register a tool function.
+
+    Args:
+        name: Name of the tool
+        func: Function that takes args dict and returns result dict
+    """
+    TOOL_REGISTRY[name] = func
+    logger.info(f"🔧 Tool '{name}' registered")
 
 
-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}")
+def execute_tool(name: str, args: Dict[str, Any]) -> Dict[str, Any]:
+    """
+    Execute a tool by name with given arguments.
+
+    Args:
+        name: Name of the tool to execute
+        args: Arguments to pass to the tool
+
+    Returns:
+        Tool execution result
+
+    Raises:
+        ValueError: If tool is not found
+    """
+    if name not in TOOL_REGISTRY:
+        available_tools = list(TOOL_REGISTRY.keys())
+        logger.error(
+            f"❌ Tool '{name}' not found. " f"Available tools: {available_tools}"
+        )
+        raise ValueError(f"Tool '{name}' not found. Available tools: {available_tools}")
+
+    logger.debug(f"🛠️  Executing tool '{name}' with args: {args}")
 
-    tool_func = TOOL_REGISTRY[tool_id]
-    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}")
+        result = TOOL_REGISTRY[name](args)
+        logger.debug(f"✅ Tool '{name}' completed successfully")
         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}")
+        logger.error(f"❌ Tool '{name}' failed: {type(e).__name__}: {e}")
         raise
 
 
-def file_writer(path: str, content: str) -> Dict[str, Any]:
+def file_writer(args: Dict[str, Any]) -> Dict[str, Any]:
     """
-    Write content to a file, creating parent directories if they don't exist.
+    Write content to a file, creating directories as needed.
 
     Args:
-        path: File path to write to
-        content: Content to write to the file
+        args: Dictionary containing 'path' and 'content'
 
     Returns:
-        Dict with success status and file path
+        Success status and file information
     """
-    logger.debug(f"📝 Writing to file: {path} ({len(content)} characters)")
-    
+    path = args.get("path")
+    content = args.get("content", "")
+
+    if not path:
+        raise ValueError("file_writer requires 'path' argument")
+
     try:
         # Create parent directories if they don't exist
-        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)
+        file_path = Path(path)
+        file_path.parent.mkdir(parents=True, exist_ok=True)
 
-        # Write the content to the file
-        with open(path, "w", encoding="utf-8") as f:
+        # Write content to file
+        with open(file_path, "w", encoding="utf-8") as f:
             f.write(content)
 
         logger.info(f"✅ File written successfully: {path}")
+
         return {
             "success": True,
-            "path": path,
+            "path": str(file_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}")
+        logger.error(f"❌ Failed to write file {path}: {e}")
         return {
             "success": False,
             "path": path,
             "error": str(e),
-            "message": f"Failed to write to {path}: {e}",
         }
 
 
-# Register the built-in file_writer tool
-logger.debug("🏗️  Registering built-in tools...")
+# Register built-in tools
 register_tool("file_writer", file_writer)
-logger.debug("✅ Built-in tools registration complete")

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dacp
-Version: 0.3.1
+Version: 0.3.2
 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
@@ -443,6 +443,347 @@ orchestrator.register_agent("my-agent", agent)
 response = orchestrator.send_message("my-agent", {"task": "process"})
 ```
 
+## Usage Patterns: Open Agent Spec vs Independent Client Usage
+
+DACP supports two primary usage patterns: integration with Open Agent Specification (OAS) projects and independent client usage. Both provide full access to DACP's capabilities but with different integration approaches.
+
+### Open Agent Specification (OAS) Integration
+
+**For OAS developers:** DACP integrates seamlessly with generated agents through YAML configuration and automatic setup.
+
+#### YAML Configuration Pattern
+
+```yaml
+# agent_config.yaml (Open Agent Specification)
+apiVersion: "v1"
+kind: "Agent"
+metadata:
+  name: "data-analysis-agent"
+  type: "smart_analysis"
+
+# DACP automatically configures logging
+logging:
+  enabled: true
+  level: "INFO"
+  format_style: "emoji"
+  log_file: "./logs/agent.log"
+  env_overrides:
+    level: "DACP_LOG_LEVEL"
+
+# Multi-provider intelligence configuration
+intelligence:
+  engine: "anthropic"
+  model: "claude-3-haiku-20240618"
+  # API key from environment: ANTHROPIC_API_KEY
+
+# Define agent capabilities
+capabilities:
+  - name: "analyze_data"
+    description: "Analyze datasets and generate insights"
+  - name: "generate_report"
+    description: "Generate analysis reports"
+```
+
+#### Generated Agent Code (OAS Pattern)
+
+```python
+# Generated by OAS with DACP integration
+import dacp
+import yaml
+
+class DataAnalysisAgent(dacp.Agent):
+    def __init__(self, config_path="agent_config.yaml"):
+        # DACP auto-configures logging from YAML
+        with open(config_path, 'r') as f:
+            self.config = yaml.safe_load(f)
+        
+        # Automatic logging setup
+        self.setup_logging()
+        
+        # Load intelligence configuration
+        self.intelligence_config = self.config.get('intelligence', {})
+    
+    def setup_logging(self):
+        """Auto-configure DACP logging from YAML config."""
+        logging_config = self.config.get('logging', {})
+        if logging_config.get('enabled', False):
+            dacp.setup_dacp_logging(
+                level=logging_config.get('level', 'INFO'),
+                format_style=logging_config.get('format_style', 'emoji'),
+                log_file=logging_config.get('log_file')
+            )
+    
+    def handle_message(self, message):
+        """Handle capabilities defined in YAML."""
+        task = message.get("task")
+        
+        if task == "analyze_data":
+            return self.analyze_data(message)
+        elif task == "generate_report":
+            return self.generate_report(message)
+        else:
+            return {"error": f"Unknown task: {task}"}
+    
+    def analyze_data(self, message):
+        """Analyze data using configured intelligence provider."""
+        data = message.get("data", "No data provided")
+        
+        try:
+            result = dacp.invoke_intelligence(
+                f"Analyze this data and provide insights: {data}",
+                self.intelligence_config
+            )
+            return {"response": result}
+        except Exception as e:
+            return {"error": f"Analysis failed: {e}"}
+    
+    def generate_report(self, message):
+        """Generate reports using DACP's file_writer tool."""
+        subject = message.get("subject", "report")
+        data = message.get("data", "No data")
+        
+        return {
+            "tool_request": {
+                "name": "file_writer", 
+                "args": {
+                    "path": f"./reports/{subject}.txt",
+                    "content": f"# Analysis Report: {subject}\n\nData: {data}\n"
+                }
+            }
+        }
+
+# Auto-generated main function
+def main():
+    # Zero-configuration setup
+    orchestrator = dacp.Orchestrator()
+    agent = DataAnalysisAgent()
+    orchestrator.register_agent("data-analysis-agent", agent)
+    
+    print("🚀 OAS Agent running with DACP integration!")
+    # Agent ready for messages via orchestrator
+
+if __name__ == "__main__":
+    main()
+```
+
+#### OAS Benefits
+
+- ✅ **Zero Configuration**: Logging and intelligence work out of the box
+- ✅ **YAML-Driven**: All configuration in standard OAS YAML format  
+- ✅ **Auto-Generated**: Complete agents generated from specifications
+- ✅ **Environment Overrides**: Runtime configuration via environment variables
+- ✅ **Standardized**: Consistent interface across all OAS agents
+
+### Independent Client Usage
+
+**For independent developers:** Use DACP directly as a flexible agent router and orchestration platform.
+
+#### Direct Integration Pattern
+
+```python
+import dacp
+import os
+
+class MyCustomAgent(dacp.Agent):
+    """Independent client's custom agent."""
+    
+    def __init__(self):
+        # Manual setup - full control
+        self.setup_intelligence()
+        self.setup_logging()
+        
+    def setup_intelligence(self):
+        """Configure intelligence providers manually."""
+        self.intelligence_configs = {
+            "research": {
+                "engine": "openai",
+                "model": "gpt-4",
+                "api_key": os.getenv("OPENAI_API_KEY")
+            },
+            "analysis": {
+                "engine": "anthropic", 
+                "model": "claude-3-sonnet-20240229",
+                "api_key": os.getenv("ANTHROPIC_API_KEY")
+            },
+            "local": {
+                "engine": "local",
+                "model": "llama2",
+                "endpoint": "http://localhost:11434/api/generate"
+            }
+        }
+    
+    def setup_logging(self):
+        """Configure logging manually."""
+        dacp.enable_info_logging(log_file="./logs/custom_agent.log")
+    
+    def handle_message(self, message):
+        """Custom business logic."""
+        task = message.get("task")
+        
+        if task == "research_topic":
+            return self.research_with_multiple_llms(message)
+        elif task == "process_data":
+            return self.multi_step_processing(message)
+        elif task == "custom_workflow":
+            return self.handle_custom_workflow(message)
+        else:
+            return {"error": f"Unknown task: {task}"}
+    
+    def research_with_multiple_llms(self, message):
+        """Use multiple LLM providers for comprehensive research."""
+        topic = message.get("topic", "AI Research")
+        
+        # Use different LLMs for different aspects
+        research_prompt = f"Research the topic: {topic}"
+        analysis_prompt = f"Analyze research findings for: {topic}"
+        
+        try:
+            # Research with GPT-4
+            research = dacp.invoke_intelligence(
+                research_prompt, 
+                self.intelligence_configs["research"]
+            )
+            
+            # Analysis with Claude
+            analysis = dacp.invoke_intelligence(
+                f"Analyze: {research}",
+                self.intelligence_configs["analysis"]
+            )
+            
+            return {
+                "research": research,
+                "analysis": analysis,
+                "status": "completed"
+            }
+        except Exception as e:
+            return {"error": f"Research failed: {e}"}
+    
+    def multi_step_processing(self, message):
+        """Multi-step workflow with tool chaining."""
+        data = message.get("data", "sample data")
+        
+        # Step 1: Process and save data
+        return {
+            "tool_request": {
+                "name": "file_writer",
+                "args": {
+                    "path": "./processing/input_data.txt",
+                    "content": f"Raw data: {data}\nProcessed at: {dacp.time.time()}"
+                }
+            }
+        }
+        # In real implementation, would continue workflow in subsequent messages
+
+# Independent client setup
+def main():
+    # Manual orchestrator setup
+    orchestrator = dacp.Orchestrator()
+    
+    # Register multiple custom agents
+    research_agent = MyCustomAgent()
+    data_agent = MyCustomAgent()
+    workflow_agent = MyCustomAgent()
+    
+    orchestrator.register_agent("researcher", research_agent)
+    orchestrator.register_agent("processor", data_agent)  
+    orchestrator.register_agent("workflow", workflow_agent)
+    
+    # Direct control over routing
+    print("🚀 Independent client agents running!")
+    
+    # Example: Route complex task across multiple agents
+    research_result = orchestrator.send_message("researcher", {
+        "task": "research_topic",
+        "topic": "Multi-Agent Systems"
+    })
+    
+    processing_result = orchestrator.send_message("processor", {
+        "task": "process_data", 
+        "data": research_result
+    })
+    
+    # Broadcast updates to all agents
+    orchestrator.broadcast_message({
+        "task": "status_update",
+        "message": "Workflow completed"
+    })
+
+if __name__ == "__main__":
+    main()
+```
+
+#### Advanced Independent Usage
+
+```python
+# Register custom tools for specialized business logic
+def custom_data_processor(args):
+    """Client's proprietary data processing tool."""
+    data = args.get("data", [])
+    algorithm = args.get("algorithm", "default")
+    
+    # Custom processing logic
+    processed = [item * 2 for item in data if isinstance(item, (int, float))]
+    
+    return {
+        "success": True,
+        "processed_data": processed,
+        "algorithm_used": algorithm,
+        "count": len(processed)
+    }
+
+# Register with DACP
+dacp.register_tool("custom_processor", custom_data_processor)
+
+# Use in agents
+class SpecializedAgent(dacp.Agent):
+    def handle_message(self, message):
+        if message.get("task") == "process_with_custom_tool":
+            return {
+                "tool_request": {
+                    "name": "custom_processor",
+                    "args": {
+                        "data": message.get("data", []),
+                        "algorithm": "proprietary_v2"
+                    }
+                }
+            }
+```
+
+#### Independent Client Benefits
+
+- ✅ **Full Control**: Manual configuration of all components
+- ✅ **Flexible Architecture**: Design your own agent interactions
+- ✅ **Custom Tools**: Register proprietary business logic tools
+- ✅ **Multi-Provider**: Use different LLMs for different tasks
+- ✅ **Direct API Access**: Call DACP functions directly when needed
+- ✅ **Complex Workflows**: Build sophisticated multi-agent orchestrations
+
+### Choosing Your Pattern
+
+| Feature | OAS Integration | Independent Client |
+|---------|----------------|-------------------|
+| **Setup Complexity** | Minimal (auto-generated) | Manual (full control) |
+| **Configuration** | YAML-driven | Programmatic |
+| **Agent Generation** | Automatic from spec | Manual implementation |
+| **Customization** | Template-based | Unlimited flexibility |
+| **Best For** | Rapid prototyping, standard agents | Complex workflows, custom logic |
+| **Learning Curve** | Low | Medium |
+
+### Getting Started
+
+**For OAS Integration:**
+1. Add DACP logging section to your YAML spec
+2. Generate agents with DACP base class
+3. Agents work with zero additional configuration
+
+**For Independent Usage:**
+1. `pip install dacp` 
+2. Create agents inheriting from `dacp.Agent`
+3. Register with `dacp.Orchestrator()`
+4. Build your custom workflows
+
+Both patterns provide full access to DACP's capabilities: multi-provider LLM routing, tool execution, comprehensive logging, conversation history, and multi-agent orchestration.
+
 ## Development
 
 ```bash

dacp-0.3.2.dist-info/RECORD

@@ -0,0 +1,15 @@
+dacp/__init__.py,sha256=5EUO_gnPX7DISwAuPPkDSWrHoH9MNEoDRjDG16c7q_w,1351
+dacp/exceptions.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+dacp/intelligence.py,sha256=z8RqRYXKKKDd9MCm1KLBNQ3DJ9Zl4ZntbjFcaqtuv9s,9713
+dacp/llm.py,sha256=K78QefD3LCOBTrsNHtfRs-UzcHNYCJNxcJ28HGirwfU,1064
+dacp/logging_config.py,sha256=g5iMe9mloZag4oFQ9FQrRTikDTCI-XxeTGX0Y1KXVMw,3927
+dacp/main.py,sha256=YReioZotkURiYMuMLVf_-hPzVPSpqA5Esgwz7D36DhE,229
+dacp/orchestrator.py,sha256=5GxAVQFYW6OkNB8O5TT2eaJtQat7YUN_je7j-V0kXNM,9315
+dacp/protocol.py,sha256=DVhLTdyDVlAu8ETSEX8trPeycKfMeirHwcWQ8-BY7eA,1026
+dacp/tools.py,sha256=wfuUQ12UVvyMLUcDA4GGxwwzQJ-k4ftWbewg7qwNQGg,2872
+dacp/types.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+dacp-0.3.2.dist-info/licenses/LICENSE,sha256=tb5kgUYRypHqAy8wlrJUBSYI5l1SBmawSYHmCC-MVW0,1074
+dacp-0.3.2.dist-info/METADATA,sha256=RHlO4D7HV5kNPendOYH9yd3c5hzDOsIKf8bMSJcaNEk,25756
+dacp-0.3.2.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+dacp-0.3.2.dist-info/top_level.txt,sha256=Qxy0cy5jl7ttTQoGFlY9LXB6CbSvsekJ2y0P8I7L1zA,5
+dacp-0.3.2.dist-info/RECORD,,

dacp-0.3.1.dist-info/RECORD

@@ -1,15 +0,0 @@
-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,,