agent_os_kernel 3.1.0__py3-none-any.whl

mute_agent/listener/threshold_config.py

@@ -0,0 +1,313 @@
+# Copyright (c) Microsoft Corporation.
+# Licensed under the MIT License.
+"""
+Threshold Configuration for Listener Agent
+
+Defines the configurable thresholds that determine when the Listener
+should intervene in graph state changes.
+
+This module provides:
+- ThresholdType: Categories of monitored conditions
+- InterventionLevel: Severity levels for responses
+- ThresholdConfig: Configuration container
+"""
+
+from typing import Dict, Any, Optional, List, Callable
+from dataclasses import dataclass, field
+from enum import Enum, auto
+
+
+class ThresholdType(Enum):
+    """Categories of conditions the Listener monitors."""
+    
+    # Graph state thresholds
+    CONSTRAINT_VIOLATION_COUNT = auto()
+    DIMENSION_CONFLICT_RATIO = auto()
+    ACTION_REJECTION_RATE = auto()
+    
+    # Security thresholds (from iatp)
+    TRUST_SCORE_MINIMUM = auto()
+    PERMISSION_ESCALATION_COUNT = auto()
+    ANOMALY_SCORE_MAXIMUM = auto()
+    
+    # Context thresholds (from caas)
+    CONTEXT_DRIFT_MAXIMUM = auto()
+    STALE_CONTEXT_AGE_SECONDS = auto()
+    AMBIGUITY_SCORE_MAXIMUM = auto()
+    
+    # Performance thresholds
+    GRAPH_TRAVERSAL_LATENCY_MS = auto()
+    HANDSHAKE_TIMEOUT_MS = auto()
+    QUEUE_DEPTH_MAXIMUM = auto()
+
+
+class InterventionLevel(Enum):
+    """Severity levels for Listener intervention responses."""
+    
+    # Passive observation only - log and continue
+    OBSERVE = "observe"
+    
+    # Warning - emit event but allow action to proceed
+    WARN = "warn"
+    
+    # Soft block - require confirmation before proceeding
+    SOFT_BLOCK = "soft_block"
+    
+    # Hard block - prevent action entirely
+    HARD_BLOCK = "hard_block"
+    
+    # Emergency - trigger system-wide alert/shutdown
+    EMERGENCY = "emergency"
+
+
+@dataclass
+class ThresholdRule:
+    """A single threshold rule configuration."""
+    
+    threshold_type: ThresholdType
+    value: float
+    intervention_level: InterventionLevel
+    description: str = ""
+    enabled: bool = True
+    
+    # Optional custom evaluation function
+    # Signature: (current_value: float, threshold: float, context: Dict) -> bool
+    custom_evaluator: Optional[Callable[[float, float, Dict], bool]] = None
+    
+    def evaluate(self, current_value: float, context: Optional[Dict[str, Any]] = None) -> bool:
+        """
+        Evaluate if the threshold has been exceeded.
+        
+        Returns True if threshold is exceeded (intervention needed).
+        """
+        if not self.enabled:
+            return False
+        
+        if self.custom_evaluator:
+            return self.custom_evaluator(current_value, self.value, context or {})
+        
+        # Default evaluation: current exceeds threshold
+        # For MINIMUM thresholds, we check if current is below
+        if "MINIMUM" in self.threshold_type.name:
+            return current_value < self.value
+        else:
+            return current_value > self.value
+
+
+@dataclass
+class ThresholdConfig:
+    """
+    Complete threshold configuration for the Listener Agent.
+    
+    This configuration determines when the Listener transitions from
+    passive observation to active intervention.
+    """
+    
+    rules: Dict[ThresholdType, ThresholdRule] = field(default_factory=dict)
+    
+    # Global settings
+    global_intervention_level: InterventionLevel = InterventionLevel.OBSERVE
+    escalation_enabled: bool = True
+    cooldown_seconds: float = 5.0
+    
+    # Aggregation settings
+    window_size_seconds: float = 60.0
+    sample_rate_hz: float = 1.0
+    
+    def add_rule(self, rule: ThresholdRule) -> None:
+        """Add or update a threshold rule."""
+        self.rules[rule.threshold_type] = rule
+    
+    def remove_rule(self, threshold_type: ThresholdType) -> None:
+        """Remove a threshold rule."""
+        self.rules.pop(threshold_type, None)
+    
+    def get_rule(self, threshold_type: ThresholdType) -> Optional[ThresholdRule]:
+        """Get a threshold rule by type."""
+        return self.rules.get(threshold_type)
+    
+    def enable_rule(self, threshold_type: ThresholdType) -> None:
+        """Enable a specific rule."""
+        if threshold_type in self.rules:
+            self.rules[threshold_type].enabled = True
+    
+    def disable_rule(self, threshold_type: ThresholdType) -> None:
+        """Disable a specific rule."""
+        if threshold_type in self.rules:
+            self.rules[threshold_type].enabled = False
+    
+    def evaluate_all(
+        self,
+        metrics: Dict[ThresholdType, float],
+        context: Optional[Dict[str, Any]] = None
+    ) -> List[ThresholdRule]:
+        """
+        Evaluate all rules against current metrics.
+        
+        Returns list of rules that were triggered (threshold exceeded).
+        """
+        triggered = []
+        for threshold_type, value in metrics.items():
+            rule = self.rules.get(threshold_type)
+            if rule and rule.evaluate(value, context):
+                triggered.append(rule)
+        return triggered
+    
+    def get_maximum_intervention_level(
+        self,
+        triggered_rules: List[ThresholdRule]
+    ) -> InterventionLevel:
+        """
+        Get the highest intervention level from triggered rules.
+        
+        Intervention levels ordered: OBSERVE < WARN < SOFT_BLOCK < HARD_BLOCK < EMERGENCY
+        """
+        if not triggered_rules:
+            return self.global_intervention_level
+        
+        level_order = [
+            InterventionLevel.OBSERVE,
+            InterventionLevel.WARN,
+            InterventionLevel.SOFT_BLOCK,
+            InterventionLevel.HARD_BLOCK,
+            InterventionLevel.EMERGENCY,
+        ]
+        
+        max_level = self.global_intervention_level
+        for rule in triggered_rules:
+            if level_order.index(rule.intervention_level) > level_order.index(max_level):
+                max_level = rule.intervention_level
+        
+        return max_level
+
+
+# Default threshold configuration for production use
+DEFAULT_THRESHOLDS = ThresholdConfig(
+    rules={
+        ThresholdType.CONSTRAINT_VIOLATION_COUNT: ThresholdRule(
+            threshold_type=ThresholdType.CONSTRAINT_VIOLATION_COUNT,
+            value=3.0,
+            intervention_level=InterventionLevel.WARN,
+            description="Warn after 3 constraint violations in observation window",
+        ),
+        ThresholdType.DIMENSION_CONFLICT_RATIO: ThresholdRule(
+            threshold_type=ThresholdType.DIMENSION_CONFLICT_RATIO,
+            value=0.5,
+            intervention_level=InterventionLevel.SOFT_BLOCK,
+            description="Soft block when >50% of dimensions conflict",
+        ),
+        ThresholdType.ACTION_REJECTION_RATE: ThresholdRule(
+            threshold_type=ThresholdType.ACTION_REJECTION_RATE,
+            value=0.8,
+            intervention_level=InterventionLevel.HARD_BLOCK,
+            description="Hard block when >80% of actions are rejected",
+        ),
+        ThresholdType.TRUST_SCORE_MINIMUM: ThresholdRule(
+            threshold_type=ThresholdType.TRUST_SCORE_MINIMUM,
+            value=0.3,
+            intervention_level=InterventionLevel.HARD_BLOCK,
+            description="Hard block when trust score falls below 0.3",
+        ),
+        ThresholdType.PERMISSION_ESCALATION_COUNT: ThresholdRule(
+            threshold_type=ThresholdType.PERMISSION_ESCALATION_COUNT,
+            value=2.0,
+            intervention_level=InterventionLevel.EMERGENCY,
+            description="Emergency alert on 2+ permission escalation attempts",
+        ),
+        ThresholdType.ANOMALY_SCORE_MAXIMUM: ThresholdRule(
+            threshold_type=ThresholdType.ANOMALY_SCORE_MAXIMUM,
+            value=0.9,
+            intervention_level=InterventionLevel.EMERGENCY,
+            description="Emergency alert on anomaly score >0.9",
+        ),
+        ThresholdType.CONTEXT_DRIFT_MAXIMUM: ThresholdRule(
+            threshold_type=ThresholdType.CONTEXT_DRIFT_MAXIMUM,
+            value=0.7,
+            intervention_level=InterventionLevel.WARN,
+            description="Warn when context drift exceeds 0.7",
+        ),
+        ThresholdType.STALE_CONTEXT_AGE_SECONDS: ThresholdRule(
+            threshold_type=ThresholdType.STALE_CONTEXT_AGE_SECONDS,
+            value=300.0,
+            intervention_level=InterventionLevel.SOFT_BLOCK,
+            description="Soft block on context older than 5 minutes",
+        ),
+        ThresholdType.AMBIGUITY_SCORE_MAXIMUM: ThresholdRule(
+            threshold_type=ThresholdType.AMBIGUITY_SCORE_MAXIMUM,
+            value=0.6,
+            intervention_level=InterventionLevel.SOFT_BLOCK,
+            description="Soft block when ambiguity score exceeds 0.6",
+        ),
+        ThresholdType.GRAPH_TRAVERSAL_LATENCY_MS: ThresholdRule(
+            threshold_type=ThresholdType.GRAPH_TRAVERSAL_LATENCY_MS,
+            value=100.0,
+            intervention_level=InterventionLevel.WARN,
+            description="Warn on graph traversal >100ms",
+        ),
+        ThresholdType.HANDSHAKE_TIMEOUT_MS: ThresholdRule(
+            threshold_type=ThresholdType.HANDSHAKE_TIMEOUT_MS,
+            value=5000.0,
+            intervention_level=InterventionLevel.HARD_BLOCK,
+            description="Hard block on handshake timeout >5s",
+        ),
+        ThresholdType.QUEUE_DEPTH_MAXIMUM: ThresholdRule(
+            threshold_type=ThresholdType.QUEUE_DEPTH_MAXIMUM,
+            value=100.0,
+            intervention_level=InterventionLevel.WARN,
+            description="Warn when action queue exceeds 100 items",
+        ),
+    },
+    global_intervention_level=InterventionLevel.OBSERVE,
+    escalation_enabled=True,
+    cooldown_seconds=5.0,
+    window_size_seconds=60.0,
+    sample_rate_hz=1.0,
+)
+
+
+# Strict threshold configuration for high-security environments
+STRICT_THRESHOLDS = ThresholdConfig(
+    rules={
+        ThresholdType.CONSTRAINT_VIOLATION_COUNT: ThresholdRule(
+            threshold_type=ThresholdType.CONSTRAINT_VIOLATION_COUNT,
+            value=1.0,
+            intervention_level=InterventionLevel.SOFT_BLOCK,
+            description="Soft block on any constraint violation",
+        ),
+        ThresholdType.TRUST_SCORE_MINIMUM: ThresholdRule(
+            threshold_type=ThresholdType.TRUST_SCORE_MINIMUM,
+            value=0.7,
+            intervention_level=InterventionLevel.HARD_BLOCK,
+            description="Hard block when trust score falls below 0.7",
+        ),
+        ThresholdType.PERMISSION_ESCALATION_COUNT: ThresholdRule(
+            threshold_type=ThresholdType.PERMISSION_ESCALATION_COUNT,
+            value=1.0,
+            intervention_level=InterventionLevel.EMERGENCY,
+            description="Emergency alert on any permission escalation attempt",
+        ),
+    },
+    global_intervention_level=InterventionLevel.WARN,
+    escalation_enabled=True,
+    cooldown_seconds=1.0,
+    window_size_seconds=30.0,
+    sample_rate_hz=10.0,
+)
+
+
+# Permissive threshold configuration for development/testing
+PERMISSIVE_THRESHOLDS = ThresholdConfig(
+    rules={
+        ThresholdType.ANOMALY_SCORE_MAXIMUM: ThresholdRule(
+            threshold_type=ThresholdType.ANOMALY_SCORE_MAXIMUM,
+            value=0.95,
+            intervention_level=InterventionLevel.WARN,
+            description="Only warn on extreme anomaly scores",
+        ),
+    },
+    global_intervention_level=InterventionLevel.OBSERVE,
+    escalation_enabled=False,
+    cooldown_seconds=30.0,
+    window_size_seconds=300.0,
+    sample_rate_hz=0.1,
+)

mute_agent/super_system/__init__.py

@@ -0,0 +1 @@
+"""Super System routing components."""

mute_agent/super_system/router.py

@@ -0,0 +1,204 @@
+# Copyright (c) Microsoft Corporation.
+# Licensed under the MIT License.
+"""
+Super System Router - Routes context to specific dimensional subgraphs.
+"""
+
+from typing import Dict, List, Optional, Any
+from dataclasses import dataclass
+from ..knowledge_graph.multidimensional_graph import MultidimensionalKnowledgeGraph
+from ..knowledge_graph.graph_elements import Node
+
+
+# Normalization mappings for common synonyms and colloquialisms
+# Note: "east" and "west" map to -1 and -2 regions respectively as these are
+# the most commonly used primary regions in AWS US availability zones
+REGION_SYNONYMS = {
+    "virginia": "us-east-1",
+    "n. virginia": "us-east-1",
+    "northern virginia": "us-east-1",
+    "us-east": "us-east-1",
+    "east": "us-east-1",  # Maps to primary east region
+    "oregon": "us-west-2",
+    "us-west": "us-west-2",
+    "west": "us-west-2",  # Maps to primary west region (Oregon, not N. California)
+    "california": "us-west-1",
+    "ohio": "us-east-2",
+}
+
+ENVIRONMENT_SYNONYMS = {
+    "production": "prod",
+    "production environment": "prod",
+    "the prod env": "prod",
+    "prod env": "prod",
+    "live": "prod",
+    "development": "dev",
+    "development environment": "dev",
+    "the dev env": "dev",
+    "dev env": "dev",
+    "staging": "stage",
+    "stage": "stage",
+    "test": "test",
+}
+
+
+@dataclass
+class RoutingResult:
+    """Result of routing a context through the Super System."""
+    selected_dimensions: List[str]
+    pruned_action_space: List[Node]
+    routing_metadata: Dict[str, Any]
+
+
+class SuperSystemRouter:
+    """
+    The Super System Router analyzes context and routes it to specific
+    dimensional subgraphs, effectively pruning the action space before
+    the agent acts.
+    """
+    
+    def __init__(self, knowledge_graph: MultidimensionalKnowledgeGraph):
+        self.knowledge_graph = knowledge_graph
+        self.routing_history: List[RoutingResult] = []
+        self.normalization_enabled = True
+        self.custom_synonyms: Dict[str, Dict[str, str]] = {
+            "region": REGION_SYNONYMS.copy(),
+            "environment": ENVIRONMENT_SYNONYMS.copy(),
+            "env": ENVIRONMENT_SYNONYMS.copy(),
+        }
+    
+    def add_synonym_mapping(self, field_name: str, synonym: str, canonical: str) -> None:
+        """Add a custom synonym mapping for normalization."""
+        if field_name not in self.custom_synonyms:
+            self.custom_synonyms[field_name] = {}
+        self.custom_synonyms[field_name][synonym.lower()] = canonical
+    
+    def normalize_context(self, context: Dict[str, Any]) -> Dict[str, Any]:
+        """
+        Normalize context values using synonym mappings.
+        This helps prevent "False Positive" rejections when users use colloquial terms.
+        """
+        if not self.normalization_enabled:
+            return context
+        
+        normalized = context.copy()
+        
+        for key, value in context.items():
+            if not isinstance(value, str):
+                continue
+            
+            # Check if we have synonym mappings for this field
+            if key in self.custom_synonyms:
+                value_lower = value.lower()
+                if value_lower in self.custom_synonyms[key]:
+                    normalized[key] = self.custom_synonyms[key][value_lower]
+        
+        return normalized
+    
+    def route(self, context: Dict[str, Any]) -> RoutingResult:
+        """
+        Route the context to appropriate dimensional subgraphs.
+        This is the core routing mechanism that implements the
+        "Forest of Trees" approach.
+        """
+        # Step 0: Normalize context to handle synonyms
+        normalized_context = self.normalize_context(context)
+        
+        # Step 1: Find relevant dimensions based on context
+        relevant_dimensions = self.knowledge_graph.find_relevant_dimensions(normalized_context)
+        
+        if not relevant_dimensions:
+            # If no specific dimensions match, use all dimensions
+            relevant_dimensions = list(self.knowledge_graph.dimensions.keys())
+        
+        # Step 2: Get pruned action spaces from each dimension
+        action_spaces = {}
+        for dim_name in relevant_dimensions:
+            action_space = self.knowledge_graph.get_pruned_action_space(
+                dim_name, normalized_context
+            )
+            action_spaces[dim_name] = action_space
+        
+        # Step 3: Intersect action spaces to find valid actions across dimensions
+        pruned_action_space = self._intersect_action_spaces(
+            action_spaces,
+            relevant_dimensions
+        )
+        
+        # Step 4: Create routing result
+        result = RoutingResult(
+            selected_dimensions=relevant_dimensions,
+            pruned_action_space=pruned_action_space,
+            routing_metadata={
+                "context": context,
+                "normalized_context": normalized_context,
+                "action_count_by_dimension": {
+                    dim: len(actions) for dim, actions in action_spaces.items()
+                },
+                "final_action_count": len(pruned_action_space)
+            }
+        )
+        
+        # Store in history
+        self.routing_history.append(result)
+        
+        return result
+    
+    def _intersect_action_spaces(
+        self,
+        action_spaces: Dict[str, List[Node]],
+        dimension_names: List[str]
+    ) -> List[Node]:
+        """
+        Intersect action spaces from multiple dimensions to find
+        actions that are valid across all dimensions.
+        """
+        if not action_spaces or not dimension_names:
+            return []
+        
+        # Start with the first dimension's action space
+        first_dim = dimension_names[0]
+        common_actions = {node.id: node for node in action_spaces.get(first_dim, [])}
+        
+        # Intersect with other dimensions
+        for dim_name in dimension_names[1:]:
+            dim_actions = {node.id for node in action_spaces.get(dim_name, [])}
+            common_actions = {
+                action_id: node
+                for action_id, node in common_actions.items()
+                if action_id in dim_actions
+            }
+        
+        return list(common_actions.values())
+    
+    def get_routing_statistics(self) -> Dict[str, Any]:
+        """Get statistics about routing operations."""
+        if not self.routing_history:
+            return {
+                "total_routings": 0,
+                "avg_dimensions_per_routing": 0,
+                "avg_actions_per_routing": 0
+            }
+        
+        total_routings = len(self.routing_history)
+        total_dimensions = sum(
+            len(result.selected_dimensions) for result in self.routing_history
+        )
+        total_actions = sum(
+            len(result.pruned_action_space) for result in self.routing_history
+        )
+        
+        return {
+            "total_routings": total_routings,
+            "avg_dimensions_per_routing": total_dimensions / total_routings if total_routings > 0 else 0,
+            "avg_actions_per_routing": total_actions / total_routings if total_routings > 0 else 0,
+            "dimension_usage": self._get_dimension_usage_stats()
+        }
+    
+    def _get_dimension_usage_stats(self) -> Dict[str, int]:
+        """Get statistics on how often each dimension is used."""
+        usage = {}
+        for result in self.routing_history:
+            for dim_name in result.selected_dimensions:
+                usage[dim_name] = usage.get(dim_name, 0) + 1
+        return usage

mute_agent/visualization/__init__.py

@@ -0,0 +1,10 @@
+# Copyright (c) Microsoft Corporation.
+# Licensed under the MIT License.
+"""
+Visualization module for Mute Agent.
+Provides graph debugging and execution trace visualization.
+"""
+
+from .graph_debugger import GraphDebugger, ExecutionTrace, NodeState
+
+__all__ = ['GraphDebugger', 'ExecutionTrace', 'NodeState']