attune-ai 2.1.5__py3-none-any.whl → 2.2.0__py3-none-any.whl

attune/workflows/batch_processing.py

@@ -192,9 +192,7 @@ class BatchProcessingWorkflow:
                 )
 
             elif result_type == "expired":
-                results.append(
-                    BatchResult(task_id=task_id, success=False, error="Request expired")
-                )
+                results.append(BatchResult(task_id=task_id, success=False, error="Request expired"))
 
             elif result_type == "canceled":
                 results.append(

attune/workflows/compat.py

@@ -0,0 +1,156 @@
+"""Backward compatibility module for deprecated workflow enums.
+
+This module contains deprecated enums that were originally in base.py:
+- ModelTier: Use attune.models.ModelTier instead
+- ModelProvider: Use attune.models.ModelProvider instead
+
+These are maintained for backward compatibility only.
+New code should use attune.models imports directly.
+
+Migration guide:
+    # Old (deprecated):
+    from attune.workflows.base import ModelTier, ModelProvider
+
+    # New (recommended):
+    from attune.models import ModelTier, ModelProvider
+
+Copyright 2025 Smart-AI-Memory
+Licensed under Fair Source License 0.9
+"""
+
+from __future__ import annotations
+
+import warnings
+from enum import Enum
+from typing import TYPE_CHECKING
+
+# Import unified types for conversion
+from attune.models import ModelProvider as UnifiedModelProvider
+from attune.models import ModelTier as UnifiedModelTier
+
+if TYPE_CHECKING:
+    pass
+
+
+class ModelTier(Enum):
+    """DEPRECATED: Model tier for cost optimization.
+
+    This enum is deprecated and will be removed in v5.0.
+    Use attune.models.ModelTier instead.
+
+    Migration:
+        # Old:
+        from attune.workflows.base import ModelTier
+
+        # New:
+        from attune.models import ModelTier
+
+    Why deprecated:
+        - Creates confusion with dual definitions
+        - attune.models.ModelTier is the canonical location
+        - Simplifies imports and reduces duplication
+    """
+
+    CHEAP = "cheap"  # Haiku/GPT-4o-mini - $0.25-1.25/M tokens
+    CAPABLE = "capable"  # Sonnet/GPT-4o - $3-15/M tokens
+    PREMIUM = "premium"  # Opus/o1 - $15-75/M tokens
+
+    def __init__(self, value: str):
+        """Initialize with deprecation warning."""
+        # Only warn once per process, not per instance
+        if not hasattr(self.__class__, "_deprecation_warned"):
+            warnings.warn(
+                "workflows.base.ModelTier is deprecated and will be removed in v5.0. "
+                "Use attune.models.ModelTier instead. "
+                "Update imports: from attune.models import ModelTier",
+                DeprecationWarning,
+                stacklevel=4,
+            )
+            self.__class__._deprecation_warned = True
+
+    def to_unified(self) -> UnifiedModelTier:
+        """Convert to unified ModelTier from attune.models."""
+        return UnifiedModelTier(self.value)
+
+
+class ModelProvider(Enum):
+    """DEPRECATED: Supported model providers.
+
+    This enum is deprecated and will be removed in v5.0.
+    Use attune.models.ModelProvider instead.
+
+    Migration:
+        # Old:
+        from attune.workflows.base import ModelProvider
+
+        # New:
+        from attune.models import ModelProvider
+    """
+
+    ANTHROPIC = "anthropic"
+    OPENAI = "openai"
+    GOOGLE = "google"  # Google Gemini models
+    OLLAMA = "ollama"
+    HYBRID = "hybrid"  # Mix of best models from different providers
+    CUSTOM = "custom"  # User-defined custom models
+
+    def to_unified(self) -> UnifiedModelProvider:
+        """Convert to unified ModelProvider from attune.models.
+
+        As of v5.0.0, framework is Claude-native. All providers map to ANTHROPIC.
+        """
+        # v5.0.0: Framework is Claude-native, only ANTHROPIC supported
+        return UnifiedModelProvider.ANTHROPIC
+
+
+def _build_provider_models() -> dict[ModelProvider, dict[ModelTier, str]]:
+    """Build PROVIDER_MODELS from MODEL_REGISTRY.
+
+    This ensures PROVIDER_MODELS stays in sync with the single source of truth.
+
+    Returns:
+        Dictionary mapping ModelProvider -> ModelTier -> model_id
+    """
+    # Lazy import to avoid circular dependencies
+    from attune.models import MODEL_REGISTRY
+
+    result: dict[ModelProvider, dict[ModelTier, str]] = {}
+
+    # Map string provider names to ModelProvider enum
+    provider_map = {
+        "anthropic": ModelProvider.ANTHROPIC,
+        "openai": ModelProvider.OPENAI,
+        "google": ModelProvider.GOOGLE,
+        "ollama": ModelProvider.OLLAMA,
+        "hybrid": ModelProvider.HYBRID,
+    }
+
+    # Map string tier names to ModelTier enum
+    tier_map = {
+        "cheap": ModelTier.CHEAP,
+        "capable": ModelTier.CAPABLE,
+        "premium": ModelTier.PREMIUM,
+    }
+
+    for provider_str, tiers in MODEL_REGISTRY.items():
+        if provider_str not in provider_map:
+            continue  # Skip custom providers
+        provider_enum = provider_map[provider_str]
+        result[provider_enum] = {}
+        for tier_str, model_info in tiers.items():
+            if tier_str in tier_map:
+                result[provider_enum][tier_map[tier_str]] = model_info.id
+
+    return result
+
+
+# Build PROVIDER_MODELS at module load time
+PROVIDER_MODELS: dict[ModelProvider, dict[ModelTier, str]] = _build_provider_models()
+
+# Expose all public symbols
+__all__ = [
+    "ModelTier",
+    "ModelProvider",
+    "PROVIDER_MODELS",
+    "_build_provider_models",
+]

attune/workflows/cost_mixin.py

@@ -0,0 +1,141 @@
+"""Cost tracking mixin for workflow classes.
+
+This module provides methods for calculating and reporting workflow costs,
+including tier-based pricing, baseline comparisons, and cache savings.
+
+Extracted from base.py for improved maintainability and import performance.
+
+Copyright 2025 Smart-AI-Memory
+Licensed under Fair Source License 0.9
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from .data_classes import CostReport
+
+
+class CostTrackingMixin:
+    """Mixin providing cost tracking capabilities for workflows.
+
+    This mixin adds methods for calculating costs, baseline comparisons,
+    and generating cost reports with cache savings.
+
+    Methods:
+        _calculate_cost: Calculate cost for a stage based on tier and tokens
+        _calculate_baseline_cost: Calculate premium-tier baseline cost
+        _generate_cost_report: Generate comprehensive cost report
+
+    Note:
+        This mixin expects the class to have:
+        - _stages_run: list[WorkflowStage] - stages executed in workflow
+        - _get_cache_stats(): method returning cache statistics dict
+        - ModelTier enum available
+    """
+
+    # These will be provided by the main class
+    _stages_run: list[Any]
+
+    def _calculate_cost(self, tier: Any, input_tokens: int, output_tokens: int) -> float:
+        """Calculate cost for a stage.
+
+        Args:
+            tier: ModelTier enum value for the stage
+            input_tokens: Number of input tokens used
+            output_tokens: Number of output tokens generated
+
+        Returns:
+            Total cost in dollars for this stage
+        """
+        from attune.cost_tracker import MODEL_PRICING
+
+        tier_name = tier.value
+        pricing = MODEL_PRICING.get(tier_name, MODEL_PRICING["capable"])
+        input_cost = (input_tokens / 1_000_000) * pricing["input"]
+        output_cost = (output_tokens / 1_000_000) * pricing["output"]
+        return input_cost + output_cost
+
+    def _calculate_baseline_cost(self, input_tokens: int, output_tokens: int) -> float:
+        """Calculate what the cost would be using premium tier.
+
+        Args:
+            input_tokens: Number of input tokens used
+            output_tokens: Number of output tokens generated
+
+        Returns:
+            Cost in dollars if premium tier was used
+        """
+        from attune.cost_tracker import MODEL_PRICING
+
+        pricing = MODEL_PRICING["premium"]
+        input_cost = (input_tokens / 1_000_000) * pricing["input"]
+        output_cost = (output_tokens / 1_000_000) * pricing["output"]
+        return input_cost + output_cost
+
+    def _generate_cost_report(self) -> CostReport:
+        """Generate cost report from completed stages.
+
+        Calculates total costs, baseline comparisons, savings percentages,
+        and includes cache performance metrics.
+
+        Returns:
+            CostReport with comprehensive cost breakdown and savings analysis
+        """
+        from .data_classes import CostReport
+
+        total_cost = 0.0
+        baseline_cost = 0.0
+        by_stage: dict[str, float] = {}
+        by_tier: dict[str, float] = {}
+
+        for stage in self._stages_run:
+            if stage.skipped:
+                continue
+
+            total_cost += stage.cost
+            by_stage[stage.name] = stage.cost
+
+            tier_name = stage.tier.value
+            by_tier[tier_name] = by_tier.get(tier_name, 0.0) + stage.cost
+
+            # Calculate what this would cost at premium tier
+            baseline_cost += self._calculate_baseline_cost(stage.input_tokens, stage.output_tokens)
+
+        savings = baseline_cost - total_cost
+        savings_percent = (savings / baseline_cost * 100) if baseline_cost > 0 else 0.0
+
+        # Calculate cache metrics using CachingMixin
+        cache_stats = self._get_cache_stats()
+        cache_hits = cache_stats["hits"]
+        cache_misses = cache_stats["misses"]
+        cache_hit_rate = cache_stats["hit_rate"]
+        estimated_cost_without_cache = total_cost
+        savings_from_cache = 0.0
+
+        # Estimate cost without cache (assumes cache hits would have incurred full cost)
+        if cache_hits > 0:
+            avg_cost_per_call = total_cost / cache_misses if cache_misses > 0 else 0.0
+            estimated_additional_cost = cache_hits * avg_cost_per_call
+            estimated_cost_without_cache = total_cost + estimated_additional_cost
+            savings_from_cache = estimated_additional_cost
+
+        return CostReport(
+            total_cost=total_cost,
+            baseline_cost=baseline_cost,
+            savings=savings,
+            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,
+        )
+
+    def _get_cache_stats(self) -> dict[str, Any]:
+        """Get cache statistics. Override in subclass or mixin."""
+        # Default implementation - CachingMixin provides the real one
+        return {"hits": 0, "misses": 0, "hit_rate": 0.0}

attune/workflows/data_classes.py

@@ -0,0 +1,92 @@
+"""Data classes for workflow execution.
+
+This module contains the core data structures used across all workflows:
+- WorkflowStage: Represents a single stage in a workflow
+- CostReport: Cost breakdown for a workflow execution
+- StageQualityMetrics: Quality metrics for stage output validation
+- WorkflowResult: Result of a workflow execution
+
+Copyright 2025 Smart-AI-Memory
+Licensed under Fair Source License 0.9
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from datetime import datetime
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    # Use unified ModelTier for type hints (avoids circular imports)
+    from attune.models import ModelTier
+
+
+@dataclass
+class WorkflowStage:
+    """Represents a single stage in a workflow."""
+
+    name: str
+    tier: ModelTier
+    description: str
+    input_tokens: int = 0
+    output_tokens: int = 0
+    cost: float = 0.0
+    result: Any = None
+    duration_ms: int = 0
+    skipped: bool = False
+    skip_reason: str | None = None
+
+
+@dataclass
+class CostReport:
+    """Cost breakdown for a workflow execution."""
+
+    total_cost: float
+    baseline_cost: float  # If all stages used premium
+    savings: float
+    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
+class StageQualityMetrics:
+    """Quality metrics for stage output validation."""
+
+    execution_succeeded: bool
+    output_valid: bool
+    quality_improved: bool  # Workflow-specific (e.g., health score improved)
+    error_type: str | None
+    validation_error: str | None
+
+
+@dataclass
+class WorkflowResult:
+    """Result of a workflow execution."""
+
+    success: bool
+    stages: list[WorkflowStage]
+    final_output: Any
+    cost_report: CostReport
+    started_at: datetime
+    completed_at: datetime
+    total_duration_ms: int
+    provider: str = "unknown"
+    error: str | None = None
+    # Structured error taxonomy for reliability
+    error_type: str | None = None  # "config" | "runtime" | "provider" | "timeout" | "validation"
+    transient: bool = False  # True if retry is reasonable (e.g., provider timeout)
+    # Optional metadata and summary for extended reporting
+    metadata: dict[str, Any] = field(default_factory=dict)
+    summary: str | None = None
+
+    @property
+    def duration_seconds(self) -> float:
+        """Get duration in seconds (computed from total_duration_ms)."""
+        return self.total_duration_ms / 1000.0

attune/workflows/document_gen/workflow.py

@@ -377,8 +377,7 @@ class DocumentGenerationWorkflow(BaseWorkflow):
                         )
                     else:  # API
                         logger.info(
-                            f"Cost: ~${cost_estimate['monetary_cost']:.4f} "
-                            f"(1M context window)"
+                            f"Cost: ~${cost_estimate['monetary_cost']:.4f} " f"(1M context window)"
                         )
 
             except Exception as e:
@@ -1257,13 +1256,15 @@ Make all code examples complete and executable."""
                 # Extract docstring
                 docstring = ast.get_docstring(node) or ""
 
-                functions.append({
-                    "name": node.name,
-                    "args": args_list,
-                    "return_type": return_type,
-                    "docstring": docstring,
-                    "lineno": node.lineno,
-                })
+                functions.append(
+                    {
+                        "name": node.name,
+                        "args": args_list,
+                        "return_type": return_type,
+                        "docstring": docstring,
+                        "lineno": node.lineno,
+                    }
+                )
 
         return functions
 
@@ -1407,9 +1408,7 @@ None
             func_name = func_info["name"]
             logger.debug(f"Generating API reference for {func_name}()")
 
-            api_section = await self._generate_api_section_for_function(
-                func_info, tier
-            )
+            api_section = await self._generate_api_section_for_function(func_info, tier)
             api_sections.append(api_section)
 
         # Append API reference section to narrative doc
@@ -1422,5 +1421,3 @@ None
         logger.info(f"Added {len(api_sections)} API reference sections")
 
         return full_doc
-
-

attune/workflows/history.py

@@ -67,7 +67,8 @@ class WorkflowHistoryStore:
         Idempotent - safe to call multiple times.
         """
         # Main workflow runs table
-        self.conn.execute("""
+        self.conn.execute(
+            """
             CREATE TABLE IF NOT EXISTS workflow_runs (
                 run_id TEXT PRIMARY KEY,
                 workflow_name TEXT NOT NULL,
@@ -87,10 +88,12 @@ class WorkflowHistoryStore:
                 summary TEXT,
                 created_at TEXT DEFAULT CURRENT_TIMESTAMP
             )
-        """)
+        """
+        )
 
         # Workflow stages (1:many relationship)
-        self.conn.execute("""
+        self.conn.execute(
+            """
             CREATE TABLE IF NOT EXISTS workflow_stages (
                 stage_id INTEGER PRIMARY KEY AUTOINCREMENT,
                 run_id TEXT NOT NULL,
@@ -104,34 +107,45 @@ class WorkflowHistoryStore:
                 output_tokens INTEGER DEFAULT 0,
                 FOREIGN KEY (run_id) REFERENCES workflow_runs(run_id)
             )
-        """)
+        """
+        )
 
         # Indexes for common queries
-        self.conn.execute("""
+        self.conn.execute(
+            """
             CREATE INDEX IF NOT EXISTS idx_workflow_name
             ON workflow_runs(workflow_name)
-        """)
+        """
+        )
 
-        self.conn.execute("""
+        self.conn.execute(
+            """
             CREATE INDEX IF NOT EXISTS idx_started_at
             ON workflow_runs(started_at DESC)
-        """)
+        """
+        )
 
-        self.conn.execute("""
+        self.conn.execute(
+            """
             CREATE INDEX IF NOT EXISTS idx_provider
             ON workflow_runs(provider)
-        """)
+        """
+        )
 
-        self.conn.execute("""
+        self.conn.execute(
+            """
             CREATE INDEX IF NOT EXISTS idx_success
             ON workflow_runs(success)
-        """)
+        """
+        )
 
         # Index for stage queries
-        self.conn.execute("""
+        self.conn.execute(
+            """
             CREATE INDEX IF NOT EXISTS idx_run_stages
             ON workflow_stages(run_id)
-        """)
+        """
+        )
 
         self.conn.commit()
         logger.debug(f"History store initialized: {self.db_path}")
@@ -184,13 +198,18 @@ class WorkflowHistoryStore:
                     result.error,
                     result.error_type,
                     1 if result.transient else 0,
-                    1
-                    if isinstance(result.final_output, dict)
-                    and result.final_output.get("xml_parsed")
-                    else 0,
-                    result.final_output.get("summary")
-                    if isinstance(result.final_output, dict)
-                    else None,
+                    (
+                        1
+                        if isinstance(result.final_output, dict)
+                        and result.final_output.get("xml_parsed")
+                        else 0
+                    ),
+                    (
+                        str(result.final_output.get("summary"))
+                        if isinstance(result.final_output, dict)
+                        and result.final_output.get("summary") is not None
+                        else None
+                    ),
                 ),
             )
 
@@ -328,7 +347,8 @@ class WorkflowHistoryStore:
         cursor = self.conn.cursor()
 
         # Total runs by workflow
-        cursor.execute("""
+        cursor.execute(
+            """
             SELECT
                 workflow_name,
                 COUNT(*) as runs,
@@ -337,41 +357,49 @@ class WorkflowHistoryStore:
                 SUM(success) as successful
             FROM workflow_runs
             GROUP BY workflow_name
-        """)
+        """
+        )
         by_workflow = {row["workflow_name"]: dict(row) for row in cursor.fetchall()}
 
         # Total runs by provider
-        cursor.execute("""
+        cursor.execute(
+            """
             SELECT
                 provider,
                 COUNT(*) as runs,
                 SUM(total_cost) as cost
             FROM workflow_runs
             GROUP BY provider
-        """)
+        """
+        )
         by_provider = {row["provider"]: dict(row) for row in cursor.fetchall()}
 
         # Total cost by tier
-        cursor.execute("""
+        cursor.execute(
+            """
             SELECT
                 tier,
                 SUM(cost) as total_cost
             FROM workflow_stages
             WHERE skipped = 0
             GROUP BY tier
-        """)
+        """
+        )
         by_tier = {row["tier"]: row["total_cost"] for row in cursor.fetchall()}
 
         # Recent runs (last 10)
-        cursor.execute("""
+        cursor.execute(
+            """
             SELECT * FROM workflow_runs
             ORDER BY started_at DESC
             LIMIT 10
-        """)
+        """
+        )
         recent_runs = [dict(row) for row in cursor.fetchall()]
 
         # Totals
-        cursor.execute("""
+        cursor.execute(
+            """
             SELECT
                 COUNT(*) as total_runs,
                 SUM(success) as successful_runs,
@@ -379,7 +407,8 @@ class WorkflowHistoryStore:
                 SUM(savings) as total_savings,
                 AVG(CASE WHEN success = 1 THEN savings_percent ELSE NULL END) as avg_savings_percent
             FROM workflow_runs
-        """)
+        """
+        )
         totals = dict(cursor.fetchone())
 
         return {
@@ -479,14 +508,10 @@ class WorkflowHistoryStore:
         # Security Note: f-string builds placeholder list only ("?, ?, ?")
         # Actual data (run_ids) passed as parameters - SQL injection safe
         placeholders = ",".join("?" * len(run_ids))
-        cursor.execute(
-            f"DELETE FROM workflow_stages WHERE run_id IN ({placeholders})", run_ids
-        )
+        cursor.execute(f"DELETE FROM workflow_stages WHERE run_id IN ({placeholders})", run_ids)
 
         # Delete runs (same safe parameterization pattern)
-        cursor.execute(
-            f"DELETE FROM workflow_runs WHERE run_id IN ({placeholders})", run_ids
-        )
+        cursor.execute(f"DELETE FROM workflow_runs WHERE run_id IN ({placeholders})", run_ids)
 
         self.conn.commit()
         logger.info(f"Cleaned up {len(run_ids)} runs older than {keep_days} days")

attune/workflows/llm_base.py

@@ -262,9 +262,7 @@ class LLMWorkflowGenerator(ABC):
         # Calculate rates
         total_requests = stats["llm_requests"]
         if total_requests > 0:
-            stats["llm_success_rate"] = (
-                total_requests - stats["llm_failures"]
-            ) / total_requests
+            stats["llm_success_rate"] = (total_requests - stats["llm_failures"]) / total_requests
             stats["template_fallback_rate"] = stats["template_fallbacks"] / total_requests
         else:
             stats["llm_success_rate"] = 0.0