dacp 0.3.1__tar.gz → 0.3.2__tar.gz

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

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

@@ -396,6 +396,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