agent-os-kernel 1.1.0__py3-none-any.whl → 1.2.0__py3-none-any.whl

modules/mute-agent/experiments/visualize.py

@@ -0,0 +1,400 @@
+"""
+Visualization Module for Mute Agent Benchmarks
+
+Generates charts showing the "Cost of Curiosity":
+- Cost vs. Ambiguity chart
+- Token efficiency comparisons
+- Latency comparisons
+
+Key insight from PRD:
+"Mute Agent is a flat line (cost is constant).
+Interactive Agent cost explodes as ambiguity rises."
+"""
+
+import json
+import sys
+import os
+from typing import Dict, Any, List, Tuple, Optional
+from dataclasses import dataclass
+
+try:
+    import matplotlib.pyplot as plt
+    import matplotlib.patches as mpatches
+    MATPLOTLIB_AVAILABLE = True
+except ImportError:
+    MATPLOTLIB_AVAILABLE = False
+    print("Warning: matplotlib not available. Install with: pip install matplotlib")
+
+
+@dataclass
+class AmbiguityDataPoint:
+    """A data point for the Cost vs. Ambiguity chart."""
+    ambiguity_level: float  # 0.0 to 1.0 (0% to 100%)
+    mute_tokens: int
+    interactive_tokens: int
+    scenario_title: str
+
+
+def generate_cost_vs_ambiguity_chart(
+    results: List[Dict[str, Any]],
+    output_path: str = "cost_vs_ambiguity.png",
+    title: str = "The Cost of Curiosity: Token Cost vs. Ambiguity"
+):
+    """
+    Generate the key chart from the PRD:
+    X-Axis: Ambiguity Level (0% to 100%)
+    Y-Axis: Token Cost
+    
+    Expected:
+    - Mute Agent: Flat line (cost is constant regardless of ambiguity)
+    - Interactive Agent: Cost explodes as ambiguity increases (more reflection loops)
+    
+    Args:
+        results: List of benchmark results
+        output_path: Where to save the chart
+        title: Chart title
+    """
+    if not MATPLOTLIB_AVAILABLE:
+        print("Cannot generate chart: matplotlib not installed")
+        return
+    
+    # Extract data points
+    data_points: List[AmbiguityDataPoint] = []
+    
+    for result in results:
+        # Calculate ambiguity level based on scenario characteristics
+        ambiguity = _calculate_ambiguity_level(result)
+        
+        data_points.append(AmbiguityDataPoint(
+            ambiguity_level=ambiguity,
+            mute_tokens=result.get("mute_tokens", 0),
+            interactive_tokens=result.get("interactive_tokens", 0),
+            scenario_title=result.get("scenario_title", "Unknown")
+        ))
+    
+    # Sort by ambiguity level
+    data_points.sort(key=lambda x: x.ambiguity_level)
+    
+    # Extract data for plotting
+    ambiguity_levels = [dp.ambiguity_level * 100 for dp in data_points]  # Convert to percentage
+    mute_tokens = [dp.mute_tokens for dp in data_points]
+    interactive_tokens = [dp.interactive_tokens for dp in data_points]
+    
+    # Create figure
+    plt.figure(figsize=(12, 7))
+    
+    # Plot lines
+    plt.plot(ambiguity_levels, mute_tokens, 
+             marker='o', linewidth=2, markersize=8,
+             color='#2ecc71', label='Mute Agent (Graph-Constrained)',
+             alpha=0.8)
+    
+    plt.plot(ambiguity_levels, interactive_tokens,
+             marker='s', linewidth=2, markersize=8,
+             color='#e74c3c', label='Interactive Agent (SOTA)',
+             alpha=0.8)
+    
+    # Add mean lines
+    mute_mean = sum(mute_tokens) / len(mute_tokens) if mute_tokens else 0
+    interactive_mean = sum(interactive_tokens) / len(interactive_tokens) if interactive_tokens else 0
+    
+    plt.axhline(y=mute_mean, color='#2ecc71', linestyle='--', 
+                alpha=0.5, linewidth=1, label=f'Mute Avg: {mute_mean:.0f} tokens')
+    plt.axhline(y=interactive_mean, color='#e74c3c', linestyle='--',
+                alpha=0.5, linewidth=1, label=f'Interactive Avg: {interactive_mean:.0f} tokens')
+    
+    # Styling
+    plt.xlabel('Ambiguity Level (%)', fontsize=12, fontweight='bold')
+    plt.ylabel('Token Cost', fontsize=12, fontweight='bold')
+    plt.title(title, fontsize=14, fontweight='bold', pad=20)
+    plt.legend(loc='upper left', fontsize=10)
+    plt.grid(True, alpha=0.3, linestyle='--')
+    
+    # Add annotation
+    if data_points:
+        max_ambiguity_point = max(data_points, key=lambda x: x.ambiguity_level)
+        reduction = ((max_ambiguity_point.interactive_tokens - max_ambiguity_point.mute_tokens) / 
+                    max_ambiguity_point.interactive_tokens * 100)
+        
+        plt.text(0.5, 0.95, 
+                f'At High Ambiguity: {reduction:.1f}% Token Reduction\n'
+                f'Mute Agent: Constant Cost (Graph Constraints)\n'
+                f'Interactive Agent: Increasing Cost (Reflection Loops)',
+                transform=plt.gca().transAxes,
+                bbox=dict(boxstyle='round', facecolor='wheat', alpha=0.5),
+                verticalalignment='top',
+                horizontalalignment='center',
+                fontsize=9)
+    
+    plt.tight_layout()
+    plt.savefig(output_path, dpi=300, bbox_inches='tight')
+    print(f"Chart saved to: {output_path}")
+    plt.close()
+
+
+def generate_metrics_comparison_chart(
+    report: Dict[str, Any],
+    output_path: str = "metrics_comparison.png"
+):
+    """
+    Generate a bar chart comparing key metrics.
+    
+    Args:
+        report: Benchmark report dictionary
+        output_path: Where to save the chart
+    """
+    if not MATPLOTLIB_AVAILABLE:
+        print("Cannot generate chart: matplotlib not installed")
+        return
+    
+    # Extract metrics
+    metrics = {
+        'Avg Tokens': {
+            'Mute': report.get('mute_avg_tokens', 0),
+            'Interactive': report.get('interactive_avg_tokens', 0),
+            'unit': 'tokens'
+        },
+        'Avg Latency': {
+            'Mute': report.get('mute_avg_latency_ms', 0),
+            'Interactive': report.get('interactive_avg_latency_ms', 0),
+            'unit': 'ms'
+        },
+        'Avg Turns': {
+            'Mute': report.get('mute_avg_turns', 0),
+            'Interactive': report.get('interactive_avg_turns', 0),
+            'unit': 'turns'
+        },
+        'User Interactions': {
+            'Mute': report.get('mute_total_user_interactions', 0),
+            'Interactive': report.get('interactive_total_user_interactions', 0),
+            'unit': 'count'
+        }
+    }
+    
+    # Create figure with subplots
+    fig, axes = plt.subplots(2, 2, figsize=(14, 10))
+    fig.suptitle('Mute Agent vs Interactive Agent: Key Metrics Comparison', 
+                 fontsize=16, fontweight='bold')
+    
+    colors = ['#2ecc71', '#e74c3c']  # Green for Mute, Red for Interactive
+    
+    for idx, (metric_name, metric_data) in enumerate(metrics.items()):
+        ax = axes[idx // 2, idx % 2]
+        
+        values = [metric_data['Mute'], metric_data['Interactive']]
+        bars = ax.bar(['Mute Agent', 'Interactive Agent'], values, color=colors, alpha=0.8)
+        
+        ax.set_title(metric_name, fontsize=12, fontweight='bold')
+        ax.set_ylabel(metric_data['unit'], fontsize=10)
+        ax.grid(True, alpha=0.3, axis='y', linestyle='--')
+        
+        # Add value labels on bars
+        for bar, value in zip(bars, values):
+            height = bar.get_height()
+            ax.text(bar.get_x() + bar.get_width()/2., height,
+                   f'{value:.1f}',
+                   ha='center', va='bottom', fontsize=10, fontweight='bold')
+        
+        # Add improvement percentage
+        if metric_data['Interactive'] > 0 and metric_data['Mute'] < metric_data['Interactive']:
+            improvement = ((metric_data['Interactive'] - metric_data['Mute']) / 
+                         metric_data['Interactive'] * 100)
+            ax.text(0.5, 0.95, f'↓ {improvement:.1f}% improvement',
+                   transform=ax.transAxes,
+                   ha='center', va='top',
+                   bbox=dict(boxstyle='round', facecolor='lightgreen', alpha=0.7),
+                   fontsize=9)
+    
+    plt.tight_layout()
+    plt.savefig(output_path, dpi=300, bbox_inches='tight')
+    print(f"Metrics comparison chart saved to: {output_path}")
+    plt.close()
+
+
+def generate_scenario_class_breakdown(
+    results: List[Dict[str, Any]],
+    output_path: str = "scenario_breakdown.png"
+):
+    """
+    Generate a breakdown by scenario class (stale_state, ghost_resource, privilege_escalation).
+    
+    Args:
+        results: List of benchmark results
+        output_path: Where to save the chart
+    """
+    if not MATPLOTLIB_AVAILABLE:
+        print("Cannot generate chart: matplotlib not installed")
+        return
+    
+    # Group by scenario class
+    classes = {}
+    for result in results:
+        scenario_class = result.get('scenario_id', '').split('_')[0] + '_' + result.get('scenario_id', '').split('_')[1]
+        if scenario_class not in classes:
+            classes[scenario_class] = {
+                'mute_tokens': [],
+                'interactive_tokens': [],
+                'count': 0
+            }
+        
+        classes[scenario_class]['mute_tokens'].append(result.get('mute_tokens', 0))
+        classes[scenario_class]['interactive_tokens'].append(result.get('interactive_tokens', 0))
+        classes[scenario_class]['count'] += 1
+    
+    # Calculate averages
+    class_names = []
+    mute_avgs = []
+    interactive_avgs = []
+    
+    for class_name, data in classes.items():
+        class_names.append(class_name.replace('_', ' ').title())
+        mute_avgs.append(sum(data['mute_tokens']) / len(data['mute_tokens']) if data['mute_tokens'] else 0)
+        interactive_avgs.append(sum(data['interactive_tokens']) / len(data['interactive_tokens']) if data['interactive_tokens'] else 0)
+    
+    # Create grouped bar chart
+    x = range(len(class_names))
+    width = 0.35
+    
+    fig, ax = plt.subplots(figsize=(12, 7))
+    
+    bars1 = ax.bar([i - width/2 for i in x], mute_avgs, width, 
+                   label='Mute Agent', color='#2ecc71', alpha=0.8)
+    bars2 = ax.bar([i + width/2 for i in x], interactive_avgs, width,
+                   label='Interactive Agent', color='#e74c3c', alpha=0.8)
+    
+    ax.set_xlabel('Scenario Class', fontsize=12, fontweight='bold')
+    ax.set_ylabel('Average Token Cost', fontsize=12, fontweight='bold')
+    ax.set_title('Token Cost by Scenario Class', fontsize=14, fontweight='bold')
+    ax.set_xticks(x)
+    ax.set_xticklabels(class_names, rotation=15, ha='right')
+    ax.legend(fontsize=10)
+    ax.grid(True, alpha=0.3, axis='y', linestyle='--')
+    
+    # Add value labels
+    for bars in [bars1, bars2]:
+        for bar in bars:
+            height = bar.get_height()
+            ax.text(bar.get_x() + bar.get_width()/2., height,
+                   f'{height:.0f}',
+                   ha='center', va='bottom', fontsize=9)
+    
+    plt.tight_layout()
+    plt.savefig(output_path, dpi=300, bbox_inches='tight')
+    print(f"Scenario breakdown chart saved to: {output_path}")
+    plt.close()
+
+
+def _calculate_ambiguity_level(result: Dict[str, Any]) -> float:
+    """
+    Calculate ambiguity level for a scenario (0.0 to 1.0).
+    
+    Factors that increase ambiguity:
+    - Multiple services with same name
+    - Pronoun usage ("it", "the service")
+    - Stale context
+    - Partial state
+    
+    Args:
+        result: Benchmark result dictionary
+    
+    Returns:
+        Ambiguity level from 0.0 (clear) to 1.0 (highly ambiguous)
+    """
+    scenario_id = result.get('scenario_id', '')
+    
+    # Base ambiguity by scenario class
+    if 'stale_state' in scenario_id:
+        base_ambiguity = 0.7  # High ambiguity - context is unclear
+    elif 'ghost_resource' in scenario_id:
+        base_ambiguity = 0.5  # Medium ambiguity - state is unclear
+    elif 'privilege' in scenario_id:
+        base_ambiguity = 0.3  # Low ambiguity - permissions are policy-based
+    else:
+        base_ambiguity = 0.5
+    
+    # Adjust based on whether Interactive Agent needed clarification
+    if result.get('interactive_needed_clarification', False):
+        base_ambiguity = min(1.0, base_ambiguity + 0.2)
+    
+    # Adjust based on number of turns taken
+    turns = result.get('interactive_turns', 1)
+    if turns > 1:
+        base_ambiguity = min(1.0, base_ambiguity + (turns - 1) * 0.1)
+    
+    return base_ambiguity
+
+
+def generate_all_visualizations(
+    benchmark_results_path: str,
+    output_dir: str = "."
+):
+    """
+    Generate all visualizations from a benchmark results file.
+    
+    Args:
+        benchmark_results_path: Path to benchmark results JSON
+        output_dir: Directory to save charts
+    """
+    if not MATPLOTLIB_AVAILABLE:
+        print("Cannot generate visualizations: matplotlib not installed")
+        print("Install with: pip install matplotlib")
+        return
+    
+    # Load results
+    with open(benchmark_results_path, 'r') as f:
+        report = json.load(f)
+    
+    results = report.get('results', [])
+    
+    if not results:
+        print("No results found in benchmark report")
+        return
+    
+    # Ensure output directory exists
+    os.makedirs(output_dir, exist_ok=True)
+    
+    # Generate all charts
+    print("Generating visualizations...")
+    
+    generate_cost_vs_ambiguity_chart(
+        results,
+        output_path=os.path.join(output_dir, "cost_vs_ambiguity.png")
+    )
+    
+    generate_metrics_comparison_chart(
+        report,
+        output_path=os.path.join(output_dir, "metrics_comparison.png")
+    )
+    
+    generate_scenario_class_breakdown(
+        results,
+        output_path=os.path.join(output_dir, "scenario_breakdown.png")
+    )
+    
+    print(f"\nAll visualizations saved to: {output_dir}")
+
+
+def main():
+    """CLI for generating visualizations."""
+    import argparse
+    
+    parser = argparse.ArgumentParser(
+        description="Generate visualizations from benchmark results"
+    )
+    parser.add_argument(
+        "results_file",
+        help="Path to benchmark results JSON file"
+    )
+    parser.add_argument(
+        "--output-dir",
+        default=".",
+        help="Directory to save charts (default: current directory)"
+    )
+    
+    args = parser.parse_args()
+    
+    generate_all_visualizations(args.results_file, args.output_dir)
+
+
+if __name__ == "__main__":
+    main()

modules/mute-agent/mute_agent/__init__.py

@@ -0,0 +1,66 @@
+"""
+Mute Agent - Decoupling Reasoning from Execution
+
+Layer 5 Reference Implementation: A Listener agent that monitors graph states
+without interfering until configured thresholds are exceeded.
+
+Consolidated Stack:
+- agent-control-plane: Base orchestration
+- scak: Intelligence/Knowledge layer
+- iatp: Security/Trust layer  
+- caas: Context-as-a-Service layer
+"""
+
+__version__ = "0.2.0"
+
+# Core components
+from .core.reasoning_agent import ReasoningAgent
+from .core.execution_agent import ExecutionAgent
+from .core.handshake_protocol import HandshakeProtocol
+from .knowledge_graph.multidimensional_graph import MultidimensionalKnowledgeGraph
+from .super_system.router import SuperSystemRouter
+
+# Layer 5: Listener Agent
+from .listener import (
+    ListenerAgent,
+    ListenerState,
+    InterventionEvent,
+    ThresholdConfig,
+    ThresholdType,
+    InterventionLevel,
+    DEFAULT_THRESHOLDS,
+    StateObserver,
+    ObservationResult,
+)
+
+# Layer adapters
+from .listener.adapters import (
+    ControlPlaneAdapter,
+    IntelligenceAdapter,
+    SecurityAdapter,
+    ContextAdapter,
+)
+
+__all__ = [
+    # Core
+    "ReasoningAgent",
+    "ExecutionAgent",
+    "HandshakeProtocol",
+    "MultidimensionalKnowledgeGraph",
+    "SuperSystemRouter",
+    # Layer 5: Listener
+    "ListenerAgent",
+    "ListenerState",
+    "InterventionEvent",
+    "ThresholdConfig",
+    "ThresholdType",
+    "InterventionLevel",
+    "DEFAULT_THRESHOLDS",
+    "StateObserver",
+    "ObservationResult",
+    # Adapters
+    "ControlPlaneAdapter",
+    "IntelligenceAdapter",
+    "SecurityAdapter",
+    "ContextAdapter",
+]

modules/mute-agent/mute_agent/core/__init__.py

@@ -0,0 +1 @@
+"""Core components of the Mute Agent system."""

modules/mute-agent/mute_agent/core/execution_agent.py

@@ -0,0 +1,164 @@
+"""
+The Hands - The Execution Agent
+"""
+
+from typing import Dict, List, Optional, Any, Callable
+from .handshake_protocol import HandshakeProtocol, HandshakeSession, HandshakeState
+
+
+class ExecutionAgent:
+    """
+    The Hands - The Execution Agent
+    
+    This agent is responsible for executing actions that have been negotiated
+    and validated through the Handshake Protocol. It does not reason about
+    actions but simply executes them when properly authorized.
+    """
+    
+    def __init__(self, protocol: HandshakeProtocol):
+        self.protocol = protocol
+        self.execution_handlers: Dict[str, Callable] = {}
+        self.execution_history: List[Dict[str, Any]] = []
+    
+    def register_action_handler(
+        self,
+        action_id: str,
+        handler: Callable[[Dict[str, Any]], Dict[str, Any]]
+    ) -> None:
+        """
+        Register a handler function for a specific action.
+        The handler receives parameters and returns results.
+        """
+        self.execution_handlers[action_id] = handler
+    
+    def execute(self, session_id: str) -> HandshakeSession:
+        """
+        Execute an action from an accepted handshake session.
+        This is the main execution entry point.
+        """
+        session = self.protocol.get_session(session_id)
+        
+        if not session:
+            raise ValueError(f"Session {session_id} not found")
+        
+        if session.state != HandshakeState.ACCEPTED:
+            raise ValueError(
+                f"Cannot execute session in state {session.state}. "
+                f"Session must be in ACCEPTED state."
+            )
+        
+        if not session.proposal:
+            raise ValueError("Session has no proposal")
+        
+        # Mark as executing
+        self.protocol.start_execution(session_id)
+        
+        try:
+            # Execute the action
+            result = self._execute_action(
+                session.proposal.action_id,
+                session.proposal.parameters,
+                session.proposal.context
+            )
+            
+            # Mark as completed
+            self.protocol.complete_execution(session_id, result)
+            
+            # Store in history
+            self.execution_history.append({
+                "session_id": session_id,
+                "action_id": session.proposal.action_id,
+                "result": result,
+                "success": True
+            })
+            
+        except Exception as e:
+            # Mark as failed
+            self.protocol.fail_execution(session_id, str(e))
+            
+            # Store in history
+            self.execution_history.append({
+                "session_id": session_id,
+                "action_id": session.proposal.action_id,
+                "error": str(e),
+                "success": False
+            })
+            
+            raise
+        
+        return self.protocol.get_session(session_id)
+    
+    def _execute_action(
+        self,
+        action_id: str,
+        parameters: Dict[str, Any],
+        context: Dict[str, Any]
+    ) -> Dict[str, Any]:
+        """
+        Execute a specific action using its registered handler.
+        """
+        handler = self.execution_handlers.get(action_id)
+        
+        if not handler:
+            # If no handler registered, return a default result
+            return {
+                "status": "no_handler",
+                "message": f"No handler registered for action {action_id}",
+                "action_id": action_id,
+                "parameters": parameters
+            }
+        
+        # Call the handler
+        result = handler(parameters)
+        
+        return {
+            "status": "success",
+            "action_id": action_id,
+            "result": result
+        }
+    
+    def can_execute(self, session_id: str) -> bool:
+        """Check if a session can be executed."""
+        session = self.protocol.get_session(session_id)
+        
+        if not session:
+            return False
+        
+        if session.state != HandshakeState.ACCEPTED:
+            return False
+        
+        if not session.proposal:
+            return False
+        
+        # Check if handler is registered (optional)
+        return True
+    
+    def get_execution_statistics(self) -> Dict[str, Any]:
+        """Get statistics about execution operations."""
+        if not self.execution_history:
+            return {
+                "total_executions": 0,
+                "successful_executions": 0,
+                "failed_executions": 0,
+                "success_rate": 0.0
+            }
+        
+        total = len(self.execution_history)
+        successful = sum(1 for exec in self.execution_history if exec["success"])
+        failed = total - successful
+        
+        return {
+            "total_executions": total,
+            "successful_executions": successful,
+            "failed_executions": failed,
+            "success_rate": successful / total if total > 0 else 0.0,
+            "actions_executed": self._get_action_counts()
+        }
+    
+    def _get_action_counts(self) -> Dict[str, int]:
+        """Get counts of how many times each action was executed."""
+        counts = {}
+        for exec in self.execution_history:
+            action_id = exec["action_id"]
+            counts[action_id] = counts.get(action_id, 0) + 1
+        return counts