empathy-framework 3.8.3__py3-none-any.whl → 3.9.0__py3-none-any.whl

empathy_os/pattern_library.py

@@ -126,6 +126,9 @@ class PatternLibrary:
             agent_id: ID of contributing agent
             pattern: Pattern to contribute
 
+        Raises:
+            ValueError: If agent_id is empty or pattern.id already exists
+
         Example:
             >>> pattern = Pattern(
             ...     id="pat_002",
@@ -138,6 +141,16 @@ class PatternLibrary:
             >>> library.contribute_pattern("agent_1", pattern)
 
         """
+        # Validate inputs
+        if not agent_id or not agent_id.strip():
+            raise ValueError("agent_id cannot be empty")
+
+        if pattern.id in self.patterns:
+            raise ValueError(
+                f"Pattern '{pattern.id}' already exists. "
+                f"Use a different ID or remove the existing pattern first."
+            )
+
         # Store pattern
         self.patterns[pattern.id] = pattern
 
@@ -170,6 +183,10 @@ class PatternLibrary:
         Returns:
             List of PatternMatch objects, sorted by relevance
 
+        Raises:
+            ValueError: If agent_id is empty, min_confidence out of range, or limit < 1
+            TypeError: If context is not a dictionary
+
         Example:
             >>> context = {
             ...     "user_role": "developer",
@@ -179,6 +196,19 @@ class PatternLibrary:
             >>> matches = library.query_patterns("debug_agent", context, min_confidence=0.7)
 
         """
+        # Validate inputs
+        if not agent_id or not agent_id.strip():
+            raise ValueError("agent_id cannot be empty")
+
+        if not isinstance(context, dict):
+            raise TypeError(f"context must be dict, got {type(context).__name__}")
+
+        if not 0.0 <= min_confidence <= 1.0:
+            raise ValueError(f"min_confidence must be 0-1, got {min_confidence}")
+
+        if limit < 1:
+            raise ValueError(f"limit must be positive, got {limit}")
+
         matches: list[PatternMatch] = []
 
         for pattern in self.patterns.values():
@@ -226,10 +256,16 @@ class PatternLibrary:
             pattern_id: ID of pattern that was used
             success: Whether using the pattern was successful
 
+        Raises:
+            ValueError: If pattern_id does not exist
+
         """
         pattern = self.patterns.get(pattern_id)
-        if pattern:
-            pattern.record_usage(success)
+        if not pattern:
+            raise ValueError(
+                f"Pattern '{pattern_id}' not found. Cannot record outcome."
+            )
+        pattern.record_usage(success)
 
     def link_patterns(self, pattern_id_1: str, pattern_id_2: str):
         """Create a link between related patterns
@@ -240,7 +276,21 @@ class PatternLibrary:
             pattern_id_1: First pattern ID
             pattern_id_2: Second pattern ID
 
+        Raises:
+            ValueError: If either pattern ID doesn't exist or IDs are the same
+
         """
+        # Validate patterns exist
+        if pattern_id_1 not in self.patterns:
+            raise ValueError(f"Pattern '{pattern_id_1}' does not exist")
+
+        if pattern_id_2 not in self.patterns:
+            raise ValueError(f"Pattern '{pattern_id_2}' does not exist")
+
+        if pattern_id_1 == pattern_id_2:
+            raise ValueError("Cannot link a pattern to itself")
+
+        # Create bidirectional link
         if pattern_id_1 in self.pattern_graph:
             if pattern_id_2 not in self.pattern_graph[pattern_id_1]:
                 self.pattern_graph[pattern_id_1].append(pattern_id_2)
@@ -249,27 +299,39 @@ class PatternLibrary:
             if pattern_id_1 not in self.pattern_graph[pattern_id_2]:
                 self.pattern_graph[pattern_id_2].append(pattern_id_1)
 
-    def get_related_patterns(self, pattern_id: str, depth: int = 1) -> list[Pattern]:
+    def get_related_patterns(
+        self,
+        pattern_id: str,
+        depth: int = 1,
+        _visited: set[str] | None = None
+    ) -> list[Pattern]:
         """Get patterns related to a given pattern
 
         Args:
             pattern_id: Source pattern ID
             depth: How many hops to traverse (1 = immediate neighbors)
+            _visited: Internal tracking to prevent cycles (do not use directly)
 
         Returns:
-            List of related patterns
+            List of related patterns (no duplicates, cycle-safe)
 
         """
+        # Initialize visited set on first call
+        if _visited is None:
+            _visited = {pattern_id}
+
         if depth <= 0 or pattern_id not in self.pattern_graph:
             return []
 
         related_ids = set(self.pattern_graph[pattern_id])
 
         if depth > 1:
-            # Traverse deeper
+            # Traverse deeper (avoiding cycles)
             for related_id in list(related_ids):
-                deeper = self.get_related_patterns(related_id, depth - 1)
-                related_ids.update(p.id for p in deeper)
+                if related_id not in _visited:
+                    _visited.add(related_id)
+                    deeper = self.get_related_patterns(related_id, depth - 1, _visited)
+                    related_ids.update(p.id for p in deeper)
 
         # Remove source pattern
         related_ids.discard(pattern_id)
@@ -355,8 +417,19 @@ class PatternLibrary:
     ) -> tuple[float, list[str]]:
         """Calculate how relevant a pattern is to current context
 
+        Args:
+            pattern: Pattern to evaluate
+            context: Current context to match against
+
         Returns:
-            (relevance_score, matching_factors)
+            tuple: (relevance_score, matching_factors)
+                - relevance_score (float): 0.0-1.0 relevance score
+                - matching_factors (list[str]): Human-readable reasons for match
+
+        Algorithm:
+            - 50% weight: Context key/value matches
+            - 30% weight: Tag matches
+            - 20% weight: Pattern success rate boost
 
         """
         relevance = 0.0

empathy_os/patterns/debugging/all_patterns.json

@@ -0,0 +1,81 @@
+{
+  "patterns": [
+    {
+      "pattern_id": "workflow_20260107_1770825e",
+      "bug_type": "refactoring",
+      "status": "resolved",
+      "root_cause": "Workflow: refactor-plan - Prioritize tech debt based on trajectory and impact",
+      "fix": "Completed via refactor-plan workflow",
+      "resolved_by": "@empathy_framework",
+      "resolved_at": "2026-01-07",
+      "files_affected": [],
+      "source": "workflow_tracking",
+      "tier_progression": {
+        "methodology": "AI-ADDIE",
+        "recommended_tier": "CHEAP",
+        "starting_tier": "PREMIUM",
+        "successful_tier": "PREMIUM",
+        "total_attempts": 3,
+        "tier_history": [
+          {
+            "tier": "CHEAP",
+            "attempts": 1,
+            "success": {
+              "attempt": 1,
+              "quality_gates_passed": [
+                "execution",
+                "output"
+              ]
+            }
+          },
+          {
+            "tier": "CAPABLE",
+            "attempts": 2,
+            "success": {
+              "attempt": 2,
+              "quality_gates_passed": [
+                "execution",
+                "output"
+              ]
+            }
+          },
+          {
+            "tier": "PREMIUM",
+            "attempts": 1,
+            "success": {
+              "attempt": 1,
+              "quality_gates_passed": [
+                "execution",
+                "output"
+              ]
+            }
+          }
+        ],
+        "cost_breakdown": {
+          "total_cost": 0.021,
+          "cost_if_always_premium": 0.104,
+          "savings_percent": 80.0
+        },
+        "quality_metrics": {
+          "tests_passed": true,
+          "health_score_before": 73,
+          "health_score_after": 73
+        },
+        "xml_protocol_compliance": {
+          "prompt_used_xml": true,
+          "response_used_xml": true,
+          "all_sections_present": true,
+          "test_evidence_provided": true,
+          "false_complete_avoided": true
+        }
+      },
+      "workflow_metadata": {
+        "workflow_name": "refactor-plan",
+        "workflow_id": "1770825e-b645-4c66-b4e1-87b9463b0082",
+        "duration_seconds": 3.24,
+        "started_at": "2026-01-07T06:30:40.696987",
+        "completed_at": "2026-01-07T06:30:43.935316"
+      }
+    }
+  ]
+}

empathy_os/patterns/debugging/workflow_20260107_1770825e.json

@@ -0,0 +1,77 @@
+{
+  "pattern_id": "workflow_20260107_1770825e",
+  "bug_type": "refactoring",
+  "status": "resolved",
+  "root_cause": "Workflow: refactor-plan - Prioritize tech debt based on trajectory and impact",
+  "fix": "Completed via refactor-plan workflow",
+  "resolved_by": "@empathy_framework",
+  "resolved_at": "2026-01-07",
+  "files_affected": [],
+  "source": "workflow_tracking",
+  "tier_progression": {
+    "methodology": "AI-ADDIE",
+    "recommended_tier": "CHEAP",
+    "starting_tier": "PREMIUM",
+    "successful_tier": "PREMIUM",
+    "total_attempts": 3,
+    "tier_history": [
+      {
+        "tier": "CHEAP",
+        "attempts": 1,
+        "success": {
+          "attempt": 1,
+          "quality_gates_passed": [
+            "execution",
+            "output"
+          ]
+        }
+      },
+      {
+        "tier": "CAPABLE",
+        "attempts": 2,
+        "success": {
+          "attempt": 2,
+          "quality_gates_passed": [
+            "execution",
+            "output"
+          ]
+        }
+      },
+      {
+        "tier": "PREMIUM",
+        "attempts": 1,
+        "success": {
+          "attempt": 1,
+          "quality_gates_passed": [
+            "execution",
+            "output"
+          ]
+        }
+      }
+    ],
+    "cost_breakdown": {
+      "total_cost": 0.021,
+      "cost_if_always_premium": 0.104,
+      "savings_percent": 80.0
+    },
+    "quality_metrics": {
+      "tests_passed": true,
+      "health_score_before": 73,
+      "health_score_after": 73
+    },
+    "xml_protocol_compliance": {
+      "prompt_used_xml": true,
+      "response_used_xml": true,
+      "all_sections_present": true,
+      "test_evidence_provided": true,
+      "false_complete_avoided": true
+    }
+  },
+  "workflow_metadata": {
+    "workflow_name": "refactor-plan",
+    "workflow_id": "1770825e-b645-4c66-b4e1-87b9463b0082",
+    "duration_seconds": 3.24,
+    "started_at": "2026-01-07T06:30:40.696987",
+    "completed_at": "2026-01-07T06:30:43.935316"
+  }
+}

empathy_os/patterns/refactoring_memory.json

@@ -0,0 +1,89 @@
+{
+  "version": "1.0",
+  "updated_at": "2026-01-07T06:30:43.930352",
+  "node_count": 5,
+  "edge_count": 0,
+  "nodes": [
+    {
+      "id": "refactoring_analysis_20260107063043_663dbce03854",
+      "type": "pattern",
+      "name": "refactor:workflows/bug_predict.py",
+      "description": "Found 1 refactoring opportunities:\n  - 1 medium impact\n\nTop categories:\n  - other: 1",
+      "source_wizard": "refactoring_crew",
+      "source_file": "",
+      "source_line": null,
+      "severity": "",
+      "confidence": 1.0,
+      "metadata": {},
+      "tags": [],
+      "created_at": "2026-01-07T06:30:43.460922",
+      "updated_at": "2026-01-07T06:30:43.460924",
+      "status": "open"
+    },
+    {
+      "id": "refactoring_analysis_20260107063043_fc92406de1d5",
+      "type": "pattern",
+      "name": "refactor:monitoring/alerts_cli.py",
+      "description": "Found 1 refactoring opportunities:\n  - 1 medium impact\n\nTop categories:\n  - other: 1",
+      "source_wizard": "refactoring_crew",
+      "source_file": "",
+      "source_line": null,
+      "severity": "",
+      "confidence": 1.0,
+      "metadata": {},
+      "tags": [],
+      "created_at": "2026-01-07T06:30:43.593291",
+      "updated_at": "2026-01-07T06:30:43.593291",
+      "status": "open"
+    },
+    {
+      "id": "refactoring_analysis_20260107063043_5cce2d4230a4",
+      "type": "pattern",
+      "name": "refactor:memory/edges.py",
+      "description": "Found 1 refactoring opportunities:\n  - 1 medium impact\n\nTop categories:\n  - other: 1",
+      "source_wizard": "refactoring_crew",
+      "source_file": "",
+      "source_line": null,
+      "severity": "",
+      "confidence": 1.0,
+      "metadata": {},
+      "tags": [],
+      "created_at": "2026-01-07T06:30:43.682805",
+      "updated_at": "2026-01-07T06:30:43.682806",
+      "status": "open"
+    },
+    {
+      "id": "refactoring_analysis_20260107063043_0ef136ce11fb",
+      "type": "pattern",
+      "name": "refactor:workflows/refactor_plan.py",
+      "description": "Found 1 refactoring opportunities:\n  - 1 medium impact\n\nTop categories:\n  - other: 1",
+      "source_wizard": "refactoring_crew",
+      "source_file": "",
+      "source_line": null,
+      "severity": "",
+      "confidence": 1.0,
+      "metadata": {},
+      "tags": [],
+      "created_at": "2026-01-07T06:30:43.796584",
+      "updated_at": "2026-01-07T06:30:43.796586",
+      "status": "open"
+    },
+    {
+      "id": "refactoring_analysis_20260107063043_3c6673a7bb17",
+      "type": "pattern",
+      "name": "refactor:workflows/new_sample_workflow1.py",
+      "description": "Found 1 refactoring opportunities:\n  - 1 medium impact\n\nTop categories:\n  - other: 1",
+      "source_wizard": "refactoring_crew",
+      "source_file": "",
+      "source_line": null,
+      "severity": "",
+      "confidence": 1.0,
+      "metadata": {},
+      "tags": [],
+      "created_at": "2026-01-07T06:30:43.930183",
+      "updated_at": "2026-01-07T06:30:43.930183",
+      "status": "open"
+    }
+  ],
+  "edges": []
+}

empathy_os/telemetry/__init__.py

@@ -0,0 +1,11 @@
+"""Telemetry tracking for Empathy Framework.
+
+Privacy-first, local-only usage tracking to measure actual cost savings.
+
+Copyright 2025 Smart-AI-Memory
+Licensed under Fair Source License 0.9
+"""
+
+from .usage_tracker import UsageTracker
+
+__all__ = ["UsageTracker"]