attune-ai 2.0.0__py3-none-any.whl

attune/exceptions.py

@@ -0,0 +1,123 @@
+"""Custom exceptions for the Empathy Framework
+
+Provides domain-specific exceptions for better error handling and debugging.
+
+Copyright 2025 Smart AI Memory, LLC
+Licensed under Fair Source 0.9
+"""
+
+
+class EmpathyFrameworkError(Exception):
+    """Base exception for all Empathy Framework errors
+
+    All custom exceptions in the framework inherit from this class,
+    making it easy to catch any framework-specific error.
+    """
+
+
+class ValidationError(EmpathyFrameworkError):
+    """Raised when input validation fails
+
+    Examples:
+        - Empty strings when non-empty required
+        - Wrong type provided
+        - Invalid value ranges
+
+    """
+
+
+class PatternNotFoundError(EmpathyFrameworkError):
+    """Raised when a pattern lookup fails
+
+    Examples:
+        - Pattern ID doesn't exist in library
+        - No patterns match query criteria
+
+    """
+
+    def __init__(self, pattern_id: str, message: str | None = None):
+        self.pattern_id = pattern_id
+        if message is None:
+            message = f"Pattern not found: {pattern_id}"
+        super().__init__(message)
+
+
+class TrustThresholdError(EmpathyFrameworkError):
+    """Raised when trust level is insufficient for an operation
+
+    Examples:
+        - Trust too low for proactive actions
+        - Erosion loop detected
+
+    """
+
+    def __init__(self, current_trust: float, required_trust: float, message: str | None = None):
+        self.current_trust = current_trust
+        self.required_trust = required_trust
+        if message is None:
+            message = f"Trust level {current_trust:.2f} is below required {required_trust:.2f}"
+        super().__init__(message)
+
+
+class ConfidenceThresholdError(EmpathyFrameworkError):
+    """Raised when confidence is too low for proactive action
+
+    Examples:
+        - Pattern confidence below threshold
+        - Prediction uncertainty too high
+
+    """
+
+    def __init__(self, confidence: float, threshold: float, message: str | None = None):
+        self.confidence = confidence
+        self.threshold = threshold
+        if message is None:
+            message = f"Confidence {confidence:.2f} is below threshold {threshold:.2f}"
+        super().__init__(message)
+
+
+class EmpathyLevelError(EmpathyFrameworkError):
+    """Raised when empathy level operations fail
+
+    Examples:
+        - Invalid level number
+        - Level not yet achieved
+        - Cannot regress to lower level
+
+    """
+
+    def __init__(self, level: int, message: str | None = None):
+        self.level = level
+        if message is None:
+            message = f"Invalid empathy level: {level}"
+        super().__init__(message)
+
+
+class LeveragePointError(EmpathyFrameworkError):
+    """Raised when leverage point analysis fails
+
+    Examples:
+        - No leverage points found
+        - Intervention feasibility too low
+
+    """
+
+
+class FeedbackLoopError(EmpathyFrameworkError):
+    """Raised when feedback loop detection or management fails
+
+    Examples:
+        - Vicious cycle detected but cannot break
+        - Insufficient history for loop detection
+
+    """
+
+
+class CollaborationStateError(EmpathyFrameworkError):
+    """Raised when collaboration state operations fail
+
+    Examples:
+        - Invalid state transition
+        - State corruption detected
+
+    """

attune/feedback_loops.py

@@ -0,0 +1,373 @@
+"""Feedback Loop Detection for AI-Human Collaboration
+
+Detects and analyzes reinforcing and balancing feedback loops in AI-human
+collaboration based on systems thinking (Meadows, Senge).
+
+Feedback loops are circular causal relationships that either amplify
+(reinforcing) or stabilize (balancing) system behaviors.
+
+Copyright 2025 Smart AI Memory, LLC
+Licensed under Fair Source 0.9
+"""
+
+from dataclasses import dataclass, field
+from datetime import datetime
+from enum import Enum
+from typing import Any
+
+
+class LoopType(Enum):
+    """Types of feedback loops"""
+
+    REINFORCING = "reinforcing"  # Amplifying, can be virtuous or vicious
+    BALANCING = "balancing"  # Stabilizing, seeks equilibrium
+
+
+class LoopPolarity(Enum):
+    """Polarity of reinforcing loops"""
+
+    VIRTUOUS = "virtuous"  # Positive reinforcing loop (good spiral)
+    VICIOUS = "vicious"  # Negative reinforcing loop (bad spiral)
+    NEUTRAL = "neutral"  # Balancing loops
+
+
+@dataclass
+class FeedbackLoop:
+    """A detected feedback loop in the system
+
+    Feedback loops are circular causal chains where:
+    A -> B -> C -> A (with delays and polarities)
+    """
+
+    loop_id: str
+    loop_type: LoopType
+    polarity: LoopPolarity
+    description: str
+    components: list[str]  # Variables involved in the loop
+    strength: float = 0.5  # 0.0-1.0, how strong is the loop effect
+    detected_at: datetime = field(default_factory=datetime.now)
+    evidence: list[dict[str, Any]] = field(default_factory=list)
+    intervention_points: list[str] = field(default_factory=list)
+
+
+class FeedbackLoopDetector:
+    """Detects reinforcing and balancing feedback loops in AI-human collaboration
+
+    Based on systems thinking (Meadows, Senge):
+
+    **Common Loops:**
+    - R1: Trust building loop (virtuous reinforcing)
+      - Success → Trust ↑ → Willingness to delegate ↑ → More success
+    - R2: Trust erosion loop (vicious reinforcing)
+      - Failure → Trust ↓ → Micromanagement ↑ → More failures
+    - B1: Quality control loop (balancing)
+      - Error rate ↑ → Guardrails ↑ → Error rate ↓
+
+    **Reinforcing Loops (R):**
+    - Amplify change (exponential growth or decay)
+    - Can be virtuous (good spiral) or vicious (bad spiral)
+    - Examples: compound interest, viral growth, panic
+
+    **Balancing Loops (B):**
+    - Seek equilibrium
+    - Stabilize systems
+    - Examples: thermostat, supply-demand, homeostasis
+
+    Example:
+        >>> detector = FeedbackLoopDetector()
+        >>> history = [
+        ...     {"trust": 0.5, "success": True},
+        ...     {"trust": 0.6, "success": True},
+        ...     {"trust": 0.7, "success": True}
+        ... ]
+        >>> loops = detector.detect_active_loop(history)
+        >>> print(loops["dominant_loop"])
+
+    """
+
+    def __init__(self):
+        """Initialize FeedbackLoopDetector"""
+        self.detected_loops: list[FeedbackLoop] = []
+        self._initialize_standard_loops()
+
+    def _initialize_standard_loops(self):
+        """Initialize standard loops from systems thinking literature"""
+        # R1: Trust building loop (virtuous)
+        trust_building = FeedbackLoop(
+            loop_id="R1_trust_building",
+            loop_type=LoopType.REINFORCING,
+            polarity=LoopPolarity.VIRTUOUS,
+            description="Trust building cycle: Success → Trust ↑ → Delegation ↑ → More Success",
+            components=["trust", "success_rate", "delegation_level"],
+            intervention_points=["celebrate_wins", "increase_transparency"],
+        )
+
+        # R2: Trust erosion loop (vicious)
+        trust_erosion = FeedbackLoop(
+            loop_id="R2_trust_erosion",
+            loop_type=LoopType.REINFORCING,
+            polarity=LoopPolarity.VICIOUS,
+            description="Trust erosion: Failure → Trust ↓ → Micromanagement ↑ → More Failures",
+            components=["trust", "failure_rate", "oversight_level"],
+            intervention_points=["break_cycle", "rebuild_confidence", "adjust_scope"],
+        )
+
+        # B1: Quality control loop (balancing)
+        quality_control = FeedbackLoop(
+            loop_id="B1_quality_control",
+            loop_type=LoopType.BALANCING,
+            polarity=LoopPolarity.NEUTRAL,
+            description="Quality control: Error Rate ↑ → Guardrails ↑ → Error Rate ↓",
+            components=["error_rate", "guardrail_strength", "intervention_frequency"],
+            intervention_points=["adjust_guardrails", "calibrate_sensitivity"],
+        )
+
+        # Add to detected loops
+        self.detected_loops.extend([trust_building, trust_erosion, quality_control])
+
+    def detect_active_loop(self, session_history: list[dict[str, Any]]) -> dict[str, Any]:
+        """Analyze session history for active feedback loops
+
+        Examines trends in trust, success rate, and collaboration metrics
+        to determine which feedback loop is currently dominant.
+
+        Args:
+            session_history: List of session state snapshots over time
+
+        Returns:
+            Dict with:
+            - dominant_loop: The most active loop
+            - loop_strength: How strongly the loop is operating (0-1)
+            - trend: "amplifying" or "stabilizing"
+            - recommendation: Suggested intervention
+
+        Example:
+            >>> history = [
+            ...     {"trust": 0.5, "success_rate": 0.6},
+            ...     {"trust": 0.6, "success_rate": 0.7},
+            ...     {"trust": 0.7, "success_rate": 0.8}
+            ... ]
+            >>> result = detector.detect_active_loop(history)
+
+        """
+        if len(session_history) < 2:
+            return {
+                "dominant_loop": None,
+                "loop_strength": 0.0,
+                "trend": "insufficient_data",
+                "recommendation": "Continue collaboration to gather data",
+            }
+
+        # Analyze trust trend - use generator to avoid intermediate list for calculations
+        trust_values = [s.get("trust", 0.5) for s in session_history]
+        trust_trend = self._calculate_trend(trust_values)
+
+        # Analyze success rate trend - extract directly without intermediate list
+        success_count = sum(1 for s in session_history if s.get("success", False))
+        success_rate = success_count / len(session_history) if session_history else 0.5
+
+        # Determine active loop
+        if trust_trend > 0.1 and success_rate > 0.6:
+            # Trust building virtuous cycle active
+            dominant_loop = self._get_loop_by_id("R1_trust_building")
+            return {
+                "dominant_loop": "R1_trust_building",
+                "loop_type": "reinforcing_virtuous",
+                "loop_strength": min(trust_trend * success_rate, 1.0),
+                "trend": "amplifying_positive",
+                "recommendation": "Maintain momentum. Consider increasing delegation.",
+                "details": dominant_loop,
+            }
+
+        if trust_trend < -0.1 and success_rate < 0.4:
+            # Trust erosion vicious cycle active
+            dominant_loop = self._get_loop_by_id("R2_trust_erosion")
+            return {
+                "dominant_loop": "R2_trust_erosion",
+                "loop_type": "reinforcing_vicious",
+                "loop_strength": min(abs(trust_trend) * (1 - success_rate), 1.0),
+                "trend": "amplifying_negative",
+                "recommendation": "INTERVENTION NEEDED: Break cycle. Reduce scope, rebuild confidence.",
+                "details": dominant_loop,
+            }
+
+        # Quality control balancing loop active
+        dominant_loop = self._get_loop_by_id("B1_quality_control")
+        return {
+            "dominant_loop": "B1_quality_control",
+            "loop_type": "balancing",
+            "loop_strength": 0.5,
+            "trend": "stabilizing",
+            "recommendation": "System stable. Monitor for reinforcing loop activation.",
+            "details": dominant_loop,
+        }
+
+    def detect_virtuous_cycle(self, history: list[dict[str, Any]]) -> bool:
+        """Detect reinforcing positive feedback (virtuous cycle)
+
+        A virtuous cycle is present when:
+        1. Trust is increasing
+        2. Success rate is high (>60%)
+        3. Trend is accelerating (not just linear)
+
+        Args:
+            history: Session history with trust and success metrics
+
+        Returns:
+            True if virtuous cycle detected, False otherwise
+
+        Example:
+            >>> history = [
+            ...     {"trust": 0.5, "success": True},
+            ...     {"trust": 0.6, "success": True},
+            ...     {"trust": 0.75, "success": True}  # Accelerating
+            ... ]
+            >>> detector.detect_virtuous_cycle(history)
+            True
+
+        """
+        if len(history) < 3:
+            return False
+
+        trust_values = [h.get("trust", 0.5) for h in history]
+        success_count = sum(1 for h in history if h.get("success", False))
+
+        # Check trust is increasing
+        trust_trend = self._calculate_trend(trust_values)
+        if trust_trend <= 0:
+            return False
+
+        # Check success rate is high - calculate directly without intermediate list
+        success_rate = success_count / len(history) if history else 0.0
+        if success_rate < 0.6:
+            return False
+
+        # Check for acceleration (reinforcing behavior)
+        recent_trust_trend = self._calculate_trend(trust_values[-3:])
+        overall_trust_trend = self._calculate_trend(trust_values)
+
+        is_accelerating = recent_trust_trend > overall_trust_trend
+
+        return is_accelerating
+
+    def detect_vicious_cycle(self, history: list[dict[str, Any]]) -> bool:
+        """Detect reinforcing negative feedback (vicious cycle)
+
+        A vicious cycle is present when:
+        1. Trust is decreasing
+        2. Failure rate is high (>40%)
+        3. Trend is accelerating downward
+
+        Args:
+            history: Session history with trust and success metrics
+
+        Returns:
+            True if vicious cycle detected, False otherwise
+
+        Example:
+            >>> history = [
+            ...     {"trust": 0.7, "success": False},
+            ...     {"trust": 0.5, "success": False},
+            ...     {"trust": 0.3, "success": False}  # Accelerating down
+            ... ]
+            >>> detector.detect_vicious_cycle(history)
+            True
+
+        """
+        if len(history) < 3:
+            return False
+
+        trust_values = [h.get("trust", 0.5) for h in history]
+        failure_count = sum(1 for h in history if not h.get("success", True))
+
+        # Check trust is decreasing
+        trust_trend = self._calculate_trend(trust_values)
+        if trust_trend >= 0:
+            return False
+
+        # Check failure rate is high - calculate directly without intermediate list
+        failure_rate = failure_count / len(history) if history else 0.0
+        if failure_rate < 0.4:
+            return False
+
+        # Check for acceleration (reinforcing behavior)
+        recent_trust_trend = self._calculate_trend(trust_values[-3:])
+        overall_trust_trend = self._calculate_trend(trust_values)
+
+        is_accelerating_down = recent_trust_trend < overall_trust_trend
+
+        return is_accelerating_down
+
+    def get_intervention_recommendations(self, loop_id: str) -> list[str]:
+        """Get recommended interventions for a specific loop
+
+        Args:
+            loop_id: ID of the loop (e.g., "R1_trust_building")
+
+        Returns:
+            List of intervention recommendations
+
+        Example:
+            >>> recommendations = detector.get_intervention_recommendations("R2_trust_erosion")
+            >>> print(recommendations)
+            ['break_cycle', 'rebuild_confidence', 'adjust_scope']
+
+        """
+        loop = self._get_loop_by_id(loop_id)
+        if loop:
+            return loop.intervention_points
+        return []
+
+    def _calculate_trend(self, values: list[float]) -> float:
+        """Calculate trend direction and magnitude
+
+        Uses simple linear regression slope as trend indicator.
+
+        Returns:
+            Positive value: increasing trend
+            Negative value: decreasing trend
+            Near zero: stable
+
+        """
+        if len(values) < 2:
+            return 0.0
+
+        n = len(values)
+        # x_mean is sum(0,1,...,n-1)/n = (n-1)/2
+        x_mean = (n - 1) / 2
+        y_mean = sum(values) / n
+
+        # Use i directly instead of x[i] since x would just be range(n)
+        numerator = sum((i - x_mean) * (values[i] - y_mean) for i in range(n))
+        denominator = sum((i - x_mean) ** 2 for i in range(n))
+
+        if denominator == 0:
+            return 0.0
+
+        slope = numerator / denominator
+        return slope
+
+    def _get_loop_by_id(self, loop_id: str) -> FeedbackLoop | None:
+        """Get a loop by its ID"""
+        for loop in self.detected_loops:
+            if loop.loop_id == loop_id:
+                return loop
+        return None
+
+    def register_custom_loop(self, loop: FeedbackLoop):
+        """Register a custom feedback loop for detection
+
+        Args:
+            loop: FeedbackLoop instance to register
+
+        """
+        self.detected_loops.append(loop)
+
+    def get_all_loops(self) -> list[FeedbackLoop]:
+        """Get all registered feedback loops"""
+        return self.detected_loops
+
+    def reset(self):
+        """Reset detector and reinitialize standard loops"""
+        self.detected_loops = []
+        self._initialize_standard_loops()