empathy-framework 4.6.6__py3-none-any.whl → 4.7.1__py3-none-any.whl

empathy_os/orchestration/execution_strategies.py

@@ -257,9 +257,7 @@ class WorkflowReference:
     def __post_init__(self):
         """Validate that exactly one reference type is provided."""
         if bool(self.workflow_id) == bool(self.inline):
-            raise ValueError(
-                "WorkflowReference must have exactly one of: workflow_id or inline"
-            )
+            raise ValueError("WorkflowReference must have exactly one of: workflow_id or inline")
 
 
 @dataclass
@@ -415,8 +413,7 @@ def get_workflow(workflow_id: str) -> WorkflowDefinition:
     """
     if workflow_id not in WORKFLOW_REGISTRY:
         raise ValueError(
-            f"Unknown workflow: {workflow_id}. "
-            f"Available: {list(WORKFLOW_REGISTRY.keys())}"
+            f"Unknown workflow: {workflow_id}. Available: {list(WORKFLOW_REGISTRY.keys())}"
         )
     return WORKFLOW_REGISTRY[workflow_id]
 
@@ -530,9 +527,7 @@ class ConditionEvaluator:
 
         return current
 
-    def _evaluate_natural_language(
-        self, condition_text: str, context: dict[str, Any]
-    ) -> bool:
+    def _evaluate_natural_language(self, condition_text: str, context: dict[str, Any]) -> bool:
         """Evaluate natural language condition using LLM.
 
         Args:
@@ -617,9 +612,7 @@ Respond with ONLY "TRUE" or "FALSE" (no explanation)."""
         result = match_ratio > 0.5
         return not result if is_negated else result
 
-    def _evaluate_composite(
-        self, predicate: dict[str, Any], context: dict[str, Any]
-    ) -> bool:
+    def _evaluate_composite(self, predicate: dict[str, Any], context: dict[str, Any]) -> bool:
         """Evaluate composite condition (AND/OR of other conditions).
 
         Args:
@@ -1159,7 +1152,7 @@ class RefinementStrategy(ExecutionStrategy):
         total_duration = 0.0
 
         for i, agent in enumerate(agents):
-            stage_name = f"stage_{i+1}"
+            stage_name = f"stage_{i + 1}"
             logger.info(f"Refinement {stage_name}: {agent.id}")
 
             result = await self._execute_agent(agent, current_context)
@@ -1171,7 +1164,7 @@ class RefinementStrategy(ExecutionStrategy):
                 current_context[f"{stage_name}_output"] = result.output
                 current_context["previous_output"] = result.output
             else:
-                logger.error(f"Refinement stage {i+1} failed: {result.error}")
+                logger.error(f"Refinement stage {i + 1} failed: {result.error}")
                 break  # Stop refinement on failure
 
         # Final output is from last successful stage
@@ -1303,9 +1296,7 @@ class ConditionalStrategy(ExecutionStrategy):
         self.else_branch = else_branch
         self.evaluator = ConditionEvaluator()
 
-    async def execute(
-        self, agents: list[AgentTemplate], context: dict[str, Any]
-    ) -> StrategyResult:
+    async def execute(self, agents: list[AgentTemplate], context: dict[str, Any]) -> StrategyResult:
         """Execute conditional branching."""
         logger.info(f"Conditional: Evaluating '{self.condition.description or 'condition'}'")
 
@@ -1353,9 +1344,7 @@ class MultiConditionalStrategy(ExecutionStrategy):
         self.default_branch = default_branch
         self.evaluator = ConditionEvaluator()
 
-    async def execute(
-        self, agents: list[AgentTemplate], context: dict[str, Any]
-    ) -> StrategyResult:
+    async def execute(self, agents: list[AgentTemplate], context: dict[str, Any]) -> StrategyResult:
         """Execute multi-conditional branching."""
         for i, (condition, branch) in enumerate(self.conditions):
             if self.evaluator.evaluate(condition, context):
@@ -1427,9 +1416,7 @@ class NestedStrategy(ExecutionStrategy):
         self.workflow_ref = workflow_ref
         self.max_depth = max_depth
 
-    async def execute(
-        self, agents: list[AgentTemplate], context: dict[str, Any]
-    ) -> StrategyResult:
+    async def execute(self, agents: list[AgentTemplate], context: dict[str, Any]) -> StrategyResult:
         """Execute nested workflow.
 
         Args:
@@ -1471,9 +1458,7 @@ class NestedStrategy(ExecutionStrategy):
             logger.error(error_msg)
             raise RecursionError(error_msg)
 
-        logger.info(
-            f"Nested: Entering '{workflow_id}' at depth {nesting.current_depth + 1}"
-        )
+        logger.info(f"Nested: Entering '{workflow_id}' at depth {nesting.current_depth + 1}")
 
         # Create child context with updated nesting
         child_nesting = nesting.enter(workflow_id)
@@ -1529,9 +1514,7 @@ class NestedSequentialStrategy(ExecutionStrategy):
         self.steps = steps
         self.max_depth = max_depth
 
-    async def execute(
-        self, agents: list[AgentTemplate], context: dict[str, Any]
-    ) -> StrategyResult:
+    async def execute(self, agents: list[AgentTemplate], context: dict[str, Any]) -> StrategyResult:
         """Execute steps sequentially, handling both agents and nested workflows."""
         if not self.steps:
             raise ValueError("steps list cannot be empty")
@@ -1640,7 +1623,7 @@ def get_strategy(strategy_name: str) -> ExecutionStrategy:
     """
     if strategy_name not in STRATEGY_REGISTRY:
         raise ValueError(
-            f"Unknown strategy: {strategy_name}. " f"Available: {list(STRATEGY_REGISTRY.keys())}"
+            f"Unknown strategy: {strategy_name}. Available: {list(STRATEGY_REGISTRY.keys())}"
         )
 
     strategy_class = STRATEGY_REGISTRY[strategy_name]

empathy_os/orchestration/pattern_learner.py

@@ -17,6 +17,7 @@ Security:
 import json
 import logging
 from collections import defaultdict
+from collections.abc import Iterator
 from dataclasses import asdict, dataclass, field
 from datetime import datetime
 from pathlib import Path
@@ -121,9 +122,7 @@ class PatternStats:
 
         # Running average for confidence
         n = self.total_executions
-        self.avg_confidence = (
-            (self.avg_confidence * (n - 1) + record.confidence) / n
-        )
+        self.avg_confidence = (self.avg_confidence * (n - 1) + record.confidence) / n
 
     def to_dict(self) -> dict[str, Any]:
         """Convert to dictionary for serialization."""
@@ -289,21 +288,14 @@ class LearningStore:
                 data = json.load(f)
 
             # Load records
-            self._records = [
-                ExecutionRecord.from_dict(r) for r in data.get("records", [])
-            ]
+            self._records = [ExecutionRecord.from_dict(r) for r in data.get("records", [])]
 
             # Load stats
-            self._stats = {
-                s["pattern"]: PatternStats.from_dict(s)
-                for s in data.get("stats", [])
-            }
+            self._stats = {s["pattern"]: PatternStats.from_dict(s) for s in data.get("stats", [])}
 
             # Rebuild context index
             for i, record in enumerate(self._records):
-                sig = ContextSignature(
-                    task_type=record.context_features.get("task_type", "")
-                )
+                sig = ContextSignature(task_type=record.context_features.get("task_type", ""))
                 self._context_index[sig.task_type].append(i)
 
             logger.info(
@@ -376,14 +368,22 @@ class LearningStore:
         """
         return self._stats.get(pattern)
 
+    def iter_all_stats(self) -> Iterator[PatternStats]:
+        """Iterate over all pattern statistics (memory-efficient).
+
+        Yields patterns in arbitrary order. For sorted results,
+        use get_all_stats().
+        """
+        yield from self._stats.values()
+
     def get_all_stats(self) -> list[PatternStats]:
-        """Get all pattern statistics.
+        """Get all pattern statistics sorted by success rate.
 
-        Returns:
-            List of PatternStats sorted by success rate
+        Note: For large pattern sets, prefer iter_all_stats() when
+        you don't need sorted results.
         """
         return sorted(
-            self._stats.values(),
+            self.iter_all_stats(),
             key=lambda s: s.success_rate,
             reverse=True,
         )
@@ -457,9 +457,7 @@ class PatternRecommender:
         """
         self.store = store
 
-    def recommend(
-        self, context: dict[str, Any], top_k: int = 3
-    ) -> list[PatternRecommendation]:
+    def recommend(self, context: dict[str, Any], top_k: int = 3) -> list[PatternRecommendation]:
         """Recommend patterns for a context.
 
         Uses hybrid approach:
@@ -516,9 +514,7 @@ class PatternRecommender:
         recommendations = []
         for pattern, scores in pattern_scores.items():
             if scores["total_similarity"] > 0:
-                weighted_success = (
-                    scores["success_similarity"] / scores["total_similarity"]
-                )
+                weighted_success = scores["success_similarity"] / scores["total_similarity"]
                 stats = self.store.get_stats(pattern)
 
                 recommendations.append(
@@ -626,9 +622,7 @@ class PatternLearner:
         self.store.add_record(record)
         logger.debug(f"Recorded {pattern} execution: success={success}")
 
-    def recommend(
-        self, context: dict[str, Any], top_k: int = 3
-    ) -> list[PatternRecommendation]:
+    def recommend(self, context: dict[str, Any], top_k: int = 3) -> list[PatternRecommendation]:
         """Get pattern recommendations for a context.
 
         Args:

empathy_os/orchestration/real_tools.py

@@ -98,9 +98,7 @@ class RealCoverageAnalyzer:
             file_age = time.time() - coverage_file.stat().st_mtime
             # Use existing file if less than 1 hour old
             if file_age < 3600:
-                logger.info(
-                    f"Using existing coverage data (age: {file_age/60:.1f} minutes)"
-                )
+                logger.info(f"Using existing coverage data (age: {file_age / 60:.1f} minutes)")
             else:
                 logger.info("Existing coverage data is stale, regenerating")
                 use_existing = False
@@ -230,6 +228,7 @@ class RealTestGenerator:
             # Try to load .env file
             try:
                 from dotenv import load_dotenv
+
                 load_dotenv()
             except ImportError:
                 pass  # python-dotenv not required
@@ -254,9 +253,7 @@ class RealTestGenerator:
             logger.warning(f"Failed to initialize LLM: {e}. Falling back to templates")
             self.use_llm = False
 
-    def generate_tests_for_file(
-        self, source_file: str, missing_lines: list[int]
-    ) -> Path:
+    def generate_tests_for_file(self, source_file: str, missing_lines: list[int]) -> Path:
         """Generate tests for uncovered code in a file.
 
         Args:
@@ -294,9 +291,7 @@ class RealTestGenerator:
         if self.use_llm and self._llm:
             test_code = self._generate_llm_tests(source_file, source_code, missing_lines)
         else:
-            test_code = self._generate_basic_test_template(
-                source_file, source_code, missing_lines
-            )
+            test_code = self._generate_basic_test_template(source_file, source_code, missing_lines)
 
         # Write test file
         validated_path = _validate_file_path(str(test_path))
@@ -423,9 +418,7 @@ Return ONLY the Python test code, starting with imports. No markdown, no explana
 
         except Exception as e:
             logger.error(f"LLM test generation failed: {e}, falling back to template")
-            return self._generate_basic_test_template(
-                source_file, source_code, missing_lines
-            )
+            return self._generate_basic_test_template(source_file, source_code, missing_lines)
 
     def _extract_api_docs(self, source_code: str) -> str:
         """Extract API signatures from source code using AST.
@@ -808,9 +801,7 @@ class RealCodeQualityAnalyzer:
             )
 
             # Count error lines
-            error_count = sum(
-                1 for line in result.stdout.split("\n") if ": error:" in line
-            )
+            error_count = sum(1 for line in result.stdout.split("\n") if ": error:" in line)
             return error_count
 
         except FileNotFoundError:

empathy_os/platform_utils.py

@@ -200,7 +200,8 @@ def write_text_file(path: str | Path, content: str, encoding: str = "utf-8") ->
 
     """
     validated_path = _validate_file_path(str(path))
-    return validated_path.write_text(content, encoding=encoding)
+    result: int = validated_path.write_text(content, encoding=encoding)
+    return result
 
 
 def normalize_path(path: str | Path) -> Path:

empathy_os/plugins/__init__.py

@@ -8,7 +8,7 @@ Licensed under Fair Source 0.9
 
 from .base import (
     BasePlugin,
-    BaseWizard,
+    BaseWorkflow,
     PluginError,
     PluginLoadError,
     PluginMetadata,
@@ -18,7 +18,7 @@ from .registry import PluginRegistry, get_global_registry
 
 __all__ = [
     "BasePlugin",
-    "BaseWizard",
+    "BaseWorkflow",
     "PluginError",
     "PluginLoadError",
     "PluginMetadata",

empathy_os/plugins/base.py

@@ -30,25 +30,25 @@ class PluginMetadata:
     dependencies: list[str] | None = None  # Additional package dependencies
 
 
-class BaseWizard(ABC):
-    """Universal base class for all wizards across all domains.
+class BaseWorkflow(ABC):
+    """Universal base class for all workflows across all domains.
 
-    This replaces domain-specific base classes (BaseCoachWizard, etc.)
+    This replaces domain-specific base classes (BaseCoachWorkflow, etc.)
     to provide a unified interface.
 
     Design Philosophy:
     - Domain-agnostic: Works for software, healthcare, finance, etc.
-    - Level-aware: Each wizard declares its empathy level
-    - Pattern-contributing: Wizards share learnings via pattern library
+    - Level-aware: Each workflow declares its empathy level
+    - Pattern-contributing: Workflows share learnings via pattern library
     """
 
     def __init__(self, name: str, domain: str, empathy_level: int, category: str | None = None):
-        """Initialize a wizard
+        """Initialize a workflow
 
         Args:
-            name: Human-readable wizard name
-            domain: Domain this wizard belongs to (e.g., 'software', 'healthcare')
-            empathy_level: Which empathy level this wizard operates at (1-5)
+            name: Human-readable workflow name
+            domain: Domain this workflow belongs to (e.g., 'software', 'healthcare')
+            empathy_level: Which empathy level this workflow operates at (1-5)
             category: Optional category within domain
 
         """
@@ -56,16 +56,16 @@ class BaseWizard(ABC):
         self.domain = domain
         self.empathy_level = empathy_level
         self.category = category
-        self.logger = logging.getLogger(f"wizard.{domain}.{name}")
+        self.logger = logging.getLogger(f"workflow.{domain}.{name}")
 
     @abstractmethod
     async def analyze(self, context: dict[str, Any]) -> dict[str, Any]:
         """Analyze the given context and return results.
 
-        This is the main entry point for all wizards. The context structure
+        This is the main entry point for all workflows. The context structure
         is domain-specific but the return format should follow a standard pattern.
         Subclasses must implement domain-specific analysis logic that aligns with
-        the wizard's empathy level.
+        the workflow's empathy level.
 
         Args:
             context: dict[str, Any]
@@ -83,7 +83,7 @@ class BaseWizard(ABC):
                 - 'recommendations': list[dict] - Actionable next steps
                 - 'patterns': list[str] - Patterns detected for the pattern library
                 - 'confidence': float - Confidence score between 0.0 and 1.0
-                - 'wizard': str - Name of the wizard that performed analysis
+                - 'workflow': str - Name of the workflow that performed analysis
                 - 'empathy_level': int - Empathy level of this analysis (1-5)
                 - 'timestamp': str - ISO format timestamp of analysis
 
@@ -103,9 +103,9 @@ class BaseWizard(ABC):
 
     @abstractmethod
     def get_required_context(self) -> list[str]:
-        """Declare what context fields this wizard needs.
+        """Declare what context fields this workflow needs.
 
-        This method defines the contract between the caller and the wizard.
+        This method defines the contract between the caller and the workflow.
         The caller must provide all declared fields before calling analyze().
         This enables validation via validate_context() and helps with introspection.
 
@@ -116,9 +116,9 @@ class BaseWizard(ABC):
                 passed to analyze().
 
         Examples:
-            Software wizard returns: ['code', 'file_path', 'language']
-            Healthcare wizard returns: ['patient_id', 'vitals', 'medications']
-            Finance wizard returns: ['transactions', 'account_id', 'period']
+            Software workflow returns: ['code', 'file_path', 'language']
+            Healthcare workflow returns: ['patient_id', 'vitals', 'medications']
+            Finance workflow returns: ['transactions', 'account_id', 'period']
 
         Note:
             - Must return at least one field (even if minimal)
@@ -143,12 +143,12 @@ class BaseWizard(ABC):
         missing = [key for key in required if key not in context]
 
         if missing:
-            raise ValueError(f"Wizard '{self.name}' missing required context: {missing}")
+            raise ValueError(f"Workflow '{self.name}' missing required context: {missing}")
 
         return True
 
     def get_empathy_level(self) -> int:
-        """Get the empathy level this wizard operates at"""
+        """Get the empathy level this workflow operates at"""
         return self.empathy_level
 
     def contribute_patterns(self, analysis_result: dict[str, Any]) -> dict[str, Any]:
@@ -165,7 +165,7 @@ class BaseWizard(ABC):
         """
         # Default implementation - override for custom pattern extraction
         return {
-            "wizard": self.name,
+            "workflow": self.name,
             "domain": self.domain,
             "timestamp": datetime.now().isoformat(),
             "patterns": analysis_result.get("patterns", []),
@@ -175,18 +175,18 @@ class BaseWizard(ABC):
 class BasePlugin(ABC):
     """Base class for domain plugins.
 
-    A plugin is a collection of wizards and patterns for a specific domain.
+    A plugin is a collection of workflows and patterns for a specific domain.
 
     Example:
-        - SoftwarePlugin: 16+ coach wizards for code analysis
-        - HealthcarePlugin: Clinical and compliance wizards
-        - FinancePlugin: Fraud detection, compliance wizards
+        - SoftwarePlugin: 16+ coach workflows for code analysis
+        - HealthcarePlugin: Clinical and compliance workflows
+        - FinancePlugin: Fraud detection, compliance workflows
 
     """
 
     def __init__(self):
         self.logger = logging.getLogger(f"plugin.{self.get_metadata().domain}")
-        self._wizards: dict[str, type[BaseWizard]] = {}
+        self._workflows: dict[str, type[BaseWorkflow]] = {}
         self._initialized = False
 
     @abstractmethod
@@ -220,44 +220,44 @@ class BasePlugin(ABC):
         """
 
     @abstractmethod
-    def register_wizards(self) -> dict[str, type[BaseWizard]]:
-        """Register all wizards provided by this plugin.
+    def register_workflows(self) -> dict[str, type[BaseWorkflow]]:
+        """Register all workflows provided by this plugin.
 
-        This method defines all analysis wizards available in this plugin.
-        Wizards are lazy-instantiated by get_wizard() when first requested.
+        This method defines all analysis workflows available in this plugin.
+        Workflows are lazy-instantiated by get_workflow() when first requested.
         This method is called during plugin initialization.
 
         Returns:
-            dict[str, type[BaseWizard]]
-                Dictionary mapping wizard identifiers to Wizard classes (not instances).
+            dict[str, type[BaseWorkflow]]
+                Dictionary mapping workflow identifiers to Workflow classes (not instances).
                 Keys should be lowercase, snake_case identifiers. Values should be
                 uninstantiated class references.
 
         Returns:
-            dict[str, type[BaseWizard]]
+            dict[str, type[BaseWorkflow]]
                 Mapping structure:
                 {
-                    'wizard_id': WizardClass,
-                    'another_wizard': AnotherWizardClass,
+                    'workflow_id': WorkflowClass,
+                    'another_workflow': AnotherWorkflowClass,
                     ...
                 }
 
         Example:
             Software plugin might return:
             {
-                'security': SecurityWizard,
-                'performance': PerformanceWizard,
-                'maintainability': MaintainabilityWizard,
-                'accessibility': AccessibilityWizard,
+                'security': SecurityWorkflow,
+                'performance': PerformanceWorkflow,
+                'maintainability': MaintainabilityWorkflow,
+                'accessibility': AccessibilityWorkflow,
             }
 
         Note:
             - Return only the class, not instances (instantiation is lazy)
-            - Use consistent, descriptive wizard IDs
-            - All returned classes must be subclasses of BaseWizard
-            - Can return empty dict {} if plugin provides no wizards initially
+            - Use consistent, descriptive workflow IDs
+            - All returned classes must be subclasses of BaseWorkflow
+            - Can return empty dict {} if plugin provides no workflows initially
             - Called once during initialization via initialize()
-            - Framework caches results in self._wizards
+            - Framework caches results in self._workflows
 
         """
 
@@ -284,63 +284,63 @@ class BasePlugin(ABC):
 
         self.logger.info(f"Initializing plugin: {self.get_metadata().name}")
 
-        # Register wizards
-        self._wizards = self.register_wizards()
+        # Register workflows
+        self._workflows = self.register_workflows()
 
         self.logger.info(
-            f"Plugin '{self.get_metadata().name}' initialized with {len(self._wizards)} wizards",
+            f"Plugin '{self.get_metadata().name}' initialized with {len(self._workflows)} workflows",
         )
 
         self._initialized = True
 
-    def get_wizard(self, wizard_id: str) -> type[BaseWizard] | None:
-        """Get a wizard by ID.
+    def get_workflow(self, workflow_id: str) -> type[BaseWorkflow] | None:
+        """Get a workflow by ID.
 
         Args:
-            wizard_id: Wizard identifier
+            workflow_id: Workflow identifier
 
         Returns:
-            Wizard class or None if not found
+            Workflow class or None if not found
 
         """
         if not self._initialized:
             self.initialize()
 
-        return self._wizards.get(wizard_id)
+        return self._workflows.get(workflow_id)
 
-    def list_wizards(self) -> list[str]:
-        """List all wizard IDs provided by this plugin.
+    def list_workflows(self) -> list[str]:
+        """List all workflow IDs provided by this plugin.
 
         Returns:
-            List of wizard identifiers
+            List of workflow identifiers
 
         """
         if not self._initialized:
             self.initialize()
 
-        return list(self._wizards.keys())
+        return list(self._workflows.keys())
 
-    def get_wizard_info(self, wizard_id: str) -> dict[str, Any] | None:
-        """Get information about a wizard without instantiating it.
+    def get_workflow_info(self, workflow_id: str) -> dict[str, Any] | None:
+        """Get information about a workflow without instantiating it.
 
         Args:
-            wizard_id: Wizard identifier
+            workflow_id: Workflow identifier
 
         Returns:
-            Dictionary with wizard metadata
+            Dictionary with workflow metadata
 
         """
-        wizard_class = self.get_wizard(wizard_id)
-        if not wizard_class:
+        workflow_class = self.get_workflow(workflow_id)
+        if not workflow_class:
             return None
 
         # Create temporary instance to get metadata
-        # (wizards should be lightweight to construct)
+        # (workflows should be lightweight to construct)
         # Subclasses provide their own defaults for name, domain, empathy_level
-        temp_instance = wizard_class()  # type: ignore[call-arg]
+        temp_instance = workflow_class()  # type: ignore[call-arg]
 
         return {
-            "id": wizard_id,
+            "id": workflow_id,
             "name": temp_instance.name,
             "domain": temp_instance.domain,
             "empathy_level": temp_instance.empathy_level,