empathy-framework 5.3.0__py3-none-any.whl → 5.4.0__py3-none-any.whl

empathy_os/workflows/builder.py

@@ -1,273 +0,0 @@
-"""Builder pattern for BaseWorkflow construction.
-
-Simplifies complex workflow configuration by providing a fluent API
-for setting optional parameters.
-
-Copyright 2025 Smart-AI-Memory
-Licensed under Fair Source License 0.9
-"""
-
-from __future__ import annotations
-
-from collections.abc import Callable
-from typing import TYPE_CHECKING, Any, Generic, TypeVar
-
-if TYPE_CHECKING:
-    from empathy_os.cache import BaseCache
-    from empathy_os.models import LLMExecutor, TelemetryBackend, UnifiedModelProvider
-    from empathy_os.workflows.base import BaseWorkflow
-    from empathy_os.workflows.config import WorkflowConfig
-    from empathy_os.workflows.progress import ProgressCallback
-    from empathy_os.workflows.routing import TierRoutingStrategy
-    from empathy_os.workflows.tier_tracking import WorkflowTierTracker
-
-T = TypeVar("T", bound="BaseWorkflow")
-
-
-class WorkflowBuilder(Generic[T]):
-    """Builder for complex workflow configuration.
-
-    Provides a fluent API for constructing workflows with many optional parameters.
-    Eliminates the need to pass 12+ constructor arguments.
-
-    Example:
-        >>> from empathy_os.workflows.test_gen import TestGenerationWorkflow
-        >>> from empathy_os.workflows.builder import WorkflowBuilder
-        >>> from empathy_os.workflows.routing import BalancedRouting
-        >>>
-        >>> workflow = (
-        ...     WorkflowBuilder(TestGenerationWorkflow)
-        ...     .with_config(my_config)
-        ...     .with_routing(BalancedRouting(budget=10.0))
-        ...     .with_cache_enabled(True)
-        ...     .with_telemetry_enabled(True)
-        ...     .build()
-        ... )
-
-    Chaining methods:
-        - with_config() - Set workflow configuration
-        - with_executor() - Set custom LLM executor
-        - with_provider() - Set model provider
-        - with_cache() - Set custom cache instance
-        - with_cache_enabled() - Enable/disable caching
-        - with_telemetry() - Set custom telemetry backend
-        - with_telemetry_enabled() - Enable/disable telemetry
-        - with_progress_callback() - Set progress callback
-        - with_tier_tracker() - Set tier tracker
-        - with_routing() - Set routing strategy
-        - build() - Construct the workflow
-    """
-
-    def __init__(self, workflow_class: type[T]):
-        """Initialize builder for a specific workflow class.
-
-        Args:
-            workflow_class: The workflow class to build (e.g., TestGenerationWorkflow)
-        """
-        self.workflow_class = workflow_class
-
-        # Optional configuration
-        self._config: WorkflowConfig | None = None
-        self._executor: LLMExecutor | None = None
-        self._provider: UnifiedModelProvider | None = None
-        self._cache: BaseCache | None = None
-        self._enable_cache: bool = True
-        self._telemetry_backend: TelemetryBackend | None = None
-        self._enable_telemetry: bool = True
-        self._progress_callback: ProgressCallback | None = None
-        self._tier_tracker: WorkflowTierTracker | None = None
-        self._routing_strategy: TierRoutingStrategy | None = None
-
-    def with_config(self, config: WorkflowConfig) -> WorkflowBuilder[T]:
-        """Set workflow configuration.
-
-        Args:
-            config: WorkflowConfig instance with provider, models, etc.
-
-        Returns:
-            Self for method chaining
-        """
-        self._config = config
-        return self
-
-    def with_executor(self, executor: LLMExecutor) -> WorkflowBuilder[T]:
-        """Set custom LLM executor.
-
-        Args:
-            executor: LLMExecutor instance for making LLM calls
-
-        Returns:
-            Self for method chaining
-        """
-        self._executor = executor
-        return self
-
-    def with_provider(self, provider: UnifiedModelProvider) -> WorkflowBuilder[T]:
-        """Set model provider.
-
-        Args:
-            provider: ModelProvider enum (ANTHROPIC, OPENAI, GOOGLE)
-
-        Returns:
-            Self for method chaining
-        """
-        self._provider = provider
-        return self
-
-    def with_cache(self, cache: BaseCache) -> WorkflowBuilder[T]:
-        """Set custom cache instance.
-
-        Args:
-            cache: BaseCache instance for caching LLM responses
-
-        Returns:
-            Self for method chaining
-        """
-        self._cache = cache
-        return self
-
-    def with_cache_enabled(self, enabled: bool) -> WorkflowBuilder[T]:
-        """Enable or disable caching.
-
-        Args:
-            enabled: Whether to enable caching (default: True)
-
-        Returns:
-            Self for method chaining
-        """
-        self._enable_cache = enabled
-        return self
-
-    def with_telemetry(self, backend: TelemetryBackend) -> WorkflowBuilder[T]:
-        """Set custom telemetry backend.
-
-        Args:
-            backend: TelemetryBackend instance for tracking workflow runs
-
-        Returns:
-            Self for method chaining
-        """
-        self._telemetry_backend = backend
-        return self
-
-    def with_telemetry_enabled(self, enabled: bool) -> WorkflowBuilder[T]:
-        """Enable or disable telemetry.
-
-        Args:
-            enabled: Whether to enable telemetry (default: True)
-
-        Returns:
-            Self for method chaining
-        """
-        self._enable_telemetry = enabled
-        return self
-
-    def with_progress_callback(
-        self, callback: ProgressCallback | Callable[[str, int, int], None]
-    ) -> WorkflowBuilder[T]:
-        """Set progress callback for workflow execution.
-
-        Args:
-            callback: ProgressCallback instance or callable(stage, current, total)
-
-        Returns:
-            Self for method chaining
-        """
-        self._progress_callback = callback  # type: ignore
-        return self
-
-    def with_tier_tracker(self, tracker: WorkflowTierTracker) -> WorkflowBuilder[T]:
-        """Set tier tracker for learning tier progression.
-
-        Args:
-            tracker: WorkflowTierTracker instance
-
-        Returns:
-            Self for method chaining
-        """
-        self._tier_tracker = tracker
-        return self
-
-    def with_routing(self, strategy: TierRoutingStrategy) -> WorkflowBuilder[T]:
-        """Set tier routing strategy.
-
-        Args:
-            strategy: TierRoutingStrategy (CostOptimized, PerformanceOptimized, Balanced)
-
-        Returns:
-            Self for method chaining
-
-        Example:
-            >>> from empathy_os.workflows.routing import BalancedRouting
-            >>> builder.with_routing(BalancedRouting(budget=50.0))
-        """
-        self._routing_strategy = strategy
-        return self
-
-    def build(self) -> T:
-        """Build the configured workflow.
-
-        Returns:
-            Configured workflow instance ready for execution
-
-        Raises:
-            TypeError: If workflow_class constructor doesn't accept the provided parameters
-        """
-        # Build kwargs for constructor
-        kwargs: dict[str, Any] = {}
-
-        if self._config is not None:
-            kwargs["config"] = self._config
-
-        if self._executor is not None:
-            kwargs["executor"] = self._executor
-
-        if self._provider is not None:
-            kwargs["provider"] = self._provider
-
-        if self._cache is not None:
-            kwargs["cache"] = self._cache
-
-        kwargs["enable_cache"] = self._enable_cache
-
-        if self._telemetry_backend is not None:
-            kwargs["telemetry_backend"] = self._telemetry_backend
-
-        kwargs["enable_telemetry"] = self._enable_telemetry
-
-        if self._progress_callback is not None:
-            kwargs["progress_callback"] = self._progress_callback
-
-        if self._tier_tracker is not None:
-            kwargs["tier_tracker"] = self._tier_tracker
-
-        if self._routing_strategy is not None:
-            kwargs["routing_strategy"] = self._routing_strategy
-
-        # Construct workflow
-        return self.workflow_class(**kwargs)
-
-
-def workflow_builder(workflow_class: type[T]) -> WorkflowBuilder[T]:
-    """Factory function for creating workflow builders.
-
-    Convenience function for creating builders with cleaner syntax.
-
-    Args:
-        workflow_class: The workflow class to build
-
-    Returns:
-        WorkflowBuilder instance
-
-    Example:
-        >>> from empathy_os.workflows.builder import workflow_builder
-        >>> from empathy_os.workflows.test_gen import TestGenerationWorkflow
-        >>>
-        >>> workflow = (
-        ...     workflow_builder(TestGenerationWorkflow)
-        ...     .with_cache_enabled(True)
-        ...     .with_telemetry_enabled(False)
-        ...     .build()
-        ... )
-    """
-    return WorkflowBuilder(workflow_class)

empathy_os/workflows/caching.py

@@ -1,253 +0,0 @@
-"""Caching Mixin for Workflow LLM Calls
-
-Extracted from BaseWorkflow to improve maintainability and reusability.
-Provides caching behavior for LLM calls with automatic cache setup.
-
-Copyright 2025 Smart-AI-Memory
-Licensed under Fair Source License 0.9
-"""
-
-from __future__ import annotations
-
-import logging
-from dataclasses import dataclass
-from typing import TYPE_CHECKING, Any, Protocol, runtime_checkable
-
-if TYPE_CHECKING:
-    from empathy_os.cache import BaseCache
-
-logger = logging.getLogger(__name__)
-
-
-@dataclass
-class CachedResponse:
-    """Cached LLM response data."""
-
-    content: str
-    input_tokens: int
-    output_tokens: int
-
-    def to_dict(self) -> dict[str, Any]:
-        """Convert to dictionary for cache storage."""
-        return {
-            "content": self.content,
-            "input_tokens": self.input_tokens,
-            "output_tokens": self.output_tokens,
-        }
-
-    @classmethod
-    def from_dict(cls, data: dict[str, Any]) -> CachedResponse:
-        """Create from dictionary (cache retrieval)."""
-        return cls(
-            content=data["content"],
-            input_tokens=data["input_tokens"],
-            output_tokens=data["output_tokens"],
-        )
-
-
-@runtime_checkable
-class CacheAwareWorkflow(Protocol):
-    """Protocol for workflows that support caching."""
-
-    name: str
-    _cache: BaseCache | None
-    _enable_cache: bool
-
-    def get_model_for_tier(self, tier: Any) -> str:
-        """Get model ID for a given tier."""
-        ...
-
-
-class CachingMixin:
-    """Mixin that provides caching behavior for LLM calls.
-
-    This mixin extracts caching logic from BaseWorkflow to improve
-    maintainability and enable reuse in other contexts.
-
-    Attributes:
-        _cache: Optional cache instance
-        _enable_cache: Whether caching is enabled
-        _cache_setup_attempted: Whether cache setup has been tried
-
-    Usage:
-        class MyWorkflow(CachingMixin, BaseWorkflow):
-            pass
-
-        # CachingMixin methods are now available
-        workflow._maybe_setup_cache()
-        cached = workflow._try_cache_lookup(...)
-        workflow._store_in_cache(...)
-    """
-
-    # Instance variables (set by __init__ or subclass)
-    _cache: BaseCache | None = None
-    _enable_cache: bool = True
-    _cache_setup_attempted: bool = False
-
-    # These must be provided by the class using this mixin
-    name: str = "unknown"
-
-    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
-
-        # Import here to avoid circular imports
-        from empathy_os.cache import auto_setup_cache, create_cache
-
-        # 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 as e:
-            # Hybrid cache dependencies not available, fall back to hash-only
-            logger.info(
-                f"Using hash-only cache (install empathy-framework[cache] for semantic caching): {e}"
-            )
-            self._cache = create_cache(cache_type="hash")
-        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
-
-    def _make_cache_key(self, system: str, user_message: str) -> str:
-        """Create cache key from system and user prompts.
-
-        Args:
-            system: System prompt
-            user_message: User message
-
-        Returns:
-            Combined prompt string for cache key
-        """
-        return f"{system}\n\n{user_message}" if system else user_message
-
-    def _try_cache_lookup(
-        self,
-        stage: str,
-        system: str,
-        user_message: str,
-        model: str,
-    ) -> CachedResponse | None:
-        """Try to retrieve a cached response.
-
-        Args:
-            stage: Stage name for cache key
-            system: System prompt
-            user_message: User message
-            model: Model ID
-
-        Returns:
-            CachedResponse if found, None otherwise
-        """
-        if not self._enable_cache or self._cache is None:
-            return None
-
-        try:
-            full_prompt = self._make_cache_key(system, user_message)
-            cached_data = self._cache.get(self.name, stage, full_prompt, model)
-
-            if cached_data is not None:
-                logger.debug(f"Cache hit for {self.name}:{stage}")
-                return CachedResponse.from_dict(cached_data)
-
-        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")
-
-        return None
-
-    def _store_in_cache(
-        self,
-        stage: str,
-        system: str,
-        user_message: str,
-        model: str,
-        response: CachedResponse,
-    ) -> bool:
-        """Store a response in the cache.
-
-        Args:
-            stage: Stage name for cache key
-            system: System prompt
-            user_message: User message
-            model: Model ID
-            response: Response to cache
-
-        Returns:
-            True if stored successfully, False otherwise
-        """
-        if not self._enable_cache or self._cache is None:
-            return False
-
-        try:
-            full_prompt = self._make_cache_key(system, user_message)
-            self._cache.put(self.name, stage, full_prompt, model, response.to_dict())
-            logger.debug(f"Cached response for {self.name}:{stage}")
-            return True
-        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 False
-
-    def _get_cache_type(self) -> str:
-        """Get the cache type for telemetry tracking.
-
-        Returns:
-            Cache type string (e.g., "hash", "semantic")
-        """
-        if self._cache is None:
-            return "none"
-
-        if hasattr(self._cache, "cache_type"):
-            ct = self._cache.cache_type
-            # Ensure it's a string (not a Mock object)
-            return str(ct) if ct and isinstance(ct, str) else "hash"
-
-        return "hash"  # Default assumption
-
-    def _get_cache_stats(self) -> dict[str, Any]:
-        """Get cache statistics for cost reporting.
-
-        Returns:
-            Dictionary with cache stats (hits, misses, hit_rate)
-        """
-        if self._cache is None:
-            return {"hits": 0, "misses": 0, "hit_rate": 0.0}
-
-        try:
-            stats = self._cache.get_stats()
-            return {
-                "hits": stats.hits,
-                "misses": stats.misses,
-                "hit_rate": stats.hit_rate,
-            }
-        except (AttributeError, TypeError) as e:
-            # Cache doesn't support stats
-            logger.debug(f"Cache stats not available: {e}")
-            return {"hits": 0, "misses": 0, "hit_rate": 0.0}