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

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

@@ -0,0 +1,199 @@
+"""
+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()}"

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

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

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

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

modules/mute-agent/mute_agent/knowledge_graph/graph_elements.py

@@ -0,0 +1,63 @@
+"""
+Knowledge Graph Node and Edge definitions.
+"""
+
+from typing import Any, Dict, List, Optional
+from dataclasses import dataclass, field
+from enum import Enum
+
+
+class NodeType(Enum):
+    """Types of nodes in the knowledge graph."""
+    ACTION = "action"
+    CONSTRAINT = "constraint"
+    PRECONDITION = "precondition"
+    POSTCONDITION = "postcondition"
+    CONTEXT = "context"
+    RESOURCE = "resource"
+
+
+class EdgeType(Enum):
+    """Types of edges in the knowledge graph."""
+    REQUIRES = "requires"
+    ENABLES = "enables"
+    CONFLICTS_WITH = "conflicts_with"
+    DEPENDS_ON = "depends_on"
+    PRODUCES = "produces"
+    CONSUMES = "consumes"
+
+
+@dataclass
+class Node:
+    """A node in the knowledge graph."""
+    id: str
+    node_type: NodeType
+    attributes: Dict[str, Any] = field(default_factory=dict)
+    metadata: Dict[str, Any] = field(default_factory=dict)
+    
+    def matches_constraint(self, constraint: Dict[str, Any]) -> bool:
+        """Check if node matches given constraints."""
+        for key, value in constraint.items():
+            if key in self.attributes:
+                if self.attributes[key] != value:
+                    return False
+            elif key in self.metadata:
+                if self.metadata[key] != value:
+                    return False
+            else:
+                return False
+        return True
+
+
+@dataclass
+class Edge:
+    """An edge in the knowledge graph."""
+    source_id: str
+    target_id: str
+    edge_type: EdgeType
+    weight: float = 1.0
+    attributes: Dict[str, Any] = field(default_factory=dict)
+    
+    def is_valid(self) -> bool:
+        """Check if edge is valid."""
+        return self.weight > 0 and self.source_id and self.target_id

modules/mute-agent/mute_agent/knowledge_graph/multidimensional_graph.py

@@ -0,0 +1,168 @@
+"""
+Multidimensional Knowledge Graph implementation.
+"""
+
+from typing import Dict, List, Optional, Any, Set
+from .graph_elements import Node, Edge, NodeType, EdgeType
+from .subgraph import Subgraph, Dimension
+
+
+class MultidimensionalKnowledgeGraph:
+    """
+    A multidimensional knowledge graph that manages multiple dimensional subgraphs.
+    This implements the "Forest of Trees" approach where each dimension represents
+    a different view or constraint layer on the action space.
+    """
+    
+    def __init__(self):
+        self.dimensions: Dict[str, Dimension] = {}
+        self.subgraphs: Dict[str, Subgraph] = {}
+        self._global_nodes: Dict[str, Node] = {}
+        self._global_edges: List[Edge] = []
+    
+    def add_dimension(self, dimension: Dimension) -> None:
+        """Add a new dimension to the knowledge graph."""
+        self.dimensions[dimension.name] = dimension
+        self.subgraphs[dimension.name] = Subgraph(dimension)
+    
+    def add_node_to_dimension(self, dimension_name: str, node: Node) -> None:
+        """Add a node to a specific dimensional subgraph."""
+        if dimension_name in self.subgraphs:
+            self.subgraphs[dimension_name].add_node(node)
+            self._global_nodes[node.id] = node
+    
+    def add_edge_to_dimension(self, dimension_name: str, edge: Edge) -> None:
+        """Add an edge to a specific dimensional subgraph."""
+        if dimension_name in self.subgraphs:
+            self.subgraphs[dimension_name].add_edge(edge)
+            self._global_edges.append(edge)
+    
+    def get_dimension(self, dimension_name: str) -> Optional[Dimension]:
+        """Get a dimension by name."""
+        return self.dimensions.get(dimension_name)
+    
+    def get_subgraph(self, dimension_name: str) -> Optional[Subgraph]:
+        """Get a subgraph for a specific dimension."""
+        return self.subgraphs.get(dimension_name)
+    
+    def get_all_dimensions(self) -> List[Dimension]:
+        """Get all dimensions, sorted by priority."""
+        return sorted(self.dimensions.values(), key=lambda d: d.priority, reverse=True)
+    
+    def find_relevant_dimensions(self, context: Dict[str, Any]) -> List[str]:
+        """
+        Find dimensions that are relevant to the given context.
+        Returns dimension names sorted by priority.
+        """
+        relevant_dimensions = []
+        
+        for dim_name, dimension in self.dimensions.items():
+            # Check if context matches dimension metadata
+            if self._dimension_matches_context(dimension, context):
+                relevant_dimensions.append(dim_name)
+        
+        # Sort by priority
+        relevant_dimensions.sort(
+            key=lambda d: self.dimensions[d].priority,
+            reverse=True
+        )
+        
+        return relevant_dimensions
+    
+    def _dimension_matches_context(self, dimension: Dimension, context: Dict[str, Any]) -> bool:
+        """Check if a dimension is relevant to the given context."""
+        if not context:
+            return True
+        
+        # Check if any context keys match dimension metadata
+        for key in context.keys():
+            if key in dimension.metadata:
+                return True
+        
+        # If no specific metadata match, dimension is potentially relevant
+        return True
+    
+    def get_pruned_action_space(
+        self,
+        dimension_name: str,
+        context: Dict[str, Any]
+    ) -> List[Node]:
+        """
+        Get the pruned action space for a specific dimension and context.
+        This is the core of the action space pruning mechanism.
+        """
+        subgraph = self.subgraphs.get(dimension_name)
+        if not subgraph:
+            return []
+        
+        # Prune the subgraph based on context
+        pruned_subgraph = subgraph.prune_by_context(context)
+        
+        # Return available actions
+        return pruned_subgraph.get_action_space()
+    
+    def validate_action_across_dimensions(
+        self,
+        action_id: str,
+        dimension_names: List[str],
+        context: Optional[Dict[str, Any]] = None
+    ) -> bool:
+        """
+        Validate an action across multiple dimensions.
+        The action must be valid in all specified dimensions.
+        """
+        for dim_name in dimension_names:
+            subgraph = self.subgraphs.get(dim_name)
+            if not subgraph:
+                continue
+            
+            if not subgraph.validate_action(action_id, context):
+                return False
+        
+        return True
+    
+    def find_all_missing_dependencies(
+        self,
+        action_id: str,
+        dimension_names: List[str],
+        context: Dict[str, Any]
+    ) -> Dict[str, List[str]]:
+        """
+        Find all missing dependencies for an action across all dimensions.
+        Returns a dictionary mapping dimension names to lists of missing dependencies.
+        """
+        all_missing = {}
+        
+        for dim_name in dimension_names:
+            subgraph = self.subgraphs.get(dim_name)
+            if not subgraph:
+                continue
+            
+            missing = subgraph.find_missing_dependencies(action_id, context)
+            if missing:
+                all_missing[dim_name] = missing
+        
+        return all_missing
+    
+    def get_action_constraints(
+        self,
+        action_id: str,
+        dimension_name: str
+    ) -> List[Node]:
+        """Get all constraints associated with an action in a dimension."""
+        subgraph = self.subgraphs.get(dimension_name)
+        if not subgraph:
+            return []
+        
+        action_node = subgraph.get_node(action_id)
+        if not action_node:
+            return []
+        
+        constraints = []
+        for edge in subgraph._adjacency_list.get(action_id, []):
+            if edge.edge_type == EdgeType.REQUIRES:
+                target_node = subgraph.get_node(edge.target_id)
+                if target_node and target_node.node_type == NodeType.CONSTRAINT:
+                    constraints.append(target_node)
+        
+        return constraints