empathy-framework 2.4.0__py3-none-any.whl → 3.8.2__py3-none-any.whl

empathy_os/levels.py

@@ -1,5 +1,4 @@
-"""
-Five Levels of AI Empathy - Individual Level Classes
+"""Five Levels of AI Empathy - Individual Level Classes
 
 Provides concrete implementations for each empathy level:
 - Level 1: Reactive Empathy (respond to explicit requests)
@@ -23,8 +22,7 @@ from typing import Any
 
 @dataclass
 class EmpathyAction:
-    """
-    An action taken at a specific empathy level
+    """An action taken at a specific empathy level
 
     Records what action was taken, at what level, and the outcome.
     """
@@ -38,8 +36,7 @@ class EmpathyAction:
 
 
 class EmpathyLevel(ABC):
-    """
-    Abstract base class for empathy levels
+    """Abstract base class for empathy levels
 
     Each level implements specific behaviors appropriate to that
     level of empathy sophistication.
@@ -53,8 +50,7 @@ class EmpathyLevel(ABC):
 
     @abstractmethod
     def respond(self, context: dict[str, Any]) -> dict[str, Any]:
-        """
-        Respond to a situation at this empathy level.
+        """Respond to a situation at this empathy level.
 
         This abstract method defines the core behavior for each empathy level.
         Subclasses must implement level-specific response logic that corresponds
@@ -73,7 +69,7 @@ class EmpathyLevel(ABC):
                 - 'level_name': str - Human-readable level name
                 - 'action': str - Type of action taken
                 - 'description': str - Description of the response
-                - 'initiative': str - Initiative level ('none', 'guided', 'proactive', 'anticipatory', 'systems_thinking')
+                - 'initiative': str - Level ('none'|'guided'|'proactive'|'anticipatory'|'systems')
                 - 'reasoning': str - Explanation of why this level's approach was used
                 - Additional fields specific to the level implementation
 
@@ -90,8 +86,8 @@ class EmpathyLevel(ABC):
 
             Implementations should record actions via self.record_action() and
             maintain consistency in the response format across levels.
+
         """
-        pass
 
     def record_action(
         self,
@@ -116,8 +112,7 @@ class EmpathyLevel(ABC):
 
 
 class Level1Reactive(EmpathyLevel):
-    """
-    Level 1: Reactive Empathy
+    """Level 1: Reactive Empathy
 
     **Principle**: Help after being asked
 
@@ -143,14 +138,14 @@ class Level1Reactive(EmpathyLevel):
         >>> response = level1.respond({"request": "status", "subject": "project"})
         >>> print(response["action"])
         'provide_requested_information'
+
     """
 
     level_number = 1
     level_name = "Reactive Empathy"
 
     def respond(self, context: dict[str, Any]) -> dict[str, Any]:
-        """
-        Respond reactively to explicit request
+        """Respond reactively to explicit request
 
         Only provides what was directly asked for.
         """
@@ -177,8 +172,7 @@ class Level1Reactive(EmpathyLevel):
 
 
 class Level2Guided(EmpathyLevel):
-    """
-    Level 2: Guided Empathy
+    """Level 2: Guided Empathy
 
     **Principle**: Collaborative exploration with user input
 
@@ -208,14 +202,14 @@ class Level2Guided(EmpathyLevel):
         ... })
         >>> print(len(response["clarifying_questions"]))
         3
+
     """
 
     level_number = 2
     level_name = "Guided Empathy"
 
     def respond(self, context: dict[str, Any]) -> dict[str, Any]:
-        """
-        Respond with guided exploration
+        """Respond with guided exploration
 
         Asks questions to understand needs and collaboratively explore solutions.
         """
@@ -266,8 +260,7 @@ class Level2Guided(EmpathyLevel):
 
 
 class Level3Proactive(EmpathyLevel):
-    """
-    Level 3: Proactive Empathy
+    """Level 3: Proactive Empathy
 
     **Principle**: Act before being asked (when confidence is high)
 
@@ -296,14 +289,14 @@ class Level3Proactive(EmpathyLevel):
         ...     "confidence": 0.9
         ... })
         >>> print(response["proactive_offer"])
+
     """
 
     level_number = 3
     level_name = "Proactive Empathy"
 
     def respond(self, context: dict[str, Any]) -> dict[str, Any]:
-        """
-        Respond proactively to observed needs
+        """Respond proactively to observed needs
 
         Takes initiative on obvious needs without being asked.
         """
@@ -351,8 +344,7 @@ class Level3Proactive(EmpathyLevel):
 
 
 class Level4Anticipatory(EmpathyLevel):
-    """
-    Level 4: Anticipatory Empathy
+    """Level 4: Anticipatory Empathy
 
     **Principle**: Predict and prepare for future needs
 
@@ -387,14 +379,14 @@ class Level4Anticipatory(EmpathyLevel):
         ...     "prediction_horizon": "30_days"
         ... })
         >>> print(response["predicted_needs"])
+
     """
 
     level_number = 4
     level_name = "Anticipatory Empathy"
 
     def respond(self, context: dict[str, Any]) -> dict[str, Any]:
-        """
-        Respond anticipatorily to predicted future needs
+        """Respond anticipatorily to predicted future needs
 
         Analyzes trajectory and prepares for future needs before they arise.
         """
@@ -427,7 +419,10 @@ class Level4Anticipatory(EmpathyLevel):
         return response
 
     def _predict_future_needs(
-        self, current_state: dict[str, Any], trajectory: str, horizon: str
+        self,
+        current_state: dict[str, Any],
+        trajectory: str,
+        horizon: str,
     ) -> dict[str, Any]:
         """Predict future needs based on current trajectory"""
         # Simulate prediction logic
@@ -452,8 +447,7 @@ class Level4Anticipatory(EmpathyLevel):
 
 
 class Level5Systems(EmpathyLevel):
-    """
-    Level 5: Systems Empathy
+    """Level 5: Systems Empathy
 
     **Principle**: Build structures that help at scale
 
@@ -489,20 +483,20 @@ class Level5Systems(EmpathyLevel):
         ...     "pattern": "repetitive_structure"
         ... })
         >>> print(response["system_created"])
+
     """
 
     level_number = 5
     level_name = "Systems Empathy"
 
     def respond(self, context: dict[str, Any]) -> dict[str, Any]:
-        """
-        Respond with systems-level solution
+        """Respond with systems-level solution
 
         Creates reusable structures that help at scale.
         """
         problem_class = context.get("problem_class", "unknown")
         instances = context.get("instances", 0)
-        pattern = context.get("pattern", None)
+        pattern = context.get("pattern")
 
         system_design = self._design_system_solution(problem_class, instances, pattern)
 
@@ -530,7 +524,10 @@ class Level5Systems(EmpathyLevel):
         return response
 
     def _design_system_solution(
-        self, problem_class: str, instances: int, pattern: str | None
+        self,
+        problem_class: str,
+        instances: int,
+        pattern: str | None,
     ) -> dict[str, Any]:
         """Design a system-level solution"""
         return {
@@ -555,8 +552,7 @@ class Level5Systems(EmpathyLevel):
 
 # Convenience function to get level class by number
 def get_level_class(level: int) -> type:
-    """
-    Get the class for a specific empathy level
+    """Get the class for a specific empathy level
 
     Args:
         level: Level number (1-5)
@@ -569,6 +565,7 @@ def get_level_class(level: int) -> type:
         >>> level4 = LevelClass()
         >>> print(level4.level_name)
         'Anticipatory Empathy'
+
     """
     levels = {
         1: Level1Reactive,

empathy_os/leverage_points.py

@@ -1,5 +1,4 @@
-"""
-Leverage Point Analysis for System Interventions
+"""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".
@@ -17,8 +16,7 @@ from typing import Any
 
 
 class LeverageLevel(IntEnum):
-    """
-    Donella Meadows's 12 Leverage Points (ordered by effectiveness)
+    """Donella Meadows's 12 Leverage Points (ordered by effectiveness)
 
     Higher numbers = More effective leverage points
     Lower numbers = Less effective (but often easier to implement)
@@ -45,8 +43,7 @@ class LeverageLevel(IntEnum):
 
 @dataclass
 class LeveragePoint:
-    """
-    A specific leverage point identified in the system
+    """A specific leverage point identified in the system
 
     Represents a place where intervention can create significant change
     in system behavior.
@@ -64,8 +61,7 @@ class LeveragePoint:
 
 
 class LeveragePointAnalyzer:
-    """
-    Identifies high-leverage intervention points in AI-human systems
+    """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.
@@ -118,6 +114,7 @@ class LeveragePointAnalyzer:
         >>> points = analyzer.find_leverage_points(problem)
         >>> for point in points:
         ...     print(f"{point.level.name}: {point.description}")
+
     """
 
     def __init__(self):
@@ -125,8 +122,7 @@ class 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
+        """Find high-leverage intervention points for a problem class
 
         Analyzes the problem and identifies leverage points at different
         levels of the Meadows hierarchy.
@@ -148,6 +144,7 @@ class LeveragePointAnalyzer:
             ...     "instances": 50
             ... }
             >>> points = analyzer.find_leverage_points(problem)
+
         """
         points: list[LeveragePoint] = []
         problem_type = problem_class.get("class", "unknown")
@@ -174,8 +171,7 @@ class LeveragePointAnalyzer:
         return points_ranked
 
     def rank_by_effectiveness(self, points: list[LeveragePoint]) -> list[LeveragePoint]:
-        """
-        Rank leverage points by Meadows's hierarchy
+        """Rank leverage points by Meadows's hierarchy
 
         Higher leverage levels (paradigms, goals) ranked before lower
         levels (parameters, buffers).
@@ -185,6 +181,7 @@ class LeveragePointAnalyzer:
 
         Returns:
             Sorted list with most effective points first
+
         """
         return sorted(points, key=lambda p: p.level, reverse=True)
 
@@ -196,17 +193,17 @@ class LeveragePointAnalyzer:
         points.append(
             LeveragePoint(
                 level=LeverageLevel.PARADIGM,
-                description="Shift paradigm: Documentation as learning artifact, not compliance burden",
+                description="Paradigm shift: Docs as learning artifact, not compliance burden",
                 problem_domain="documentation",
                 impact_potential=0.9,
                 implementation_difficulty=0.8,
-                proposed_intervention="Reframe documentation as 'capturing team learning' not 'creating artifacts'",
+                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
@@ -223,7 +220,7 @@ class LeveragePointAnalyzer:
                     "Less redundant documentation",
                     "More collaboration",
                 ],
-            )
+            ),
         )
 
         # Medium leverage: Self-organization (Level 5 systems thinking)
@@ -234,13 +231,13 @@ class LeveragePointAnalyzer:
                 problem_domain="documentation",
                 impact_potential=0.8,
                 implementation_difficulty=0.5,
-                proposed_intervention="Deploy Level 5 anticipatory system that detects patterns and auto-documents",
+                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)
@@ -253,7 +250,7 @@ class LeveragePointAnalyzer:
                 implementation_difficulty=0.1,
                 proposed_intervention="Cut required fields from 20 to 8",
                 expected_outcomes=["Faster documentation", "May not address root cause"],
-            )
+            ),
         )
 
         return points
@@ -276,7 +273,7 @@ class LeveragePointAnalyzer:
                     "Set appropriate expectations",
                     "Build genuine partnership",
                 ],
-            )
+            ),
         )
 
         # High leverage: Information flows
@@ -293,7 +290,7 @@ class LeveragePointAnalyzer:
                     "Can verify AI logic",
                     "Trust through transparency",
                 ],
-            )
+            ),
         )
 
         # Medium leverage: Reinforcing feedback loops
@@ -304,13 +301,13 @@ class LeveragePointAnalyzer:
                 problem_domain="trust",
                 impact_potential=0.7,
                 implementation_difficulty=0.5,
-                proposed_intervention="Start with high-confidence, low-risk tasks to build momentum",
+                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
@@ -329,7 +326,7 @@ class LeveragePointAnalyzer:
                 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
@@ -342,7 +339,7 @@ class LeveragePointAnalyzer:
                 implementation_difficulty=0.4,
                 proposed_intervention="Implement continuous testing with instant feedback",
                 expected_outcomes=["Faster iteration", "Catch errors early", "Better learning"],
-            )
+            ),
         )
 
         return points
@@ -360,7 +357,7 @@ class LeveragePointAnalyzer:
                 impact_potential=0.8,
                 implementation_difficulty=0.8,
                 proposed_intervention="Examine and challenge fundamental beliefs about problem",
-            )
+            ),
         )
 
         # Consider information flows
@@ -372,16 +369,17 @@ class LeveragePointAnalyzer:
                 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
+        self,
+        n: int = 3,
+        min_level: LeverageLevel | None = None,
     ) -> list[LeveragePoint]:
-        """
-        Get top N leverage points, optionally filtered by minimum level
+        """Get top N leverage points, optionally filtered by minimum level
 
         Args:
             n: Number of top points to return
@@ -389,6 +387,7 @@ class LeveragePointAnalyzer:
 
         Returns:
             Top N leverage points
+
         """
         points = self.identified_points
 
@@ -398,8 +397,7 @@ class LeveragePointAnalyzer:
         return sorted(points, key=lambda p: p.level, reverse=True)[:n]
 
     def analyze_intervention_feasibility(self, point: LeveragePoint) -> dict[str, Any]:
-        """
-        Analyze feasibility of intervening at a leverage point
+        """Analyze feasibility of intervening at a leverage point
 
         Considers:
         - Impact potential
@@ -412,6 +410,7 @@ class LeveragePointAnalyzer:
 
         Returns:
             Feasibility analysis with recommendation
+
         """
         # Calculate feasibility score (impact vs difficulty)
         feasibility_score = point.impact_potential / max(point.implementation_difficulty, 0.1)

empathy_os/logging_config.py

@@ -1,5 +1,4 @@
-"""
-Centralized Logging Configuration for Empathy Framework
+"""Centralized Logging Configuration for Empathy Framework
 
 Provides professional logging setup with:
 - Console and file logging
@@ -32,12 +31,12 @@ class StructuredFormatter(logging.Formatter):
     BOLD = "\033[1m"
 
     def __init__(self, use_color: bool = True, include_context: bool = False):
-        """
-        Initialize formatter.
+        """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
@@ -80,8 +79,7 @@ def create_logger(
     max_bytes: int = 10 * 1024 * 1024,  # 10MB
     backup_count: int = 5,
 ) -> logging.Logger:
-    """
-    Create a configured logger instance.
+    """Create a configured logger instance.
 
     Args:
         name: Logger name (typically __name__)
@@ -100,6 +98,7 @@ def create_logger(
         >>> logger = create_logger(__name__, level=logging.DEBUG)
         >>> logger.info("Application started")
         >>> logger.debug("Detailed debug information")
+
     """
     logger = logging.getLogger(name)
 
@@ -121,13 +120,13 @@ def create_logger(
         if log_dir:
             log_dir_path = Path(log_dir)
             log_dir_path.mkdir(parents=True, exist_ok=True)
-            log_file = log_dir_path / f"{name.replace('.', '_')}.log"
+            log_file_path = log_dir_path / f"{name.replace('.', '_')}.log"
         else:
-            log_file = Path(log_file)
-            log_file.parent.mkdir(parents=True, exist_ok=True)
+            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),
+            str(log_file_path),
             maxBytes=max_bytes,
             backupCount=backup_count,
         )
@@ -144,6 +143,10 @@ class LoggingConfig:
 
     _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(
@@ -153,8 +156,7 @@ class LoggingConfig:
         use_color: bool = True,
         include_context: bool = False,
     ) -> None:
-        """
-        Configure global logging settings.
+        """Configure global logging settings.
 
         Args:
             level: Default logging level
@@ -168,6 +170,7 @@ class LoggingConfig:
             ...     log_dir="./logs",
             ...     use_color=True
             ... )
+
         """
         cls._level = level
         cls._log_dir = log_dir
@@ -181,8 +184,7 @@ class LoggingConfig:
         name: str,
         level: int | None = None,
     ) -> logging.Logger:
-        """
-        Get or create a logger instance.
+        """Get or create a logger instance.
 
         Args:
             name: Logger name (typically __name__)
@@ -194,6 +196,7 @@ class LoggingConfig:
         Example:
             >>> logger = LoggingConfig.get_logger(__name__)
             >>> logger.info("Processing data")
+
         """
         if name not in cls._loggers:
             if not cls._configured:
@@ -220,8 +223,7 @@ class LoggingConfig:
 
 
 def get_logger(name: str) -> logging.Logger:
-    """
-    Convenience function to get a logger.
+    """Convenience function to get a logger.
 
     This is the primary function to use throughout the codebase.
 
@@ -236,6 +238,7 @@ def get_logger(name: str) -> logging.Logger:
         >>> logger = get_logger(__name__)
         >>> logger.info("Starting process")
         >>> logger.debug("Processing item", extra={"context": {"item_id": 123}})
+
     """
     return LoggingConfig.get_logger(name)