empathy-framework 3.7.1__py3-none-any.whl → 3.8.0__py3-none-any.whl

empathy_os/memory/long_term.py

@@ -28,6 +28,7 @@ Licensed under Fair Source 0.9
 """
 
 import base64
+import binascii
 import concurrent.futures
 import hashlib
 import json
@@ -168,7 +169,7 @@ class EncryptionManager:
         if env_key := os.getenv("EMPATHY_MASTER_KEY"):
             try:
                 return base64.b64decode(env_key)
-            except Exception as e:
+            except (binascii.Error, ValueError) as e:
                 logger.error("invalid_master_key_in_env", error=str(e))
                 raise ValueError("Invalid EMPATHY_MASTER_KEY format") from e
 
@@ -177,7 +178,7 @@ class EncryptionManager:
         if key_file.exists():
             try:
                 return key_file.read_bytes()
-            except Exception as e:
+            except (OSError, PermissionError) as e:
                 logger.error("failed_to_load_key_file", error=str(e))
 
         # Generate ephemeral key (NOT for production)
@@ -219,7 +220,7 @@ class EncryptionManager:
             # Return base64-encoded
             return base64.b64encode(encrypted_data).decode("utf-8")
 
-        except Exception as e:
+        except (ValueError, TypeError, UnicodeEncodeError) as e:
             logger.error("encryption_failed", error=str(e))
             raise SecurityError(f"Encryption failed: {e}") from e
 
@@ -255,7 +256,7 @@ class EncryptionManager:
 
             return plaintext_bytes.decode("utf-8")
 
-        except Exception as e:
+        except (ValueError, TypeError, UnicodeDecodeError, binascii.Error) as e:
             logger.error("decryption_failed", error=str(e))
             raise SecurityError(f"Decryption failed: {e}") from e
 
@@ -307,7 +308,7 @@ class MemDocsStorage:
             logger.debug("pattern_stored", pattern_id=pattern_id)
             return True
 
-        except Exception as e:
+        except (OSError, PermissionError, json.JSONDecodeError) as e:
             logger.error("pattern_storage_failed", pattern_id=pattern_id, error=str(e))
             raise
 
@@ -334,7 +335,7 @@ class MemDocsStorage:
             logger.debug("pattern_retrieved", pattern_id=pattern_id)
             return pattern_data
 
-        except Exception as e:
+        except (OSError, PermissionError, json.JSONDecodeError) as e:
             logger.error("pattern_retrieval_failed", pattern_id=pattern_id, error=str(e))
             return None
 
@@ -358,7 +359,7 @@ class MemDocsStorage:
             logger.info("pattern_deleted", pattern_id=pattern_id)
             return True
 
-        except Exception as e:
+        except (OSError, PermissionError) as e:
             logger.error("pattern_deletion_failed", pattern_id=pattern_id, error=str(e))
             return False
 

empathy_os/workflows/base.py

@@ -33,6 +33,8 @@ try:
 except ImportError:
     pass  # python-dotenv not installed, rely on environment variables
 
+# Import caching infrastructure
+from empathy_os.cache import BaseCache, auto_setup_cache, create_cache
 from empathy_os.cost_tracker import MODEL_PRICING, CostTracker
 
 # Import unified types from empathy_os.models
@@ -160,6 +162,12 @@ class CostReport:
     savings_percent: float
     by_stage: dict[str, float] = field(default_factory=dict)
     by_tier: dict[str, float] = field(default_factory=dict)
+    # Cache metrics
+    cache_hits: int = 0
+    cache_misses: int = 0
+    cache_hit_rate: float = 0.0
+    estimated_cost_without_cache: float = 0.0
+    savings_from_cache: float = 0.0
 
 
 @dataclass
@@ -366,6 +374,8 @@ class BaseWorkflow(ABC):
         executor: LLMExecutor | None = None,
         telemetry_backend: TelemetryBackend | None = None,
         progress_callback: ProgressCallback | None = None,
+        cache: BaseCache | None = None,
+        enable_cache: bool = True,
     ):
         """Initialize workflow with optional cost tracker, provider, and config.
 
@@ -381,6 +391,9 @@ class BaseWorkflow(ABC):
                      Defaults to TelemetryStore (JSONL file backend).
             progress_callback: Callback for real-time progress updates.
                      If provided, enables live progress tracking during execution.
+            cache: Optional cache instance. If None and enable_cache=True,
+                   auto-creates cache with one-time setup prompt.
+            enable_cache: Whether to enable caching (default True).
 
         """
         from .config import WorkflowConfig
@@ -398,6 +411,11 @@ class BaseWorkflow(ABC):
         self._run_id: str | None = None  # Set at start of execute()
         self._api_key: str | None = None  # For default executor creation
 
+        # Cache support
+        self._cache: BaseCache | None = cache
+        self._enable_cache = enable_cache
+        self._cache_setup_attempted = False
+
         # Load config if not provided
         self._config = config or WorkflowConfig.load()
 
@@ -434,23 +452,61 @@ class BaseWorkflow(ABC):
         model = get_model(provider_str, tier.value, self._config)
         return model
 
+    def _maybe_setup_cache(self) -> None:
+        """Set up cache with one-time user prompt if needed.
+
+        This is called lazily on first workflow execution to avoid
+        blocking workflow initialization.
+        """
+        if not self._enable_cache:
+            return
+
+        if self._cache_setup_attempted:
+            return
+
+        self._cache_setup_attempted = True
+
+        # If cache already provided, use it
+        if self._cache is not None:
+            return
+
+        # Otherwise, trigger auto-setup (which may prompt user)
+        try:
+            auto_setup_cache()
+            self._cache = create_cache()
+            logger.info(f"Cache initialized for workflow: {self.name}")
+        except ImportError:
+            # Hybrid cache dependencies not available, fall back to hash-only
+            logger.info(
+                "Using hash-only cache (install empathy-framework[cache] for semantic caching)"
+            )
+            self._cache = create_cache(cache_type="hash")
+        except Exception:
+            # Graceful degradation - disable cache if setup fails
+            logger.warning("Cache setup failed, continuing without cache")
+            self._enable_cache = False
+
     async def _call_llm(
         self,
         tier: ModelTier,
         system: str,
         user_message: str,
         max_tokens: int = 4096,
+        stage_name: str | None = None,
     ) -> tuple[str, int, int]:
         """Provider-agnostic LLM call using the configured provider.
 
         This method uses run_step_with_executor internally to make LLM calls
         that respect the configured provider (anthropic, openai, google, etc.).
 
+        Supports automatic caching to reduce API costs and latency.
+
         Args:
             tier: Model tier to use (CHEAP, CAPABLE, PREMIUM)
             system: System prompt
             user_message: User message/prompt
             max_tokens: Maximum tokens in response
+            stage_name: Optional stage name for cache key (defaults to tier)
 
         Returns:
             Tuple of (response_content, input_tokens, output_tokens)
@@ -458,9 +514,32 @@ class BaseWorkflow(ABC):
         """
         from .step_config import WorkflowStepConfig
 
+        # Determine stage name for cache key
+        stage = stage_name or f"llm_call_{tier.value}"
+        model = self.get_model_for_tier(tier)
+
+        # Try cache lookup if enabled
+        if self._enable_cache and self._cache is not None:
+            try:
+                # Combine system + user message for cache key
+                full_prompt = f"{system}\n\n{user_message}" if system else user_message
+                cached_response = self._cache.get(self.name, stage, full_prompt, model)
+
+                if cached_response is not None:
+                    logger.debug(f"Cache hit for {self.name}:{stage}")
+                    # Cached response is dict with content, input_tokens, output_tokens
+                    return (
+                        cached_response["content"],
+                        cached_response["input_tokens"],
+                        cached_response["output_tokens"],
+                    )
+            except Exception:
+                # Cache lookup failed - continue with LLM call
+                logger.debug("Cache lookup failed, continuing with LLM call")
+
         # Create a step config for this call
         step = WorkflowStepConfig(
-            name=f"llm_call_{tier.value}",
+            name=stage,
             task_type="general",
             tier_hint=tier.value,
             description="LLM call",
@@ -473,6 +552,22 @@ class BaseWorkflow(ABC):
                 prompt=user_message,
                 system=system,
             )
+
+            # Store in cache if enabled
+            if self._enable_cache and self._cache is not None:
+                try:
+                    full_prompt = f"{system}\n\n{user_message}" if system else user_message
+                    response_data = {
+                        "content": content,
+                        "input_tokens": in_tokens,
+                        "output_tokens": out_tokens,
+                    }
+                    self._cache.put(self.name, stage, full_prompt, model, response_data)
+                    logger.debug(f"Cached response for {self.name}:{stage}")
+                except Exception:
+                    # Cache storage failed - log but continue
+                    logger.debug("Failed to cache response")
+
             return content, in_tokens, out_tokens
         except (ValueError, TypeError, KeyError) as e:
             # Invalid input or configuration errors
@@ -523,6 +618,33 @@ class BaseWorkflow(ABC):
         savings = baseline_cost - total_cost
         savings_percent = (savings / baseline_cost * 100) if baseline_cost > 0 else 0.0
 
+        # Calculate cache metrics if cache is enabled
+        cache_hits = 0
+        cache_misses = 0
+        cache_hit_rate = 0.0
+        estimated_cost_without_cache = total_cost
+        savings_from_cache = 0.0
+
+        if self._cache is not None:
+            try:
+                stats = self._cache.get_stats()
+                cache_hits = stats.hits
+                cache_misses = stats.misses
+                cache_hit_rate = stats.hit_rate
+
+                # Estimate cost without cache (assumes cache hits would have incurred full cost)
+                # This is a conservative estimate
+                if cache_hits > 0:
+                    # Average cost per non-cached call
+                    avg_cost_per_call = total_cost / cache_misses if cache_misses > 0 else 0.0
+                    # Estimated additional cost if cache hits were actual API calls
+                    estimated_additional_cost = cache_hits * avg_cost_per_call
+                    estimated_cost_without_cache = total_cost + estimated_additional_cost
+                    savings_from_cache = estimated_additional_cost
+            except (AttributeError, TypeError):
+                # Cache doesn't support stats or error occurred
+                pass
+
         return CostReport(
             total_cost=total_cost,
             baseline_cost=baseline_cost,
@@ -530,6 +652,11 @@ class BaseWorkflow(ABC):
             savings_percent=savings_percent,
             by_stage=by_stage,
             by_tier=by_tier,
+            cache_hits=cache_hits,
+            cache_misses=cache_misses,
+            cache_hit_rate=cache_hit_rate,
+            estimated_cost_without_cache=estimated_cost_without_cache,
+            savings_from_cache=savings_from_cache,
         )
 
     @abstractmethod
@@ -576,6 +703,9 @@ class BaseWorkflow(ABC):
             WorkflowResult with stages, output, and cost report
 
         """
+        # Set up cache (one-time setup with user prompt if needed)
+        self._maybe_setup_cache()
+
         # Set run ID for telemetry correlation
         self._run_id = str(uuid.uuid4())
 

empathy_os/workflows/new_sample_workflow1_README.md

@@ -147,4 +147,4 @@ result = await workflow.execute(
 
 **Generated:** 2026-01-05
 **Patterns:** multi-stage
-**Complexity:** COMPLEX
+**Complexity:** COMPLEX

empathy_os/workflows/refactor_plan.py

@@ -482,8 +482,10 @@ Create a phased approach to reduce debt sustainably."""
                     prompt=user_message,
                     system=system,
                 )
-            except Exception:
-                # Fall back to legacy _call_llm if executor fails
+            except (RuntimeError, ValueError, TypeError, KeyError, AttributeError) as e:
+                # INTENTIONAL: Graceful fallback to legacy _call_llm if executor fails
+                # Catches executor/API/parsing errors during new execution path
+                logger.warning(f"Executor failed, falling back to legacy path: {e}")
                 response, input_tokens, output_tokens = await self._call_llm(
                     tier,
                     system or "",

empathy_os/workflows/security_audit.py

@@ -573,7 +573,7 @@ class SecurityAuditWorkflow(BaseWorkflow):
         if self.use_crew_for_assessment and self._crew_available:
             target = input_data.get("path", ".")
             try:
-                crew_report = await self._crew.audit(code=target, file_path=target)
+                crew_report = await self._crew.audit(target=target)
                 if crew_report and crew_report.findings:
                     crew_enhanced = True
                     # Convert crew findings to workflow format
@@ -620,11 +620,7 @@ class SecurityAuditWorkflow(BaseWorkflow):
             "risk_level": (
                 "critical"
                 if risk_score >= 75
-                else "high"
-                if risk_score >= 50
-                else "medium"
-                if risk_score >= 25
-                else "low"
+                else "high" if risk_score >= 50 else "medium" if risk_score >= 25 else "low"
             ),
             "severity_breakdown": severity_counts,
             "by_owasp_category": {k: len(v) for k, v in by_owasp.items()},

empathy_os/workflows/test5_README.md

@@ -155,4 +155,4 @@ result = await workflow.execute(
 
 **Generated:** 2026-01-05
 **Patterns:** crew-based
-**Complexity:** COMPLEX
+**Complexity:** COMPLEX

hot_reload/__init__.py

@@ -38,9 +38,9 @@ from .integration import HotReloadIntegration
 from .reloader import ReloadResult, WizardReloader
 from .watcher import WizardFileWatcher
 from .websocket import (
-                        ReloadNotificationManager,
-                        create_notification_callback,
-                        get_notification_manager,
+    ReloadNotificationManager,
+    create_notification_callback,
+    get_notification_manager,
 )
 
 __all__ = [

workflow_patterns/structural.py

@@ -41,12 +41,12 @@ class SingleStagePattern(WorkflowPattern):
         return [
             CodeSection(
                 location="class_attributes",
-                code=f'''    name = "{workflow_name}"
+                code=f"""    name = "{workflow_name}"
     description = "{description}"
     stages = ["process"]
     tier_map = {{
         "process": ModelTier.{tier},
-    }}''',
+    }}""",
                 priority=1,
             ),
             CodeSection(
@@ -140,8 +140,8 @@ class MultiStagePattern(WorkflowPattern):
         stage_routing = []
         for i, stage in enumerate(stages):
             stage_routing.append(
-                f'''        if stage_name == "{stage}":
-            return await self._{stage}(input_data, tier)'''
+                f"""        if stage_name == "{stage}":
+            return await self._{stage}(input_data, tier)"""
             )
 
         stage_routing_code = "\n".join(stage_routing)
@@ -181,10 +181,10 @@ class MultiStagePattern(WorkflowPattern):
         return [
             CodeSection(
                 location="class_attributes",
-                code=f'''    name = "{workflow_name}"
+                code=f"""    name = "{workflow_name}"
     description = "{description}"
     stages = {stages}
-{tier_map_code}''',
+{tier_map_code}""",
                 priority=1,
             ),
             CodeSection(
@@ -236,13 +236,13 @@ class CrewBasedPattern(WorkflowPattern):
         return [
             CodeSection(
                 location="class_attributes",
-                code=f'''    name = "{workflow_name}"
+                code=f"""    name = "{workflow_name}"
     description = "{description}"
     stages = ["analyze", "fix"]
     tier_map = {{
         "analyze": ModelTier.CAPABLE,
         "fix": ModelTier.CAPABLE,
-    }}''',
+    }}""",
                 priority=1,
             ),
             CodeSection(