agent_os_kernel 3.1.0__py3-none-any.whl

mute_agent/knowledge_graph/graph_elements.py

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

mute_agent/knowledge_graph/multidimensional_graph.py

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

mute_agent/knowledge_graph/subgraph.py

@@ -0,0 +1,224 @@
+# Copyright (c) Microsoft Corporation.
+# Licensed under the MIT License.
+"""
+Dimensional subgraph implementation.
+"""
+
+from typing import Dict, List, Set, Optional, Any
+from dataclasses import dataclass, field
+from .graph_elements import Node, Edge, NodeType, EdgeType
+
+
+# Wildcard constant for matching any value in context
+WILDCARD_VALUE = "*"
+
+
+@dataclass
+class Dimension:
+    """A dimension in the multidimensional knowledge graph."""
+    name: str
+    description: str
+    priority: int = 0
+    metadata: Dict[str, Any] = field(default_factory=dict)
+
+
+class Subgraph:
+    """A subgraph representing a specific dimensional view of the knowledge graph."""
+    
+    def __init__(self, dimension: Dimension):
+        self.dimension = dimension
+        self.nodes: Dict[str, Node] = {}
+        self.edges: List[Edge] = []
+        self._adjacency_list: Dict[str, List[Edge]] = {}
+    
+    def add_node(self, node: Node) -> None:
+        """Add a node to the subgraph."""
+        self.nodes[node.id] = node
+        if node.id not in self._adjacency_list:
+            self._adjacency_list[node.id] = []
+    
+    def add_edge(self, edge: Edge) -> None:
+        """Add an edge to the subgraph."""
+        if edge.is_valid():
+            self.edges.append(edge)
+            if edge.source_id not in self._adjacency_list:
+                self._adjacency_list[edge.source_id] = []
+            self._adjacency_list[edge.source_id].append(edge)
+    
+    def get_node(self, node_id: str) -> Optional[Node]:
+        """Get a node by ID."""
+        return self.nodes.get(node_id)
+    
+    def get_neighbors(self, node_id: str) -> List[Node]:
+        """Get neighboring nodes."""
+        neighbors = []
+        for edge in self._adjacency_list.get(node_id, []):
+            if edge.target_id in self.nodes:
+                neighbors.append(self.nodes[edge.target_id])
+        return neighbors
+    
+    def find_nodes_by_type(self, node_type: NodeType) -> List[Node]:
+        """Find all nodes of a specific type."""
+        return [node for node in self.nodes.values() if node.node_type == node_type]
+    
+    def find_nodes_by_constraint(self, constraint: Dict[str, Any]) -> List[Node]:
+        """Find nodes matching specific constraints."""
+        return [node for node in self.nodes.values() if node.matches_constraint(constraint)]
+    
+    def get_action_space(self) -> List[Node]:
+        """Get all available actions in this subgraph."""
+        return self.find_nodes_by_type(NodeType.ACTION)
+    
+    def validate_action(self, action_id: str, context: Optional[Dict[str, Any]] = None) -> bool:
+        """Validate if an action can be executed based on graph constraints."""
+        if action_id not in self.nodes:
+            return False
+        
+        action_node = self.nodes[action_id]
+        if action_node.node_type != NodeType.ACTION:
+            return False
+        
+        # Check preconditions
+        for edge in self._adjacency_list.get(action_id, []):
+            if edge.edge_type == EdgeType.REQUIRES:
+                target_node = self.nodes.get(edge.target_id)
+                if not target_node:
+                    return False
+                # If context provided, check if requirement is satisfied
+                if context:
+                    if not self._is_requirement_satisfied(target_node, context):
+                        return False
+        
+        return True
+    
+    def _is_requirement_satisfied(self, requirement_node: Node, context: Dict[str, Any]) -> bool:
+        """Check if a requirement node is satisfied by the context."""
+        # Check if the requirement exists in context
+        req_id = requirement_node.id
+        
+        # Check if context explicitly marks this requirement as satisfied
+        if f"{req_id}_satisfied" in context:
+            return context[f"{req_id}_satisfied"]
+        
+        # Check if requirement attributes are present in context
+        for key, expected_value in requirement_node.attributes.items():
+            if key in context:
+                if context[key] == expected_value:
+                    return True
+        
+        return False
+    
+    def find_missing_dependencies(self, action_id: str, context: Dict[str, Any]) -> List[str]:
+        """
+        Find all missing dependencies for an action (deep traversal).
+        Returns a list of missing dependency IDs in order from root to leaf.
+        Handles circular dependencies gracefully.
+        """
+        if action_id not in self.nodes:
+            return [f"Action '{action_id}' not found"]
+        
+        visited = set()
+        in_progress = set()  # Track nodes currently being processed for cycle detection
+        missing_deps = []
+        
+        def traverse_dependencies(node_id: str, path: List[str]) -> None:
+            """Recursively traverse dependencies to find missing ones."""
+            if node_id in visited:
+                return
+            
+            # Cycle detection: if we're currently processing this node, we have a cycle
+            if node_id in in_progress:
+                return  # Skip circular dependency
+            
+            in_progress.add(node_id)
+            
+            # Get all requirements for this node
+            for edge in self._adjacency_list.get(node_id, []):
+                if edge.edge_type == EdgeType.REQUIRES:
+                    target_node = self.nodes.get(edge.target_id)
+                    if target_node:
+                        # Check if this requirement is satisfied
+                        if not self._is_requirement_satisfied(target_node, context):
+                            # This dependency is missing, check its dependencies first
+                            traverse_dependencies(edge.target_id, path + [node_id])
+                            # Add to missing list if not already there
+                            if edge.target_id not in missing_deps:
+                                missing_deps.append(edge.target_id)
+            
+            in_progress.remove(node_id)
+            visited.add(node_id)
+        
+        traverse_dependencies(action_id, [])
+        return missing_deps
+    
+    def get_dependency_chain(self, action_id: str) -> List[List[str]]:
+        """
+        Get all dependency chains for an action.
+        Returns a list of chains, where each chain is a list of node IDs.
+        Handles circular dependencies by detecting and skipping cycles.
+        """
+        if action_id not in self.nodes:
+            return []
+        
+        chains = []
+        visited_in_chain = set()  # Track nodes in current chain for cycle detection
+        
+        def traverse_chain(node_id: str, current_chain: List[str]) -> None:
+            """Recursively build dependency chains with cycle detection."""
+            # Cycle detection: if node is already in current chain, we have a cycle
+            if node_id in visited_in_chain:
+                return
+            
+            visited_in_chain.add(node_id)
+            
+            # Get all requirements for this node
+            requirements = []
+            for edge in self._adjacency_list.get(node_id, []):
+                if edge.edge_type == EdgeType.REQUIRES:
+                    requirements.append(edge.target_id)
+            
+            if not requirements:
+                # End of chain
+                chains.append(current_chain[:])
+            else:
+                # Continue traversing
+                for req_id in requirements:
+                    if req_id in self.nodes:
+                        traverse_chain(req_id, current_chain + [req_id])
+            
+            visited_in_chain.remove(node_id)
+        
+        traverse_chain(action_id, [action_id])
+        return chains
+    
+    def prune_by_context(self, context: Dict[str, Any]) -> "Subgraph":
+        """Create a pruned version of this subgraph based on context."""
+        pruned = Subgraph(self.dimension)
+        
+        # Add nodes that match the context
+        for node in self.nodes.values():
+            if self._node_matches_context(node, context):
+                pruned.add_node(node)
+        
+        # Add edges between matching nodes
+        for edge in self.edges:
+            if edge.source_id in pruned.nodes and edge.target_id in pruned.nodes:
+                pruned.add_edge(edge)
+        
+        return pruned
+    
+    def _node_matches_context(self, node: Node, context: Dict[str, Any]) -> bool:
+        """Check if a node is relevant to the given context."""
+        if not context:
+            return True
+        
+        # Check if any context attributes match node attributes
+        for key, value in context.items():
+            if key in node.attributes:
+                if node.attributes[key] == value or value == WILDCARD_VALUE:
+                    return True
+            if key in node.metadata:
+                if node.metadata[key] == value or value == WILDCARD_VALUE:
+                    return True
+        
+        return False

mute_agent/listener/__init__.py

@@ -0,0 +1,43 @@
+# Copyright (c) Microsoft Corporation.
+# Licensed under the MIT License.
+"""
+Layer 5: Listener Agent - Reference Implementation
+
+This module provides the Listener Agent, a passive observer that monitors
+graph states and only intervenes when configured thresholds are exceeded.
+
+The Listener consolidates the full stack:
+- agent-control-plane (base orchestration)
+- scak (intelligence/knowledge)  
+- iatp (security/trust)
+- caas (context awareness)
+
+This is pure wiring - no logic that belongs in lower layers is redefined here.
+"""
+
+from .listener import ListenerAgent, ListenerState, InterventionEvent, ListenerConfig
+from .threshold_config import (
+    ThresholdConfig,
+    ThresholdType,
+    InterventionLevel,
+    ThresholdRule,
+    DEFAULT_THRESHOLDS,
+)
+from .state_observer import StateObserver, ObservationResult
+
+__all__ = [
+    # Core Listener
+    "ListenerAgent",
+    "ListenerState",
+    "InterventionEvent",
+    "ListenerConfig",
+    # Configuration
+    "ThresholdConfig",
+    "ThresholdType",
+    "InterventionLevel",
+    "ThresholdRule",
+    "DEFAULT_THRESHOLDS",
+    # Observer
+    "StateObserver",
+    "ObservationResult",
+]

mute_agent/listener/adapters/__init__.py

@@ -0,0 +1,31 @@
+# Copyright (c) Microsoft Corporation.
+# Licensed under the MIT License.
+"""
+Adapters for Layer 5 Integration
+
+These adapters provide clean interfaces to the lower-layer dependencies:
+- agent-control-plane: Base orchestration
+- scak: Intelligence/Knowledge layer
+- iatp: Security/Trust layer
+- caas: Context-as-a-Service layer
+
+The Listener Agent uses these adapters to wire together the full stack
+without reimplementing any lower-layer logic.
+"""
+
+from .base_adapter import BaseLayerAdapter, AdapterProtocol
+from .scak_adapter import IntelligenceAdapter
+from .iatp_adapter import SecurityAdapter
+from .caas_adapter import ContextAdapter
+from .control_plane_adapter import ControlPlaneAdapter
+
+__all__ = [
+    # Base
+    "BaseLayerAdapter",
+    "AdapterProtocol",
+    # Layer adapters
+    "IntelligenceAdapter",
+    "SecurityAdapter",
+    "ContextAdapter",
+    "ControlPlaneAdapter",
+]