agent_os_kernel 3.1.0__py3-none-any.whl

mute_agent/__init__.py

@@ -0,0 +1,68 @@
+# Copyright (c) Microsoft Corporation.
+# Licensed under the MIT License.
+"""
+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__ = "3.1.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",
+]

mute_agent/core/__init__.py

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

mute_agent/core/execution_agent.py

@@ -0,0 +1,166 @@
+# Copyright (c) Microsoft Corporation.
+# Licensed under the MIT License.
+"""
+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

mute_agent/core/handshake_protocol.py

@@ -0,0 +1,201 @@
+# Copyright (c) Microsoft Corporation.
+# Licensed under the MIT License.
+"""
+Dynamic Semantic Handshake Protocol - The negotiation mechanism between
+The Face (Reasoning) and The Hands (Execution).
+"""
+
+from typing import Dict, List, Optional, Any
+from dataclasses import dataclass, field
+from enum import Enum
+from datetime import datetime
+
+
+class HandshakeState(Enum):
+    """States in the handshake protocol."""
+    INITIATED = "initiated"
+    NEGOTIATING = "negotiating"
+    VALIDATED = "validated"
+    ACCEPTED = "accepted"
+    REJECTED = "rejected"
+    EXECUTING = "executing"
+    COMPLETED = "completed"
+    FAILED = "failed"
+
+
+@dataclass
+class ActionProposal:
+    """A proposed action from the Reasoning Agent."""
+    action_id: str
+    parameters: Dict[str, Any]
+    context: Dict[str, Any]
+    justification: str
+    priority: float = 1.0
+    timestamp: datetime = field(default_factory=datetime.now)
+
+
+@dataclass
+class ValidationResult:
+    """Result of validating an action proposal."""
+    is_valid: bool
+    errors: List[str] = field(default_factory=list)
+    warnings: List[str] = field(default_factory=list)
+    constraints_met: List[str] = field(default_factory=list)
+    constraints_violated: List[str] = field(default_factory=list)
+
+
+@dataclass
+class HandshakeSession:
+    """A session tracking the handshake process."""
+    session_id: str
+    state: HandshakeState
+    proposal: Optional[ActionProposal] = None
+    validation_result: Optional[ValidationResult] = None
+    execution_result: Optional[Dict[str, Any]] = None
+    created_at: datetime = field(default_factory=datetime.now)
+    updated_at: datetime = field(default_factory=datetime.now)
+    metadata: Dict[str, Any] = field(default_factory=dict)
+
+
+class HandshakeProtocol:
+    """
+    The Dynamic Semantic Handshake Protocol manages the negotiation
+    between the Reasoning Agent (The Face) and the Execution Agent (The Hands).
+    
+    Instead of free-text tool invocation, actions must be negotiated against
+    the knowledge graph constraints.
+    """
+    
+    def __init__(self):
+        self.sessions: Dict[str, HandshakeSession] = {}
+        self._session_counter = 0
+    
+    def initiate_handshake(
+        self,
+        proposal: ActionProposal
+    ) -> HandshakeSession:
+        """
+        Initiate a new handshake session with an action proposal.
+        This is called by the Reasoning Agent.
+        """
+        session_id = self._generate_session_id()
+        session = HandshakeSession(
+            session_id=session_id,
+            state=HandshakeState.INITIATED,
+            proposal=proposal
+        )
+        self.sessions[session_id] = session
+        return session
+    
+    def validate_proposal(
+        self,
+        session_id: str,
+        validation_result: ValidationResult
+    ) -> HandshakeSession:
+        """
+        Validate the proposal in a session.
+        This is typically called after checking against the knowledge graph.
+        """
+        session = self.sessions.get(session_id)
+        if not session:
+            raise ValueError(f"Session {session_id} not found")
+        
+        session.validation_result = validation_result
+        session.state = HandshakeState.VALIDATED if validation_result.is_valid else HandshakeState.REJECTED
+        session.updated_at = datetime.now()
+        
+        return session
+    
+    def accept_proposal(self, session_id: str) -> HandshakeSession:
+        """
+        Accept a validated proposal for execution.
+        This transitions from validation to acceptance.
+        """
+        session = self.sessions.get(session_id)
+        if not session:
+            raise ValueError(f"Session {session_id} not found")
+        
+        if session.state != HandshakeState.VALIDATED:
+            raise ValueError(f"Cannot accept proposal in state {session.state}")
+        
+        if not session.validation_result or not session.validation_result.is_valid:
+            raise ValueError("Cannot accept invalid proposal")
+        
+        session.state = HandshakeState.ACCEPTED
+        session.updated_at = datetime.now()
+        
+        return session
+    
+    def reject_proposal(
+        self,
+        session_id: str,
+        reason: str
+    ) -> HandshakeSession:
+        """Reject a proposal with a reason."""
+        session = self.sessions.get(session_id)
+        if not session:
+            raise ValueError(f"Session {session_id} not found")
+        
+        session.state = HandshakeState.REJECTED
+        session.metadata["rejection_reason"] = reason
+        session.updated_at = datetime.now()
+        
+        return session
+    
+    def start_execution(self, session_id: str) -> HandshakeSession:
+        """
+        Start executing an accepted proposal.
+        This is called by the Execution Agent.
+        """
+        session = self.sessions.get(session_id)
+        if not session:
+            raise ValueError(f"Session {session_id} not found")
+        
+        if session.state != HandshakeState.ACCEPTED:
+            raise ValueError(f"Cannot execute proposal in state {session.state}")
+        
+        session.state = HandshakeState.EXECUTING
+        session.updated_at = datetime.now()
+        
+        return session
+    
+    def complete_execution(
+        self,
+        session_id: str,
+        result: Dict[str, Any]
+    ) -> HandshakeSession:
+        """Complete execution with results."""
+        session = self.sessions.get(session_id)
+        if not session:
+            raise ValueError(f"Session {session_id} not found")
+        
+        session.execution_result = result
+        session.state = HandshakeState.COMPLETED
+        session.updated_at = datetime.now()
+        
+        return session
+    
+    def fail_execution(
+        self,
+        session_id: str,
+        error: str
+    ) -> HandshakeSession:
+        """Mark execution as failed."""
+        session = self.sessions.get(session_id)
+        if not session:
+            raise ValueError(f"Session {session_id} not found")
+        
+        session.state = HandshakeState.FAILED
+        session.metadata["error"] = error
+        session.updated_at = datetime.now()
+        
+        return session
+    
+    def get_session(self, session_id: str) -> Optional[HandshakeSession]:
+        """Get a session by ID."""
+        return self.sessions.get(session_id)
+    
+    def _generate_session_id(self) -> str:
+        """Generate a unique session ID."""
+        self._session_counter += 1
+        return f"session_{self._session_counter}_{datetime.now().timestamp()}"

mute_agent/core/reasoning_agent.py

@@ -0,0 +1,238 @@
+# Copyright (c) Microsoft Corporation.
+# Licensed under the MIT License.
+"""
+The Face - The Reasoning Agent
+"""
+
+from typing import Dict, List, Optional, Any
+from ..knowledge_graph.multidimensional_graph import MultidimensionalKnowledgeGraph
+from ..knowledge_graph.graph_elements import Node, NodeType
+from ..super_system.router import SuperSystemRouter, RoutingResult
+from .handshake_protocol import (
+    HandshakeProtocol,
+    ActionProposal,
+    ValidationResult,
+    HandshakeSession,
+    HandshakeState
+)
+
+
+class ReasoningAgent:
+    """
+    The Face - The Reasoning Agent
+    
+    This agent is responsible for reasoning about actions and negotiating
+    with the Execution Agent through the Handshake Protocol. It does not
+    execute actions directly but proposes them based on graph constraints.
+    """
+    
+    # Maximum size for reasoning history to prevent memory bloat
+    MAX_HISTORY_SIZE = 1000
+    
+    def __init__(
+        self,
+        knowledge_graph: MultidimensionalKnowledgeGraph,
+        router: SuperSystemRouter,
+        protocol: HandshakeProtocol
+    ):
+        self.knowledge_graph = knowledge_graph
+        self.router = router
+        self.protocol = protocol
+        self.reasoning_history: List[Dict[str, Any]] = []
+    
+    def reason(self, context: Dict[str, Any]) -> RoutingResult:
+        """
+        Reason about the context and determine available actions.
+        This uses the Super System Router to prune the action space.
+        """
+        routing_result = self.router.route(context)
+        
+        # Store reasoning step (with size limit to prevent memory bloat)
+        self.reasoning_history.append({
+            "context": context,
+            "selected_dimensions": routing_result.selected_dimensions,
+            "available_actions": len(routing_result.pruned_action_space)
+        })
+        
+        # Trim history if it exceeds maximum size
+        if len(self.reasoning_history) > self.MAX_HISTORY_SIZE:
+            self.reasoning_history = self.reasoning_history[-self.MAX_HISTORY_SIZE:]
+        
+        return routing_result
+    
+    def propose_action(
+        self,
+        action_id: str,
+        parameters: Dict[str, Any],
+        context: Dict[str, Any],
+        justification: str
+    ) -> HandshakeSession:
+        """
+        Propose an action for execution.
+        This initiates the handshake protocol.
+        """
+        # Create proposal
+        proposal = ActionProposal(
+            action_id=action_id,
+            parameters=parameters,
+            context=context,
+            justification=justification
+        )
+        
+        # Initiate handshake
+        session = self.protocol.initiate_handshake(proposal)
+        
+        # Validate the proposal against the knowledge graph
+        validation_result = self._validate_proposal(proposal)
+        
+        # Update session with validation
+        self.protocol.validate_proposal(session.session_id, validation_result)
+        
+        return self.protocol.get_session(session.session_id)
+    
+    def _validate_proposal(self, proposal: ActionProposal) -> ValidationResult:
+        """
+        Validate a proposal against the knowledge graph constraints.
+        This is the core constraint checking mechanism with deep dependency resolution.
+        """
+        errors = []
+        warnings = []
+        constraints_met = []
+        constraints_violated = []
+        
+        # Get routing result for the context
+        routing_result = self.router.route(proposal.context)
+        
+        # Check if action exists in pruned action space
+        action_available = any(
+            node.id == proposal.action_id
+            for node in routing_result.pruned_action_space
+        )
+        
+        if not action_available:
+            errors.append(
+                f"Action {proposal.action_id} not available in pruned action space"
+            )
+            return ValidationResult(
+                is_valid=False,
+                errors=errors,
+                warnings=warnings,
+                constraints_met=constraints_met,
+                constraints_violated=constraints_violated
+            )
+        
+        # Deep dependency checking - find all missing dependencies across dimensions
+        all_missing_deps = self.knowledge_graph.find_all_missing_dependencies(
+            proposal.action_id,
+            routing_result.selected_dimensions,
+            proposal.context
+        )
+        
+        # If there are missing dependencies, provide detailed error messages
+        if all_missing_deps:
+            for dim_name, missing_deps in all_missing_deps.items():
+                for dep_id in missing_deps:
+                    errors.append(
+                        f"Missing dependency '{dep_id}' in dimension '{dim_name}'. "
+                        f"Please satisfy this requirement first."
+                    )
+                constraints_violated.append(dim_name)
+            
+            # Early return if dependencies are missing - no need for further validation
+            is_valid = False
+        else:
+            # Only validate constraints if no missing dependencies
+            for dim_name in routing_result.selected_dimensions:
+                # Check if action is valid in this dimension
+                subgraph = self.knowledge_graph.get_subgraph(dim_name)
+                if not subgraph:
+                    continue
+                
+                if not subgraph.validate_action(proposal.action_id, proposal.context):
+                    if dim_name not in constraints_violated:
+                        errors.append(
+                            f"Action {proposal.action_id} fails validation in dimension {dim_name}"
+                        )
+                        constraints_violated.append(dim_name)
+                else:
+                    if dim_name not in constraints_violated:
+                        constraints_met.append(dim_name)
+                
+                # Check specific constraints
+                constraints = self.knowledge_graph.get_action_constraints(
+                    proposal.action_id,
+                    dim_name
+                )
+                
+                for constraint in constraints:
+                    if not self._check_constraint(constraint, proposal):
+                        warnings.append(
+                            f"Constraint {constraint.id} may not be fully satisfied"
+                        )
+            
+            is_valid = len(errors) == 0
+        
+        return ValidationResult(
+            is_valid=is_valid,
+            errors=errors,
+            warnings=warnings,
+            constraints_met=constraints_met,
+            constraints_violated=constraints_violated
+        )
+    
+    def _check_constraint(
+        self,
+        constraint: Node,
+        proposal: ActionProposal
+    ) -> bool:
+        """Check if a specific constraint is satisfied."""
+        # Check if proposal parameters satisfy constraint attributes
+        for key, value in constraint.attributes.items():
+            if key in proposal.parameters:
+                if proposal.parameters[key] != value:
+                    return False
+        return True
+    
+    def select_best_action(
+        self,
+        context: Dict[str, Any],
+        selection_criteria: Optional[Dict[str, Any]] = None
+    ) -> Optional[Node]:
+        """
+        Select the best action from the available action space.
+        This can use various selection criteria.
+        """
+        routing_result = self.router.route(context)
+        
+        if not routing_result.pruned_action_space:
+            return None
+        
+        # If no criteria specified, return first action
+        if not selection_criteria:
+            return routing_result.pruned_action_space[0]
+        
+        # Apply selection criteria
+        scored_actions = []
+        for action in routing_result.pruned_action_space:
+            score = self._score_action(action, selection_criteria)
+            scored_actions.append((score, action))
+        
+        # Sort by score and return best
+        scored_actions.sort(reverse=True, key=lambda x: x[0])
+        return scored_actions[0][1] if scored_actions else None
+    
+    def _score_action(
+        self,
+        action: Node,
+        criteria: Dict[str, Any]
+    ) -> float:
+        """Score an action based on selection criteria."""
+        score = 0.0
+        
+        # Match attributes
+        for key, value in criteria.items():
+            if key in action.attributes:
+                if action.attributes[key] == value:
+                    score += 1.0
+        
+        return score

mute_agent/knowledge_graph/__init__.py

@@ -0,0 +1 @@
+"""Knowledge Graph components."""