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

empathy_os/workflows/base.py

@@ -17,6 +17,7 @@ from __future__ import annotations
 
 import json
 import logging
+import time
 import uuid
 from abc import ABC, abstractmethod
 from dataclasses import dataclass, field
@@ -53,6 +54,14 @@ from empathy_os.models import ModelTier as UnifiedModelTier
 # Import progress tracking
 from .progress import ProgressCallback, ProgressTracker
 
+# Import telemetry tracking
+try:
+    from empathy_os.telemetry import UsageTracker
+    TELEMETRY_AVAILABLE = True
+except ImportError:
+    TELEMETRY_AVAILABLE = False
+    UsageTracker = None  # type: ignore
+
 if TYPE_CHECKING:
     from .config import WorkflowConfig
     from .step_config import WorkflowStepConfig
@@ -376,6 +385,7 @@ class BaseWorkflow(ABC):
         progress_callback: ProgressCallback | None = None,
         cache: BaseCache | None = None,
         enable_cache: bool = True,
+        enable_tier_tracking: bool = True,
     ):
         """Initialize workflow with optional cost tracker, provider, and config.
 
@@ -394,6 +404,7 @@ class BaseWorkflow(ABC):
             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).
+            enable_tier_tracking: Whether to enable automatic tier tracking (default True).
 
         """
         from .config import WorkflowConfig
@@ -416,6 +427,25 @@ class BaseWorkflow(ABC):
         self._enable_cache = enable_cache
         self._cache_setup_attempted = False
 
+        # Tier tracking support
+        self._enable_tier_tracking = enable_tier_tracking
+        self._tier_tracker = None
+
+        # Telemetry tracking (singleton instance)
+        self._telemetry_tracker: UsageTracker | None = None
+        self._enable_telemetry = True  # Enable by default
+        if TELEMETRY_AVAILABLE and UsageTracker is not None:
+            try:
+                self._telemetry_tracker = UsageTracker.get_instance()
+            except (OSError, PermissionError) as e:
+                # File system errors - log but disable telemetry
+                logger.debug(f"Failed to initialize telemetry tracker (file system error): {e}")
+                self._enable_telemetry = False
+            except (AttributeError, TypeError, ValueError) as e:
+                # Configuration or initialization errors
+                logger.debug(f"Failed to initialize telemetry tracker (config error): {e}")
+                self._enable_telemetry = False
+
         # Load config if not provided
         self._config = config or WorkflowConfig.load()
 
@@ -475,15 +505,19 @@ class BaseWorkflow(ABC):
             auto_setup_cache()
             self._cache = create_cache()
             logger.info(f"Cache initialized for workflow: {self.name}")
-        except ImportError:
+        except ImportError as e:
             # Hybrid cache dependencies not available, fall back to hash-only
             logger.info(
-                "Using hash-only cache (install empathy-framework[cache] for semantic caching)"
+                f"Using hash-only cache (install empathy-framework[cache] for semantic caching): {e}"
             )
             self._cache = create_cache(cache_type="hash")
-        except Exception:
-            # Graceful degradation - disable cache if setup fails
-            logger.warning("Cache setup failed, continuing without cache")
+        except (OSError, PermissionError) as e:
+            # File system errors - disable cache
+            logger.warning(f"Cache setup failed (file system error): {e}, continuing without cache")
+            self._enable_cache = False
+        except (ValueError, TypeError, AttributeError) as e:
+            # Configuration errors - disable cache
+            logger.warning(f"Cache setup failed (config error): {e}, continuing without cache")
             self._enable_cache = False
 
     async def _call_llm(
@@ -500,6 +534,7 @@ class BaseWorkflow(ABC):
         that respect the configured provider (anthropic, openai, google, etc.).
 
         Supports automatic caching to reduce API costs and latency.
+        Tracks telemetry for usage analysis and cost savings measurement.
 
         Args:
             tier: Model tier to use (CHEAP, CAPABLE, PREMIUM)
@@ -514,9 +549,13 @@ class BaseWorkflow(ABC):
         """
         from .step_config import WorkflowStepConfig
 
+        # Start timing for telemetry
+        start_time = time.time()
+
         # Determine stage name for cache key
         stage = stage_name or f"llm_call_{tier.value}"
         model = self.get_model_for_tier(tier)
+        cache_type = None
 
         # Try cache lookup if enabled
         if self._enable_cache and self._cache is not None:
@@ -527,15 +566,43 @@ class BaseWorkflow(ABC):
 
                 if cached_response is not None:
                     logger.debug(f"Cache hit for {self.name}:{stage}")
+                    # Determine cache type
+                    if hasattr(self._cache, "cache_type"):
+                        ct = self._cache.cache_type  # type: ignore
+                        # Ensure it's a string (not a Mock object)
+                        cache_type = str(ct) if ct and isinstance(ct, str) else "hash"
+                    else:
+                        cache_type = "hash"  # Default assumption
+
+                    # Track telemetry for cache hit
+                    duration_ms = int((time.time() - start_time) * 1000)
+                    in_tokens = cached_response["input_tokens"]
+                    out_tokens = cached_response["output_tokens"]
+                    cost = self._calculate_cost(tier, in_tokens, out_tokens)
+
+                    self._track_telemetry(
+                        stage=stage,
+                        tier=tier,
+                        model=model,
+                        cost=cost,
+                        tokens={"input": in_tokens, "output": out_tokens},
+                        cache_hit=True,
+                        cache_type=cache_type,
+                        duration_ms=duration_ms,
+                    )
+
                     # 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")
+            except (KeyError, TypeError, ValueError) as e:
+                # Malformed cache data - continue with LLM call
+                logger.debug(f"Cache lookup failed (malformed data): {e}, continuing with LLM call")
+            except (OSError, PermissionError) as e:
+                # File system errors - continue with LLM call
+                logger.debug(f"Cache lookup failed (file system error): {e}, continuing with LLM call")
 
         # Create a step config for this call
         step = WorkflowStepConfig(
@@ -547,12 +614,27 @@ class BaseWorkflow(ABC):
         )
 
         try:
-            content, in_tokens, out_tokens, _cost = await self.run_step_with_executor(
+            content, in_tokens, out_tokens, cost = await self.run_step_with_executor(
                 step=step,
                 prompt=user_message,
                 system=system,
             )
 
+            # Calculate duration
+            duration_ms = int((time.time() - start_time) * 1000)
+
+            # Track telemetry for actual LLM call
+            self._track_telemetry(
+                stage=stage,
+                tier=tier,
+                model=model,
+                cost=cost,
+                tokens={"input": in_tokens, "output": out_tokens},
+                cache_hit=False,
+                cache_type=None,
+                duration_ms=duration_ms,
+            )
+
             # Store in cache if enabled
             if self._enable_cache and self._cache is not None:
                 try:
@@ -564,21 +646,78 @@ class BaseWorkflow(ABC):
                     }
                     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")
+                except (OSError, PermissionError) as e:
+                    # File system errors - log but continue
+                    logger.debug(f"Failed to cache response (file system error): {e}")
+                except (ValueError, TypeError, KeyError) as e:
+                    # Data serialization errors - log but continue
+                    logger.debug(f"Failed to cache response (serialization error): {e}")
 
             return content, in_tokens, out_tokens
         except (ValueError, TypeError, KeyError) as e:
             # Invalid input or configuration errors
+            logger.warning(f"LLM call failed (invalid input): {e}")
             return f"Error calling LLM (invalid input): {e}", 0, 0
-        except (TimeoutError, RuntimeError) as e:
-            # Timeout or API errors
+        except (TimeoutError, RuntimeError, ConnectionError) as e:
+            # Timeout, API errors, or connection failures
+            logger.warning(f"LLM call failed (timeout/API/connection error): {e}")
             return f"Error calling LLM (timeout/API error): {e}", 0, 0
-        except Exception:
+        except (OSError, PermissionError) as e:
+            # File system or permission errors
+            logger.warning(f"LLM call failed (file system error): {e}")
+            return f"Error calling LLM (file system error): {e}", 0, 0
+        except Exception as e:
             # INTENTIONAL: Graceful degradation - return error message rather than crashing workflow
-            logger.exception("Unexpected error calling LLM")
-            return "Error calling LLM: unexpected error", 0, 0
+            logger.exception(f"Unexpected error calling LLM: {e}")
+            return f"Error calling LLM: {type(e).__name__}", 0, 0
+
+    def _track_telemetry(
+        self,
+        stage: str,
+        tier: ModelTier,
+        model: str,
+        cost: float,
+        tokens: dict[str, int],
+        cache_hit: bool,
+        cache_type: str | None,
+        duration_ms: int,
+    ) -> None:
+        """Track telemetry for an LLM call.
+
+        Args:
+            stage: Stage name
+            tier: Model tier used
+            model: Model ID used
+            cost: Cost in USD
+            tokens: Dictionary with "input" and "output" token counts
+            cache_hit: Whether this was a cache hit
+            cache_type: Cache type if cache hit
+            duration_ms: Duration in milliseconds
+
+        """
+        if not self._enable_telemetry or self._telemetry_tracker is None:
+            return
+
+        try:
+            provider_str = getattr(self, "_provider_str", "unknown")
+            self._telemetry_tracker.track_llm_call(
+                workflow=self.name,
+                stage=stage,
+                tier=tier.value.upper(),
+                model=model,
+                provider=provider_str,
+                cost=cost,
+                tokens=tokens,
+                cache_hit=cache_hit,
+                cache_type=cache_type,
+                duration_ms=duration_ms,
+            )
+        except (AttributeError, TypeError, ValueError) as e:
+            # INTENTIONAL: Telemetry tracking failures should never crash workflows
+            logger.debug(f"Failed to track telemetry (config/data error): {e}")
+        except (OSError, PermissionError) as e:
+            # File system errors - log but never crash workflow
+            logger.debug(f"Failed to track telemetry (file system error): {e}")
 
     def _calculate_cost(self, tier: ModelTier, input_tokens: int, output_tokens: int) -> float:
         """Calculate cost for a stage."""
@@ -709,6 +848,20 @@ class BaseWorkflow(ABC):
         # Set run ID for telemetry correlation
         self._run_id = str(uuid.uuid4())
 
+        # Auto tier recommendation
+        if self._enable_tier_tracking:
+            try:
+                from .tier_tracking import WorkflowTierTracker
+
+                self._tier_tracker = WorkflowTierTracker(self.name, self.description)
+                files_affected = kwargs.get("files_affected") or kwargs.get("path")
+                if files_affected and not isinstance(files_affected, list):
+                    files_affected = [str(files_affected)]
+                self._tier_tracker.show_recommendation(files_affected)
+            except Exception as e:
+                logger.debug(f"Tier tracking disabled: {e}")
+                self._enable_tier_tracking = False
+
         started_at = datetime.now()
         self._stages_run = []
         current_data = kwargs
@@ -793,6 +946,18 @@ class BaseWorkflow(ABC):
                     task_type=f"workflow:{self.name}:{stage_name}",
                 )
 
+                # Track telemetry for this stage
+                self._track_telemetry(
+                    stage=stage_name,
+                    tier=tier,
+                    model=model_id,
+                    cost=cost,
+                    tokens={"input": input_tokens, "output": output_tokens},
+                    cache_hit=False,
+                    cache_type=None,
+                    duration_ms=duration_ms,
+                )
+
                 # Pass output to next stage
                 current_data = output if isinstance(output, dict) else {"result": output}
 
@@ -802,16 +967,22 @@ class BaseWorkflow(ABC):
             logger.error(error)
             if self._progress_tracker:
                 self._progress_tracker.fail_workflow(error)
-        except (TimeoutError, RuntimeError) as e:
-            # Timeout or API errors
-            error = f"Workflow execution error (timeout/API): {e}"
+        except (TimeoutError, RuntimeError, ConnectionError) as e:
+            # Timeout, API errors, or connection failures
+            error = f"Workflow execution error (timeout/API/connection): {e}"
             logger.error(error)
             if self._progress_tracker:
                 self._progress_tracker.fail_workflow(error)
-        except Exception:
+        except (OSError, PermissionError) as e:
+            # File system or permission errors
+            error = f"Workflow execution error (file system): {e}"
+            logger.error(error)
+            if self._progress_tracker:
+                self._progress_tracker.fail_workflow(error)
+        except Exception as e:
             # INTENTIONAL: Workflow orchestration - catch all errors to report failure gracefully
-            logger.exception("Unexpected error in workflow execution")
-            error = "Workflow execution failed: unexpected error"
+            logger.exception(f"Unexpected error in workflow execution: {type(e).__name__}")
+            error = f"Workflow execution failed: {type(e).__name__}"
             if self._progress_tracker:
                 self._progress_tracker.fail_workflow(error)
 
@@ -881,6 +1052,32 @@ class BaseWorkflow(ABC):
         # Emit workflow telemetry to backend
         self._emit_workflow_telemetry(result)
 
+        # Auto-save tier progression
+        if self._enable_tier_tracking and self._tier_tracker:
+            try:
+                files_affected = kwargs.get("files_affected") or kwargs.get("path")
+                if files_affected and not isinstance(files_affected, list):
+                    files_affected = [str(files_affected)]
+
+                # Determine bug type from workflow name
+                bug_type_map = {
+                    "code-review": "code_quality",
+                    "bug-predict": "bug_prediction",
+                    "security-audit": "security_issue",
+                    "test-gen": "test_coverage",
+                    "refactor-plan": "refactoring",
+                    "health-check": "health_check",
+                }
+                bug_type = bug_type_map.get(self.name, "workflow_run")
+
+                self._tier_tracker.save_progression(
+                    workflow_result=result,
+                    files_affected=files_affected,
+                    bug_type=bug_type,
+                )
+            except Exception as e:
+                logger.debug(f"Failed to save tier progression: {e}")
+
         return result
 
     def describe(self) -> str:

empathy_os/workflows/config.py

@@ -38,6 +38,48 @@ except ImportError:
     YAML_AVAILABLE = False
 
 
+def _validate_file_path(path: str, allowed_dir: str | None = None) -> Path:
+    """Validate file path to prevent path traversal and arbitrary writes.
+
+    Args:
+        path: File path to validate
+        allowed_dir: Optional directory to restrict writes to
+
+    Returns:
+        Validated Path object
+
+    Raises:
+        ValueError: If path is invalid or unsafe
+    """
+    if not path or not isinstance(path, str):
+        raise ValueError("path must be a non-empty string")
+
+    # Check for null bytes
+    if "\x00" in path:
+        raise ValueError("path contains null bytes")
+
+    try:
+        resolved = Path(path).resolve()
+    except (OSError, RuntimeError) as e:
+        raise ValueError(f"Invalid path: {e}")
+
+    # Check if within allowed directory
+    if allowed_dir:
+        try:
+            allowed = Path(allowed_dir).resolve()
+            resolved.relative_to(allowed)
+        except ValueError:
+            raise ValueError(f"path must be within {allowed_dir}")
+
+    # Check for dangerous system paths
+    dangerous_paths = ["/etc", "/sys", "/proc", "/dev"]
+    for dangerous in dangerous_paths:
+        if str(resolved).startswith(dangerous):
+            raise ValueError(f"Cannot write to system directory: {dangerous}")
+
+    return resolved
+
+
 # Re-export for backward compatibility
 __all__ = [
     "DEFAULT_MODELS",
@@ -371,7 +413,10 @@ class WorkflowConfig:
 
     def save(self, path: str | Path) -> None:
         """Save configuration to file."""
-        path = Path(path)
+        # Validate path first (convert Path to string for validation)
+        path_str = str(path)
+        validated_path = _validate_file_path(path_str)
+
         data = {
             "default_provider": self.default_provider,
             "workflow_providers": self.workflow_providers,
@@ -387,15 +432,15 @@ class WorkflowConfig:
             "audit_level": self.audit_level,
         }
 
-        path.parent.mkdir(parents=True, exist_ok=True)
+        validated_path.parent.mkdir(parents=True, exist_ok=True)
 
-        if path.suffix in (".yaml", ".yml"):
+        if validated_path.suffix in (".yaml", ".yml"):
             if not YAML_AVAILABLE:
                 raise ImportError("PyYAML required for YAML config")
-            with open(path, "w") as f:
+            with open(validated_path, "w") as f:
                 yaml.dump(data, f, default_flow_style=False)
         else:
-            with open(path, "w") as f:
+            with open(validated_path, "w") as f:
                 json.dump(data, f, indent=2)