attune-ai 2.0.0__py3-none-any.whl

attune/leverage_points.py

@@ -0,0 +1,441 @@
+"""Leverage Point Analysis for System Interventions
+
+Identifies high-leverage intervention points based on Donella Meadows's
+seminal work "Leverage Points: Places to Intervene in a System".
+
+Leverage points are places within a complex system where a small shift
+can produce big changes in system behavior.
+
+Copyright 2025 Smart AI Memory, LLC
+Licensed under Fair Source 0.9
+"""
+
+import heapq
+from dataclasses import dataclass, field
+from enum import IntEnum
+from typing import Any
+
+
+class LeverageLevel(IntEnum):
+    """Donella Meadows's 12 Leverage Points (ordered by effectiveness)
+
+    Higher numbers = More effective leverage points
+    Lower numbers = Less effective (but often easier to implement)
+    """
+
+    # Low leverage (easy to change, small impact)
+    PARAMETERS = 1  # Constants, numbers (least effective)
+    BUFFERS = 2  # Stabilizing stocks relative to flows
+    STOCK_FLOW = 3  # Physical structure of system
+    DELAYS = 4  # Length of delays relative to change rate
+    BALANCING_LOOPS = 5  # Strength of negative feedback loops
+    REINFORCING_LOOPS = 6  # Strength of positive feedback loops
+
+    # Medium leverage
+    INFORMATION_FLOWS = 7  # Structure of information flows
+    RULES = 8  # Rules of the system (incentives, constraints)
+    SELF_ORGANIZATION = 9  # Power to add/change system structure
+
+    # High leverage (hard to change, huge impact)
+    GOALS = 10  # Goals of the system
+    PARADIGM = 11  # Mindset or paradigm out of which system arises
+    TRANSCEND_PARADIGM = 12  # Power to transcend paradigms (most effective)
+
+
+@dataclass
+class LeveragePoint:
+    """A specific leverage point identified in the system
+
+    Represents a place where intervention can create significant change
+    in system behavior.
+    """
+
+    level: LeverageLevel
+    description: str
+    problem_domain: str
+    impact_potential: float = 0.5  # 0.0-1.0
+    implementation_difficulty: float = 0.5  # 0.0-1.0
+    current_state: str | None = None
+    proposed_intervention: str | None = None
+    expected_outcomes: list[str] = field(default_factory=list)
+    risks: list[str] = field(default_factory=list)
+
+
+class LeveragePointAnalyzer:
+    """Identifies high-leverage intervention points in AI-human systems
+
+    Based on Donella Meadows's 12 leverage points. Helps identify where
+    to intervene in a system for maximum effectiveness.
+
+    **The 12 Leverage Points (in increasing order of effectiveness):**
+
+    1. **Parameters**: Constants, numbers (e.g., change tax rate)
+       - Least effective but easiest to change
+
+    2. **Buffers**: Size of stabilizing stocks
+       - Example: inventory sizes, account balances
+
+    3. **Stock-Flow Structure**: Physical system structure
+       - Example: road networks, factories
+
+    4. **Delays**: Length of delays relative to rate of change
+       - Example: feedback delay in learning systems
+
+    5. **Balancing Feedback Loops**: Strength of stabilizing loops
+       - Example: quality control mechanisms
+
+    6. **Reinforcing Feedback Loops**: Strength of amplifying loops
+       - Example: compound interest, viral growth
+
+    7. **Information Flows**: Structure of information flows
+       - Example: transparency, data access
+
+    8. **Rules**: Incentives, punishments, constraints
+       - Example: laws, policies, protocols
+
+    9. **Self-Organization**: Power to evolve system structure
+       - Example: ability to create new rules
+
+    10. **Goals**: Purpose or function of the system
+        - Example: shift from growth to sustainability
+
+    11. **Paradigm**: Mindset underlying the system
+        - Example: worldview, shared assumptions
+
+    12. **Transcending Paradigms**: Keep perspective on all paradigms
+        - Most effective but hardest to achieve
+
+    Example:
+        >>> analyzer = LeveragePointAnalyzer()
+        >>> problem = {
+        ...     "class": "documentation_burden",
+        ...     "description": "Developers spend 40% time on repetitive docs",
+        ...     "instances": 18
+        ... }
+        >>> points = analyzer.find_leverage_points(problem)
+        >>> for point in points:
+        ...     print(f"{point.level.name}: {point.description}")
+
+    """
+
+    def __init__(self):
+        """Initialize LeveragePointAnalyzer"""
+        self.identified_points: list[LeveragePoint] = []
+
+    def find_leverage_points(self, problem_class: dict[str, Any]) -> list[LeveragePoint]:
+        """Find high-leverage intervention points for a problem class
+
+        Analyzes the problem and identifies leverage points at different
+        levels of the Meadows hierarchy.
+
+        Args:
+            problem_class: Dict with keys:
+                - class: Problem category (e.g., "documentation_burden")
+                - description: Problem description
+                - instances: Number of occurrences (optional)
+                - context: Additional context (optional)
+
+        Returns:
+            List of leverage points, ranked by effectiveness
+
+        Example:
+            >>> problem = {
+            ...     "class": "trust_deficit",
+            ...     "description": "Users don't trust AI recommendations",
+            ...     "instances": 50
+            ... }
+            >>> points = analyzer.find_leverage_points(problem)
+
+        """
+        points: list[LeveragePoint] = []
+        problem_type = problem_class.get("class", "unknown")
+        description = problem_class.get("description", "")
+
+        # Analyze based on problem type
+        if "documentation" in problem_type.lower() or "documentation" in description.lower():
+            points.extend(self._analyze_documentation_problem(problem_class))
+
+        elif "trust" in problem_type.lower() or "trust" in description.lower():
+            points.extend(self._analyze_trust_problem(problem_class))
+
+        elif "efficiency" in problem_type.lower() or "speed" in description.lower():
+            points.extend(self._analyze_efficiency_problem(problem_class))
+
+        else:
+            # Generic analysis for unknown problem types
+            points.extend(self._generic_leverage_analysis(problem_class))
+
+        # Rank by effectiveness (leverage level)
+        points_ranked = self.rank_by_effectiveness(points)
+
+        self.identified_points.extend(points_ranked)
+        return points_ranked
+
+    def rank_by_effectiveness(self, points: list[LeveragePoint]) -> list[LeveragePoint]:
+        """Rank leverage points by Meadows's hierarchy
+
+        Higher leverage levels (paradigms, goals) ranked before lower
+        levels (parameters, buffers).
+
+        Args:
+            points: List of leverage points to rank
+
+        Returns:
+            Sorted list with most effective points first
+
+        """
+        return sorted(points, key=lambda p: p.level, reverse=True)
+
+    def _analyze_documentation_problem(self, problem: dict[str, Any]) -> list[LeveragePoint]:
+        """Analyze leverage points for documentation problems"""
+        points = []
+
+        # High leverage: Change paradigm (how we think about docs)
+        points.append(
+            LeveragePoint(
+                level=LeverageLevel.PARADIGM,
+                description="Paradigm shift: Docs as learning artifact, not compliance burden",
+                problem_domain="documentation",
+                impact_potential=0.9,
+                implementation_difficulty=0.8,
+                proposed_intervention="Reframe docs as 'capturing team learning' not 'creating artifacts'",
+                expected_outcomes=[
+                    "Developers see value in documentation",
+                    "Documentation becomes natural part of workflow",
+                    "Quality improves as purpose clarifies",
+                ],
+            ),
+        )
+
+        # High leverage: Change goal
+        points.append(
+            LeveragePoint(
+                level=LeverageLevel.GOALS,
+                description="Change goal: From 'comprehensive docs' to 'shared understanding'",
+                problem_domain="documentation",
+                impact_potential=0.85,
+                implementation_difficulty=0.6,
+                proposed_intervention="Optimize for team understanding not document completeness",
+                expected_outcomes=[
+                    "Focus on what matters",
+                    "Less redundant documentation",
+                    "More collaboration",
+                ],
+            ),
+        )
+
+        # Medium leverage: Self-organization (Level 5 systems thinking)
+        points.append(
+            LeveragePoint(
+                level=LeverageLevel.SELF_ORGANIZATION,
+                description="Enable self-organization: AI agents auto-generate docs from patterns",
+                problem_domain="documentation",
+                impact_potential=0.8,
+                implementation_difficulty=0.5,
+                proposed_intervention="Deploy Level 5 system that detects patterns and auto-documents",
+                expected_outcomes=[
+                    "Reduce manual documentation by 70%",
+                    "Free developers for creative work",
+                    "Maintain quality through pattern detection",
+                ],
+            ),
+        )
+
+        # Low leverage: Parameters (quickest but least impactful)
+        points.append(
+            LeveragePoint(
+                level=LeverageLevel.PARAMETERS,
+                description="Adjust parameters: Reduce required documentation fields",
+                problem_domain="documentation",
+                impact_potential=0.3,
+                implementation_difficulty=0.1,
+                proposed_intervention="Cut required fields from 20 to 8",
+                expected_outcomes=["Faster documentation", "May not address root cause"],
+            ),
+        )
+
+        return points
+
+    def _analyze_trust_problem(self, problem: dict[str, Any]) -> list[LeveragePoint]:
+        """Analyze leverage points for trust problems"""
+        points = []
+
+        # High leverage: Paradigm shift
+        points.append(
+            LeveragePoint(
+                level=LeverageLevel.PARADIGM,
+                description="Shift paradigm: AI as collaborator, not tool",
+                problem_domain="trust",
+                impact_potential=0.9,
+                implementation_difficulty=0.8,
+                proposed_intervention="Reframe AI relationship from automation to collaboration",
+                expected_outcomes=[
+                    "Users engage differently with AI",
+                    "Set appropriate expectations",
+                    "Build genuine partnership",
+                ],
+            ),
+        )
+
+        # High leverage: Information flows
+        points.append(
+            LeveragePoint(
+                level=LeverageLevel.INFORMATION_FLOWS,
+                description="Increase transparency: Show AI reasoning process",
+                problem_domain="trust",
+                impact_potential=0.75,
+                implementation_difficulty=0.4,
+                proposed_intervention="Implement explainable AI with visible reasoning chains",
+                expected_outcomes=[
+                    "Users understand AI decisions",
+                    "Can verify AI logic",
+                    "Trust through transparency",
+                ],
+            ),
+        )
+
+        # Medium leverage: Reinforcing feedback loops
+        points.append(
+            LeveragePoint(
+                level=LeverageLevel.REINFORCING_LOOPS,
+                description="Activate virtuous cycle: Success → Trust → Delegation → More Success",
+                problem_domain="trust",
+                impact_potential=0.7,
+                implementation_difficulty=0.5,
+                proposed_intervention="Start with high-confidence, low-risk tasks for momentum",
+                expected_outcomes=[
+                    "Quick wins build trust",
+                    "Positive feedback loop activated",
+                    "Natural progression to harder tasks",
+                ],
+            ),
+        )
+
+        return points
+
+    def _analyze_efficiency_problem(self, problem: dict[str, Any]) -> list[LeveragePoint]:
+        """Analyze leverage points for efficiency problems"""
+        points = []
+
+        # High leverage: Goals
+        points.append(
+            LeveragePoint(
+                level=LeverageLevel.GOALS,
+                description="Redefine goal: From 'fast completion' to 'sustainable pace'",
+                problem_domain="efficiency",
+                impact_potential=0.8,
+                implementation_difficulty=0.6,
+                proposed_intervention="Optimize for long-term throughput not short-term speed",
+                expected_outcomes=["Prevent burnout", "Sustainable productivity", "Higher quality"],
+            ),
+        )
+
+        # Medium leverage: Delays
+        points.append(
+            LeveragePoint(
+                level=LeverageLevel.DELAYS,
+                description="Reduce feedback delays: Real-time testing and validation",
+                problem_domain="efficiency",
+                impact_potential=0.65,
+                implementation_difficulty=0.4,
+                proposed_intervention="Implement continuous testing with instant feedback",
+                expected_outcomes=["Faster iteration", "Catch errors early", "Better learning"],
+            ),
+        )
+
+        return points
+
+    def _generic_leverage_analysis(self, problem: dict[str, Any]) -> list[LeveragePoint]:
+        """Generic leverage point analysis for unknown problem types"""
+        points = []
+
+        # Always consider paradigm shift (highest leverage)
+        points.append(
+            LeveragePoint(
+                level=LeverageLevel.PARADIGM,
+                description="Question underlying assumptions about this problem",
+                problem_domain=problem.get("class", "unknown"),
+                impact_potential=0.8,
+                implementation_difficulty=0.8,
+                proposed_intervention="Examine and challenge fundamental beliefs about problem",
+            ),
+        )
+
+        # Consider information flows
+        points.append(
+            LeveragePoint(
+                level=LeverageLevel.INFORMATION_FLOWS,
+                description="Improve information flow and transparency",
+                problem_domain=problem.get("class", "unknown"),
+                impact_potential=0.6,
+                implementation_difficulty=0.4,
+                proposed_intervention="Make relevant information more accessible to stakeholders",
+            ),
+        )
+
+        return points
+
+    def get_top_leverage_points(
+        self,
+        n: int = 3,
+        min_level: LeverageLevel | None = None,
+    ) -> list[LeveragePoint]:
+        """Get top N leverage points, optionally filtered by minimum level
+
+        Args:
+            n: Number of top points to return
+            min_level: Optional minimum leverage level to consider
+
+        Returns:
+            Top N leverage points
+
+        """
+        points = self.identified_points
+
+        if min_level:
+            points = [p for p in points if p.level >= min_level]
+
+        return heapq.nlargest(n, points, key=lambda p: p.level)
+
+    def analyze_intervention_feasibility(self, point: LeveragePoint) -> dict[str, Any]:
+        """Analyze feasibility of intervening at a leverage point
+
+        Considers:
+        - Impact potential
+        - Implementation difficulty
+        - Risk level
+        - Time to results
+
+        Args:
+            point: Leverage point to analyze
+
+        Returns:
+            Feasibility analysis with recommendation
+
+        """
+        # Calculate feasibility score (impact vs difficulty)
+        feasibility_score = point.impact_potential / max(point.implementation_difficulty, 0.1)
+
+        # Determine recommendation
+        if feasibility_score > 1.5:
+            recommendation = "HIGHLY RECOMMENDED: High impact, manageable difficulty"
+        elif feasibility_score > 1.0:
+            recommendation = "RECOMMENDED: Good balance of impact and feasibility"
+        elif feasibility_score > 0.7:
+            recommendation = "CONSIDER: Significant effort but worthwhile impact"
+        else:
+            recommendation = "CAUTION: High difficulty relative to impact"
+
+        return {
+            "leverage_level": point.level.name,
+            "impact_potential": point.impact_potential,
+            "implementation_difficulty": point.implementation_difficulty,
+            "feasibility_score": feasibility_score,
+            "recommendation": recommendation,
+            "risks": point.risks,
+            "expected_outcomes": point.expected_outcomes,
+        }
+
+    def reset(self):
+        """Reset analyzer state"""
+        self.identified_points = []

attune/logging_config.py

@@ -0,0 +1,261 @@
+"""Centralized Logging Configuration for Empathy Framework
+
+Provides professional logging setup with:
+- Console and file logging
+- Structured logging with context
+- Log rotation for production use
+- Configurable log levels
+
+Copyright 2025 Smart AI Memory, LLC
+Licensed under Fair Source 0.9
+"""
+
+import logging
+import logging.handlers
+import os
+import sys
+from pathlib import Path
+
+
+class StructuredFormatter(logging.Formatter):
+    """Custom formatter for structured logging with context."""
+
+    COLORS = {
+        "DEBUG": "\033[36m",  # Cyan
+        "INFO": "\033[32m",  # Green
+        "WARNING": "\033[33m",  # Yellow
+        "ERROR": "\033[31m",  # Red
+        "CRITICAL": "\033[35m",  # Magenta
+    }
+    RESET = "\033[0m"
+    BOLD = "\033[1m"
+
+    def __init__(self, use_color: bool = True, include_context: bool = False):
+        """Initialize formatter.
+
+        Args:
+            use_color: Whether to use colored output
+            include_context: Whether to include contextual information
+
+        """
+        self.use_color = use_color and sys.stderr.isatty()
+        self.include_context = include_context
+        super().__init__()
+
+    def format(self, record: logging.LogRecord) -> str:
+        """Format log record with optional colors and context."""
+        # Get color for this level
+        color = self.COLORS.get(record.levelname, self.RESET) if self.use_color else ""
+        reset = self.RESET if self.use_color else ""
+
+        # Build the main log message
+        timestamp = self.formatTime(record, "%Y-%m-%d %H:%M:%S")
+        level_name = f"{color}{record.levelname}{reset}" if self.use_color else record.levelname
+
+        # Format: [TIMESTAMP] [LEVEL] module.function: message
+        log_msg = (
+            f"[{timestamp}] [{level_name}] {record.name}:{record.funcName}: {record.getMessage()}"
+        )
+
+        # Add context if available
+        if self.include_context and hasattr(record, "context"):
+            context_str = " ".join(f"{k}={v}" for k, v in record.context.items())
+            log_msg += f" [{context_str}]"
+
+        # Add exception info if present
+        if record.exc_info:
+            log_msg += "\n" + self.formatException(record.exc_info)
+
+        return log_msg
+
+
+def create_logger(
+    name: str,
+    level: int = logging.INFO,
+    log_file: str | None = None,
+    log_dir: str | None = None,
+    use_color: bool = True,
+    include_context: bool = False,
+    max_bytes: int = 10 * 1024 * 1024,  # 10MB
+    backup_count: int = 5,
+) -> logging.Logger:
+    """Create a configured logger instance.
+
+    Args:
+        name: Logger name (typically __name__)
+        level: Logging level (DEBUG, INFO, WARNING, ERROR, CRITICAL)
+        log_file: Optional log file path
+        log_dir: Optional log directory for file-based logging
+        use_color: Whether to use colored console output
+        include_context: Whether to include contextual information
+        max_bytes: Max size of log file before rotation
+        backup_count: Number of backup files to keep
+
+    Returns:
+        Configured logger instance
+
+    Example:
+        >>> logger = create_logger(__name__, level=logging.DEBUG)
+        >>> logger.info("Application started")
+        >>> logger.debug("Detailed debug information")
+
+    """
+    logger = logging.getLogger(name)
+
+    # Avoid adding handlers multiple times
+    if logger.handlers:
+        return logger
+
+    logger.setLevel(level)
+
+    # Console handler
+    console_handler = logging.StreamHandler(sys.stderr)
+    console_handler.setLevel(level)
+    console_formatter = StructuredFormatter(use_color=use_color, include_context=include_context)
+    console_handler.setFormatter(console_formatter)
+    logger.addHandler(console_handler)
+
+    # File handler with rotation (if log_file or log_dir specified)
+    if log_file or log_dir:
+        if log_dir:
+            log_dir_path = Path(log_dir)
+            log_dir_path.mkdir(parents=True, exist_ok=True)
+            log_file_path = log_dir_path / f"{name.replace('.', '_')}.log"
+        else:
+            log_file_path = Path(log_file)  # type: ignore[arg-type]
+            log_file_path.parent.mkdir(parents=True, exist_ok=True)
+
+        file_handler = logging.handlers.RotatingFileHandler(
+            str(log_file_path),
+            maxBytes=max_bytes,
+            backupCount=backup_count,
+        )
+        file_handler.setLevel(level)
+        file_formatter = StructuredFormatter(use_color=False, include_context=include_context)
+        file_handler.setFormatter(file_formatter)
+        logger.addHandler(file_handler)
+
+    return logger
+
+
+class LoggingConfig:
+    """Centralized logging configuration manager."""
+
+    _configured = False
+    _loggers: dict[str, logging.Logger] = {}
+    _level: int = logging.INFO
+    _log_dir: str | None = None
+    _use_color: bool = True
+    _include_context: bool = False
+
+    @classmethod
+    def configure(
+        cls,
+        level: int = logging.INFO,
+        log_dir: str | None = None,
+        use_color: bool = True,
+        include_context: bool = False,
+    ) -> None:
+        """Configure global logging settings.
+
+        Args:
+            level: Default logging level
+            log_dir: Directory for log files
+            use_color: Whether to use colored output
+            include_context: Whether to include contextual information
+
+        Example:
+            >>> LoggingConfig.configure(
+            ...     level=logging.DEBUG,
+            ...     log_dir="./logs",
+            ...     use_color=True
+            ... )
+
+        """
+        cls._level = level
+        cls._log_dir = log_dir
+        cls._use_color = use_color
+        cls._include_context = include_context
+        cls._configured = True
+
+    @classmethod
+    def get_logger(
+        cls,
+        name: str,
+        level: int | None = None,
+    ) -> logging.Logger:
+        """Get or create a logger instance.
+
+        Args:
+            name: Logger name (typically __name__)
+            level: Optional override for logging level
+
+        Returns:
+            Configured logger instance
+
+        Example:
+            >>> logger = LoggingConfig.get_logger(__name__)
+            >>> logger.info("Processing data")
+
+        """
+        if name not in cls._loggers:
+            if not cls._configured:
+                cls.configure()
+
+            logger = create_logger(
+                name,
+                level=level or cls._level,
+                log_dir=cls._log_dir,
+                use_color=cls._use_color,
+                include_context=cls._include_context,
+            )
+            cls._loggers[name] = logger
+
+        return cls._loggers[name]
+
+    @classmethod
+    def set_level(cls, level: int) -> None:
+        """Set logging level for all loggers."""
+        for logger in cls._loggers.values():
+            logger.setLevel(level)
+            for handler in logger.handlers:
+                handler.setLevel(level)
+
+
+def get_logger(name: str) -> logging.Logger:
+    """Convenience function to get a logger.
+
+    This is the primary function to use throughout the codebase.
+
+    Args:
+        name: Logger name (typically __name__)
+
+    Returns:
+        Configured logger instance
+
+    Example:
+        >>> from attune.logging_config import get_logger
+        >>> logger = get_logger(__name__)
+        >>> logger.info("Starting process")
+        >>> logger.debug("Processing item", extra={"context": {"item_id": 123}})
+
+    """
+    return LoggingConfig.get_logger(name)
+
+
+# Initialize with environment variable support
+def init_logging_from_env() -> None:
+    """Initialize logging configuration from environment variables."""
+    log_level_str = os.getenv("EMPATHY_LOG_LEVEL", "INFO").upper()
+    log_level = getattr(logging, log_level_str, logging.INFO)
+
+    log_dir = os.getenv("EMPATHY_LOG_DIR")
+    use_color = os.getenv("EMPATHY_LOG_COLOR", "true").lower() == "true"
+    include_context = os.getenv("EMPATHY_LOG_CONTEXT", "false").lower() == "true"
+
+    LoggingConfig.configure(
+        level=log_level,
+        log_dir=log_dir,
+        use_color=use_color,
+        include_context=include_context,
+    )