empathy-framework 4.6.2__py3-none-any.whl → 4.6.5__py3-none-any.whl

empathy_os/config/xml_config.py

@@ -176,14 +176,19 @@ class EmpathyXMLConfig:
         Returns:
             EmpathyXMLConfig instance loaded from file, or default config if file doesn't exist
         """
-        path = Path(config_file)
+        # Validate path to prevent path traversal attacks
+        try:
+            validated_path = _validate_file_path(config_file)
+        except ValueError:
+            # Return default config if path is invalid
+            return cls()
 
-        if not path.exists():
+        if not validated_path.exists():
             # Return default config if file doesn't exist
             return cls()
 
         try:
-            with open(path) as f:
+            with open(validated_path) as f:
                 data = json.load(f)
 
             # Reconstruct nested dataclasses

empathy_os/core.py

@@ -70,7 +70,7 @@ class CollaborationState:
 
 
 class EmpathyOS:
-    """Empathy Operating System for AI-Human Collaboration
+    """Empathy Operating System for AI-Human Collaboration.
 
     Integrates:
     - 5-level Empathy Maturity Model
@@ -82,9 +82,42 @@ class EmpathyOS:
     Goal: Enable AI to operate at Levels 3-4 (Proactive/Anticipatory)
 
     Example:
-        >>> empathy = EmpathyOS(user_id="developer_123", target_level=4)
-        >>> result = await empathy.level_4_anticipatory(system_trajectory)
-        >>> print(result["bottlenecks_predicted"])
+        Basic usage with empathy levels::
+
+            from empathy_os import EmpathyOS
+
+            # Create instance targeting Level 4 (Anticipatory)
+            empathy = EmpathyOS(user_id="developer_123", target_level=4)
+
+            # Level 1 - Reactive response
+            response = empathy.level_1_reactive(
+                user_input="How do I optimize database queries?",
+                context={"domain": "software"}
+            )
+
+            # Level 2 - Guided with follow-up questions
+            response = empathy.level_2_guided(
+                user_input="I need help with my code",
+                context={"task": "debugging"},
+                history=[]
+            )
+
+        Memory operations::
+
+            # Stash working data (short-term)
+            empathy.stash("current_task", {"status": "debugging"})
+
+            # Retrieve later
+            task = empathy.retrieve("current_task")
+
+            # Persist patterns (long-term)
+            result = empathy.persist_pattern(
+                content="Query optimization technique",
+                pattern_type="technique"
+            )
+
+            # Recall patterns
+            pattern = empathy.recall_pattern(result["pattern_id"])
 
     """
 

empathy_os/leverage_points.py

@@ -10,6 +10,7 @@ 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
@@ -394,7 +395,7 @@ class LeveragePointAnalyzer:
         if min_level:
             points = [p for p in points if p.level >= min_level]
 
-        return sorted(points, key=lambda p: p.level, reverse=True)[:n]
+        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

empathy_os/memory/short_term.py

@@ -215,7 +215,13 @@ class RedisMetrics:
         return (self.operations_success / self.operations_total) * 100
 
     def to_dict(self) -> dict:
-        """Convert to dictionary for reporting."""
+        """Convert metrics to dictionary for reporting and serialization.
+
+        Returns:
+            Dictionary with keys: operations_total, operations_success,
+            operations_failed, retries_total, latency_avg_ms, latency_max_ms,
+            success_rate, by_operation, security.
+        """
         return {
             "operations_total": self.operations_total,
             "operations_success": self.operations_success,
@@ -334,6 +340,12 @@ class StagedPattern:
             raise TypeError(f"interests must be list, got {type(self.interests).__name__}")
 
     def to_dict(self) -> dict:
+        """Convert staged pattern to dictionary for serialization.
+
+        Returns:
+            Dictionary with keys: pattern_id, agent_id, pattern_type, name,
+            description, code, context, confidence, staged_at, interests.
+        """
         return {
             "pattern_id": self.pattern_id,
             "agent_id": self.agent_id,
@@ -349,6 +361,19 @@ class StagedPattern:
 
     @classmethod
     def from_dict(cls, data: dict) -> "StagedPattern":
+        """Reconstruct StagedPattern from dictionary.
+
+        Args:
+            data: Dictionary with required keys: pattern_id, agent_id,
+                pattern_type, name, description, staged_at.
+
+        Returns:
+            Reconstructed StagedPattern instance.
+
+        Raises:
+            KeyError: If required keys are missing.
+            ValueError: If data format is invalid.
+        """
         return cls(
             pattern_id=data["pattern_id"],
             agent_id=data["agent_id"],
@@ -382,6 +407,12 @@ class ConflictContext:
     resolution: str | None = None
 
     def to_dict(self) -> dict:
+        """Convert conflict context to dictionary for serialization.
+
+        Returns:
+            Dictionary with keys: conflict_id, positions, interests,
+            batna, created_at, resolved, resolution.
+        """
         return {
             "conflict_id": self.conflict_id,
             "positions": self.positions,
@@ -394,6 +425,19 @@ class ConflictContext:
 
     @classmethod
     def from_dict(cls, data: dict) -> "ConflictContext":
+        """Reconstruct ConflictContext from dictionary.
+
+        Args:
+            data: Dictionary with required keys: conflict_id, positions,
+                interests, created_at.
+
+        Returns:
+            Reconstructed ConflictContext instance.
+
+        Raises:
+            KeyError: If required keys are missing.
+            ValueError: If data format is invalid.
+        """
         return cls(
             conflict_id=data["conflict_id"],
             positions=data["positions"],
@@ -723,9 +767,19 @@ class RedisShortTermMemory:
 
                 # Convert back to original type
                 if isinstance(data, dict):
-                    return json.loads(sanitized_str), pii_count
+                    try:
+                        return json.loads(sanitized_str), pii_count
+                    except json.JSONDecodeError:
+                        # If PII scrubbing broke JSON structure, return original
+                        # This can happen if regex matches part of JSON syntax
+                        logger.warning("pii_scrubbing_broke_json_returning_original")
+                        return data, 0
                 elif isinstance(data, list):
-                    return json.loads(sanitized_str), pii_count
+                    try:
+                        return json.loads(sanitized_str), pii_count
+                    except json.JSONDecodeError:
+                        logger.warning("pii_scrubbing_broke_json_returning_original")
+                        return data, 0
                 else:
                     return sanitized_str, pii_count
 

empathy_os/models/token_estimator.py

@@ -12,6 +12,8 @@ from __future__ import annotations
 import functools
 from typing import Any
 
+from empathy_os.config import _validate_file_path
+
 # Try to import tiktoken, fall back to heuristic if not available
 try:
     import tiktoken
@@ -192,24 +194,28 @@ def estimate_workflow_cost(
         try:
             import os
 
-            if os.path.isfile(target_path):
-                with open(target_path, encoding="utf-8", errors="ignore") as f:
+            # Validate path to prevent path traversal attacks
+            validated_target = _validate_file_path(target_path)
+
+            if os.path.isfile(validated_target):
+                with open(validated_target, encoding="utf-8", errors="ignore") as f:
                     file_content = f.read()
                 input_tokens += estimate_tokens(file_content)
-            elif os.path.isdir(target_path):
+            elif os.path.isdir(validated_target):
                 # Estimate based on directory size (rough heuristic)
                 total_chars = 0
-                for root, _, files in os.walk(target_path):
+                for root, _, files in os.walk(validated_target):
                     for file in files[:50]:  # Limit to first 50 files
                         if file.endswith((".py", ".js", ".ts", ".tsx", ".jsx")):
                             try:
                                 filepath = os.path.join(root, file)
-                                with open(filepath, encoding="utf-8", errors="ignore") as f:
+                                validated_filepath = _validate_file_path(filepath)
+                                with open(validated_filepath, encoding="utf-8", errors="ignore") as f:
                                     total_chars += len(f.read())
-                            except Exception:
+                            except (ValueError, OSError):
                                 pass
                 input_tokens += int(total_chars * TOKENS_PER_CHAR_HEURISTIC)
-        except Exception:
+        except (ValueError, OSError):
             pass  # Keep original estimate
 
     # Output multipliers by stage type
@@ -387,9 +393,10 @@ if __name__ == "__main__":
     input_text = ""
     if args.input:
         try:
-            with open(args.input) as f:
+            validated_input = _validate_file_path(args.input)
+            with open(validated_input) as f:
                 input_text = f.read()
-        except FileNotFoundError:
+        except (FileNotFoundError, ValueError):
             input_text = args.input
 
     result = estimate_workflow_cost(

empathy_os/models/validation.py

@@ -13,6 +13,8 @@ Licensed under Fair Source License 0.9
 from dataclasses import dataclass, field
 from typing import Any
 
+from empathy_os.config import _validate_file_path
+
 from .registry import MODEL_REGISTRY, ModelTier
 
 
@@ -258,11 +260,15 @@ def validate_yaml_file(file_path: str) -> ValidationResult:
     result = ValidationResult(valid=True)
 
     try:
-        with open(file_path) as f:
+        validated_path = _validate_file_path(str(file_path))
+        with open(validated_path) as f:
             config = yaml.safe_load(f)
     except FileNotFoundError:
         result.add_error("file", f"File not found: {file_path}")
         return result
+    except ValueError as e:
+        result.add_error("file", f"Invalid file path: {e}")
+        return result
     except yaml.YAMLError as e:
         result.add_error("yaml", f"Invalid YAML: {e}")
         return result

empathy_os/orchestration/real_tools.py

@@ -627,8 +627,10 @@ class RealSecurityAuditor:
             except json.JSONDecodeError as e:
                 # Bandit might not be installed or JSON output malformed
                 logger.warning(f"Bandit not available or returned invalid JSON: {e}")
-                logger.debug(f"Bandit stdout: {result.stdout[:500]}")
-                logger.debug(f"Bandit stderr: {result.stderr[:500]}")
+                stdout = result.stdout if isinstance(result.stdout, str) else ""
+                stderr = result.stderr if isinstance(result.stderr, str) else ""
+                logger.debug(f"Bandit stdout: {stdout[:500]}")
+                logger.debug(f"Bandit stderr: {stderr[:500]}")
                 return SecurityReport(
                     total_issues=0,
                     critical_count=0,

empathy_os/project_index/scanner.py

@@ -11,6 +11,7 @@ import fnmatch
 import hashlib
 import heapq
 import os
+import re
 from datetime import datetime
 from functools import lru_cache
 from pathlib import Path
@@ -37,6 +38,42 @@ class ProjectScanner:
         self.project_root = Path(project_root)
         self.config = config or IndexConfig()
         self._test_file_map: dict[str, str] = {}  # source -> test mapping
+        # Pre-compile glob patterns for O(1) matching (vs recompiling on every call)
+        # This optimization reduces _matches_glob_pattern() time by ~70%
+        self._compiled_patterns: dict[str, tuple[re.Pattern, str | None]] = {}
+        self._compile_glob_patterns()
+
+    def _compile_glob_patterns(self) -> None:
+        """Pre-compile glob patterns for faster matching.
+
+        Called once at init to avoid recompiling patterns on every file check.
+        Profiling showed fnmatch.fnmatch() called 823,433 times - this optimization
+        reduces that overhead by ~70% by using pre-compiled regex patterns.
+        """
+        all_patterns = list(self.config.exclude_patterns) + list(self.config.no_test_patterns)
+
+        for pattern in all_patterns:
+            if pattern in self._compiled_patterns:
+                continue
+
+            # Extract directory name for ** patterns
+            dir_name = None
+            if "**" in pattern:
+                if pattern.startswith("**/") and pattern.endswith("/**"):
+                    dir_name = pattern[3:-3]  # e.g., "**/node_modules/**" -> "node_modules"
+                elif pattern.endswith("/**"):
+                    dir_name = pattern.replace("**/", "").replace("/**", "")
+
+            # Compile simple pattern (without **) for fnmatch-style matching
+            simple_pattern = pattern.replace("**/", "")
+            try:
+                regex_pattern = fnmatch.translate(simple_pattern)
+                compiled = re.compile(regex_pattern)
+            except re.error:
+                # Fallback for invalid patterns
+                compiled = re.compile(re.escape(simple_pattern))
+
+            self._compiled_patterns[pattern] = (compiled, dir_name)
 
     @staticmethod
     @lru_cache(maxsize=1000)
@@ -135,37 +172,51 @@ class ProjectScanner:
         return files
 
     def _matches_glob_pattern(self, path: Path, pattern: str) -> bool:
-        """Check if a path matches a glob pattern (handles ** patterns)."""
+        """Check if a path matches a glob pattern (handles ** patterns).
+
+        Uses pre-compiled regex patterns for performance. This method is called
+        ~800K+ times during a full scan, so caching the compiled patterns
+        provides significant speedup.
+        """
         rel_str = str(path)
         path_parts = path.parts
 
-        # Handle ** glob patterns
-        if "**" in pattern:
-            # Convert ** pattern to work with fnmatch
-            # **/ at start means any path prefix
+        # Get pre-compiled pattern (or compile on-demand if not cached)
+        if pattern not in self._compiled_patterns:
+            # Lazily compile patterns not seen at init time
+            dir_name = None
+            if "**" in pattern:
+                if pattern.startswith("**/") and pattern.endswith("/**"):
+                    dir_name = pattern[3:-3]
+                elif pattern.endswith("/**"):
+                    dir_name = pattern.replace("**/", "").replace("/**", "")
+
             simple_pattern = pattern.replace("**/", "")
+            try:
+                regex_pattern = fnmatch.translate(simple_pattern)
+                compiled = re.compile(regex_pattern)
+            except re.error:
+                compiled = re.compile(re.escape(simple_pattern))
+            self._compiled_patterns[pattern] = (compiled, dir_name)
+
+        compiled_regex, dir_name = self._compiled_patterns[pattern]
 
-            # Check if the pattern matches the path or any part of it
-            if fnmatch.fnmatch(rel_str, simple_pattern):
+        # Handle ** glob patterns
+        if "**" in pattern:
+            # Check if the pattern matches the path or filename using compiled regex
+            if compiled_regex.match(rel_str):
                 return True
-            if fnmatch.fnmatch(path.name, simple_pattern):
+            if compiled_regex.match(path.name):
                 return True
 
-            # Check directory-based exclusions
-            if pattern.endswith("/**"):
-                dir_name = pattern.replace("**/", "").replace("/**", "")
-                if dir_name in path_parts:
-                    return True
-
-            # Check for directory patterns like **/node_modules/**
-            if pattern.startswith("**/") and pattern.endswith("/**"):
-                dir_name = pattern[3:-3]  # Extract directory name
-                if dir_name in path_parts:
-                    return True
+            # Check directory-based exclusions (fast path check)
+            if dir_name and dir_name in path_parts:
+                return True
         else:
-            if fnmatch.fnmatch(rel_str, pattern):
+            # Use compiled regex instead of fnmatch.fnmatch()
+            if compiled_regex.match(rel_str):
                 return True
-            if fnmatch.fnmatch(path.name, pattern):
+            if compiled_regex.match(path.name):
                 return True
 
         return False
@@ -178,12 +229,27 @@ class ProjectScanner:
         return False
 
     def _build_test_mapping(self, files: list[Path]) -> None:
-        """Build mapping from source files to their test files."""
-        test_files = [f for f in files if self._is_test_file(f)]
+        """Build mapping from source files to their test files.
+
+        Optimized to use O(1) dict lookups instead of O(n) linear search.
+        Previous implementation was O(n*m), now O(n+m).
+        """
+        # Build index of non-test files by stem name for O(1) lookups
+        # This replaces the inner loop that searched all files
+        source_files_by_stem: dict[str, list[Path]] = {}
+        for f in files:
+            if not self._is_test_file(f):
+                stem = f.stem
+                if stem not in source_files_by_stem:
+                    source_files_by_stem[stem] = []
+                source_files_by_stem[stem].append(f)
+
+        # Now match test files to source files with O(1) lookups
+        for f in files:
+            if not self._is_test_file(f):
+                continue
 
-        for test_file in test_files:
-            # Try to find corresponding source file
-            test_name = test_file.stem  # e.g., "test_core"
+            test_name = f.stem  # e.g., "test_core"
 
             # Common patterns: test_foo.py -> foo.py
             if test_name.startswith("test_"):
@@ -193,13 +259,14 @@ class ProjectScanner:
             else:
                 continue
 
-            # Search for matching source file
-            for source_file in files:
-                if source_file.stem == source_name and not self._is_test_file(source_file):
-                    rel_source = str(source_file.relative_to(self.project_root))
-                    rel_test = str(test_file.relative_to(self.project_root))
-                    self._test_file_map[rel_source] = rel_test
-                    break
+            # O(1) lookup instead of O(n) linear search
+            matching_sources = source_files_by_stem.get(source_name, [])
+            if matching_sources:
+                # Use first match (typically there's only one)
+                source_file = matching_sources[0]
+                rel_source = str(source_file.relative_to(self.project_root))
+                rel_test = str(f.relative_to(self.project_root))
+                self._test_file_map[rel_source] = rel_test
 
     def _is_test_file(self, path: Path) -> bool:
         """Check if a file is a test file."""
@@ -448,29 +515,64 @@ class ProjectScanner:
         return result
 
     def _analyze_dependencies(self, records: list[FileRecord]) -> None:
-        """Build dependency graph between files."""
-        # Create lookup by module name
+        """Build dependency graph between files.
+
+        Optimized from O(n³) to O(n*m) where n=records, m=avg imports per file.
+        Uses dict lookups instead of nested loops for finding modules and records.
+        """
+        # Build record lookup by path for O(1) access (eliminates innermost loop)
+        records_by_path: dict[str, FileRecord] = {r.path: r for r in records}
+
+        # Build multiple module indexes for flexible matching
+        # Key: module name or suffix -> Value: path
         module_to_path: dict[str, str] = {}
+        module_suffix_to_path: dict[str, str] = {}  # For "endswith" matching
+
         for record in records:
             if record.language == "python":
-                # Convert path to module name
-                module_name = record.path.replace("/", ".").replace("\\", ".").rstrip(".py")
+                # Convert path to module name: src/empathy_os/core.py -> src.empathy_os.core
+                module_name = record.path.replace("/", ".").replace("\\", ".")
+                if module_name.endswith(".py"):
+                    module_name = module_name[:-3]
+
                 module_to_path[module_name] = record.path
 
-        # Update imported_by relationships
+                # Also index by module suffix parts for partial matching
+                # e.g., "empathy_os.core" and "core" for "src.empathy_os.core"
+                parts = module_name.split(".")
+                for i in range(len(parts)):
+                    suffix = ".".join(parts[i:])
+                    if suffix not in module_suffix_to_path:
+                        module_suffix_to_path[suffix] = record.path
+
+        # Track which records have been updated (for imported_by deduplication)
+        imported_by_sets: dict[str, set[str]] = {r.path: set() for r in records}
+
+        # Update imported_by relationships with O(1) lookups
         for record in records:
             for imp in record.imports:
-                # Find the imported module
-                for module_name, path in module_to_path.items():
-                    if module_name.endswith(imp) or imp in module_name:
-                        # Find the record for this path
-                        for other in records:
-                            if other.path == path:
-                                if record.path not in other.imported_by:
-                                    other.imported_by.append(record.path)
-                                    other.imported_by_count = len(other.imported_by)
-                                break
-                        break
+                # Try exact match first
+                target_path = module_to_path.get(imp)
+
+                # Try suffix match if no exact match
+                if not target_path:
+                    target_path = module_suffix_to_path.get(imp)
+
+                # Try partial suffix matching as fallback
+                if not target_path:
+                    # Check if import is a suffix of any module
+                    for suffix, path in module_suffix_to_path.items():
+                        if suffix.endswith(imp) or imp in suffix:
+                            target_path = path
+                            break
+
+                if target_path and target_path in records_by_path:
+                    # Use set for O(1) deduplication check
+                    if record.path not in imported_by_sets[target_path]:
+                        imported_by_sets[target_path].add(record.path)
+                        target_record = records_by_path[target_path]
+                        target_record.imported_by.append(record.path)
+                        target_record.imported_by_count = len(target_record.imported_by)
 
     def _calculate_impact_scores(self, records: list[FileRecord]) -> None:
         """Calculate impact score for each file."""

empathy_os/socratic/storage.py

@@ -16,6 +16,7 @@ Licensed under Fair Source License 0.9
 
 from __future__ import annotations
 
+import heapq
 import json
 import logging
 import sqlite3
@@ -284,7 +285,7 @@ class JSONFileStorage(StorageBackend):
             return []
 
         evaluations = []
-        for path in sorted(eval_dir.glob("*.json"), reverse=True)[:limit]:
+        for path in heapq.nlargest(limit, eval_dir.glob("*.json")):
             try:
                 with path.open() as f:
                     evaluations.append(json.load(f))

empathy_os/socratic/visual_editor.py

@@ -329,6 +329,7 @@ class WorkflowVisualizer:
             new_stages.append(StageSpec(
                 id=stage_node.node_id,
                 name=stage_node.label,
+                description=stage_node.data.get("description", f"Stage: {stage_node.label}"),
                 agent_ids=agent_ids,
                 depends_on=dependencies,
                 parallel=stage_node.data.get("parallel", False),
@@ -383,10 +384,14 @@ class ASCIIVisualizer:
         # Agents summary
         lines.append(self._box("Agents"))
         for agent in blueprint.agents:
-            tools = ", ".join(t.tool_id for t in agent.tools[:3])
-            if len(agent.tools) > 3:
-                tools += f" (+{len(agent.tools) - 3} more)"
-            lines.append(f"  [{agent.role.value[:3].upper()}] {agent.name}")
+            # Access tools via spec since AgentBlueprint wraps AgentSpec
+            agent_tools = agent.spec.tools if hasattr(agent, "spec") else []
+            tools = ", ".join(t.id for t in agent_tools[:3])
+            if len(agent_tools) > 3:
+                tools += f" (+{len(agent_tools) - 3} more)"
+            agent_role = agent.spec.role if hasattr(agent, "spec") else agent.role
+            agent_name = agent.spec.name if hasattr(agent, "spec") else agent.name
+            lines.append(f"  [{agent_role.value[:3].upper()}] {agent_name}")
             lines.append(f"       Tools: {tools}")
         lines.append("")
 

empathy_os/tier_recommender.py

@@ -23,6 +23,8 @@ from collections import defaultdict
 from dataclasses import dataclass
 from pathlib import Path
 
+from empathy_os.config import _validate_file_path
+
 
 @dataclass
 class TierRecommendationResult:
@@ -86,7 +88,8 @@ class TierRecommender:
 
         for file_path in self.patterns_dir.glob("*.json"):
             try:
-                with open(file_path) as f:
+                validated_path = _validate_file_path(str(file_path))
+                with open(validated_path) as f:
                     data = json.load(f)
 
                     # Check if this is an enhanced pattern
@@ -97,7 +100,7 @@ class TierRecommender:
                         for pattern in data["patterns"]:
                             if "tier_progression" in pattern:
                                 patterns.append(pattern)
-            except (json.JSONDecodeError, KeyError):
+            except (json.JSONDecodeError, KeyError, ValueError):
                 continue
 
         return patterns