attune-ai 2.0.0__py3-none-any.whl

attune/workflows/builder.py

@@ -0,0 +1,273 @@
+"""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 attune.cache import BaseCache
+    from attune.models import LLMExecutor, TelemetryBackend, UnifiedModelProvider
+    from attune.workflows.base import BaseWorkflow
+    from attune.workflows.config import WorkflowConfig
+    from attune.workflows.progress import ProgressCallback
+    from attune.workflows.routing import TierRoutingStrategy
+    from attune.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 attune.workflows.test_gen import TestGenerationWorkflow
+        >>> from attune.workflows.builder import WorkflowBuilder
+        >>> from attune.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 attune.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 attune.workflows.builder import workflow_builder
+        >>> from attune.workflows.test_gen import TestGenerationWorkflow
+        >>>
+        >>> workflow = (
+        ...     workflow_builder(TestGenerationWorkflow)
+        ...     .with_cache_enabled(True)
+        ...     .with_telemetry_enabled(False)
+        ...     .build()
+        ... )
+    """
+    return WorkflowBuilder(workflow_class)

attune/workflows/caching.py

@@ -0,0 +1,253 @@
+"""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 attune.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 attune.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}