attune-ai 2.0.0__py3-none-any.whl

attune/workflows/research_synthesis.py

@@ -0,0 +1,404 @@
+"""Research Synthesis Workflow
+
+A cost-optimized pipeline for research and analysis tasks:
+1. Haiku: Summarize each source (cheap, parallel)
+2. Sonnet: Identify patterns across summaries
+3. Opus: Synthesize final insights (conditional on complexity)
+
+Integration with attune.models:
+- Supports LLMExecutor for unified execution (optional)
+- WorkflowStepConfig for declarative step definitions
+- Automatic telemetry emission when executor is used
+- Falls back to direct API calls when executor not provided
+
+Copyright 2025 Smart-AI-Memory
+Licensed under Fair Source License 0.9
+"""
+
+from typing import Any
+
+from .base import BaseWorkflow, ModelTier
+from .step_config import WorkflowStepConfig
+
+# Step configurations for executor-based execution
+SUMMARIZE_STEP = WorkflowStepConfig(
+    name="summarize",
+    task_type="summarize",  # Routes to cheap tier
+    description="Summarize each source document",
+    max_tokens=2048,
+)
+
+ANALYZE_STEP = WorkflowStepConfig(
+    name="analyze",
+    task_type="analyze_patterns",  # Routes to capable tier
+    description="Identify patterns across summaries",
+    max_tokens=2048,
+)
+
+SYNTHESIZE_STEP = WorkflowStepConfig(
+    name="synthesize",
+    task_type="complex_reasoning",  # Routes to premium tier
+    description="Synthesize final insights",
+    max_tokens=4096,
+)
+
+SYNTHESIZE_STEP_CAPABLE = WorkflowStepConfig(
+    name="synthesize",
+    task_type="generate_content",  # Routes to capable tier
+    tier_hint="capable",  # Force capable tier
+    description="Synthesize final insights (lower complexity)",
+    max_tokens=4096,
+)
+
+
+class ResearchSynthesisWorkflow(BaseWorkflow):
+    """Multi-tier research synthesis workflow for comparing multiple documents.
+
+    Uses cheap models for initial summarization, capable models for
+    pattern analysis, and optionally premium models for final synthesis
+    when the analysis reveals high complexity.
+
+    IMPORTANT: This workflow requires at least 2 source documents.
+    For single research questions without sources, use a direct LLM call instead.
+
+    Usage (legacy - direct API calls):
+        workflow = ResearchSynthesisWorkflow()
+        result = await workflow.execute(
+            sources=["doc1.md", "doc2.md"],
+            question="What are the key patterns?"
+        )
+
+    Usage (executor-based - unified execution with telemetry):
+        from attune.models import MockLLMExecutor
+
+        executor = MockLLMExecutor()  # or EmpathyLLMExecutor for real calls
+        workflow = ResearchSynthesisWorkflow(executor=executor)
+        result = await workflow.execute(
+            sources=["doc1.md", "doc2.md"],
+            question="What are the key patterns?"
+        )
+
+    When using executor:
+    - Automatic task-based routing via WorkflowStepConfig
+    - Automatic telemetry emission (LLMCallRecord per call)
+    - Automatic workflow telemetry (WorkflowRunRecord at end)
+    - Fallback and retry policies applied automatically
+
+    Raises:
+        ValueError: If fewer than 2 sources are provided
+
+    """
+
+    name = "research"
+    description = "Cost-optimized research synthesis for multi-document analysis"
+    MIN_SOURCES = 2  # Minimum required sources
+    stages = ["summarize", "analyze", "synthesize"]
+    tier_map = {
+        "summarize": ModelTier.CHEAP,
+        "analyze": ModelTier.CAPABLE,
+        "synthesize": ModelTier.PREMIUM,
+    }
+
+    def __init__(self, complexity_threshold: float = 0.7, **kwargs: Any):
+        """Initialize workflow.
+
+        Args:
+            complexity_threshold: Threshold (0-1) above which premium
+                synthesis is used. Below this, capable tier is used.
+
+        """
+        super().__init__(**kwargs)
+        self.complexity_threshold = complexity_threshold
+        self._detected_complexity: float = 0.0
+
+    async def _call_with_step(
+        self,
+        step: WorkflowStepConfig,
+        system: str,
+        user_message: str,
+    ) -> tuple[str, int, int]:
+        """Make an LLM call using WorkflowStepConfig and executor (if available).
+
+        This is the recommended approach for new workflows. It provides:
+        - Automatic task-based routing
+        - Automatic telemetry emission
+        - Fallback and retry policies
+
+        If no executor is configured, falls back to direct API call.
+
+        Args:
+            step: WorkflowStepConfig defining the step
+            system: System prompt
+            user_message: User message
+
+        Returns:
+            (response_text, input_tokens, output_tokens)
+
+        """
+        if self._executor is not None:
+            # Use executor-based execution with telemetry
+            prompt = f"{system}\n\n{user_message}" if system else user_message
+            content, input_tokens, output_tokens, _cost = await self.run_step_with_executor(
+                step=step,
+                prompt=prompt,
+                system=system,
+            )
+            return content, input_tokens, output_tokens
+        # Fall back to direct API call
+        tier_value = step.effective_tier
+        tier = ModelTier(tier_value)
+        return await self._call_llm(
+            tier,
+            system,
+            user_message,
+            max_tokens=step.max_tokens or 4096,
+        )
+
+    def validate_sources(self, sources: list) -> None:
+        """Validate that sufficient sources are provided.
+
+        Args:
+            sources: List of source documents/content
+
+        Raises:
+            ValueError: If fewer than MIN_SOURCES are provided
+
+        """
+        if not sources or len(sources) < self.MIN_SOURCES:
+            raise ValueError(
+                f"ResearchSynthesisWorkflow requires at least {self.MIN_SOURCES} source documents. "
+                f"Got {len(sources) if sources else 0}. "
+                "For single research questions without sources, use a direct LLM call instead.",
+            )
+
+    async def execute(self, **kwargs: Any) -> Any:
+        """Execute the research synthesis workflow.
+
+        Args:
+            sources: List of source documents (required, minimum 2)
+            question: Research question to answer
+
+        Returns:
+            WorkflowResult with synthesis output
+
+        Raises:
+            ValueError: If fewer than 2 sources are provided
+
+        """
+        sources = kwargs.get("sources", [])
+        self.validate_sources(sources)
+        return await super().execute(**kwargs)
+
+    def should_skip_stage(self, stage_name: str, input_data: Any) -> tuple[bool, str | None]:
+        """Skip premium synthesis if complexity is low."""
+        if stage_name == "synthesize" and self._detected_complexity < self.complexity_threshold:
+            # Downgrade to capable tier instead of skipping
+            self.tier_map["synthesize"] = ModelTier.CAPABLE
+            return False, None
+        return False, None
+
+    async def run_stage(
+        self,
+        stage_name: str,
+        tier: ModelTier,
+        input_data: Any,
+    ) -> tuple[Any, int, int]:
+        """Execute a research workflow stage.
+
+        Args:
+            stage_name: Stage to run
+            tier: Model tier to use
+            input_data: Input data
+
+        Returns:
+            (output, input_tokens, output_tokens)
+
+        """
+        if stage_name == "summarize":
+            return await self._summarize(input_data, tier)
+        if stage_name == "analyze":
+            return await self._analyze(input_data, tier)
+        if stage_name == "synthesize":
+            return await self._synthesize(input_data, tier)
+        raise ValueError(f"Unknown stage: {stage_name}")
+
+    async def _summarize(self, input_data: dict, tier: ModelTier) -> tuple[dict, int, int]:
+        """Summarize each source document.
+
+        Note: Sources are validated in execute() before this method is called.
+        """
+        sources = input_data.get("sources", [])
+        question = input_data.get("question", "Summarize the content")
+
+        total_input = 0
+        total_output = 0
+
+        # Process each source
+        summaries = []
+        system = """You are a research assistant. Summarize the given content,
+extracting key points relevant to the research question. Be thorough but concise."""
+
+        for source in sources:
+            user_message = f"Research question: {question}\n\nSource content:\n{source}"
+
+            response, inp_tokens, out_tokens = await self._call_llm(
+                tier,
+                system,
+                user_message,
+                max_tokens=1024,
+            )
+
+            summaries.append(
+                {
+                    "source": str(source)[:100],
+                    "summary": response,
+                    "key_points": [],
+                },
+            )
+
+            total_input += inp_tokens
+            total_output += out_tokens
+
+        return (
+            {
+                "summaries": summaries,
+                "question": question,
+                "source_count": len(sources),
+            },
+            total_input,
+            total_output,
+        )
+
+    async def _analyze(self, input_data: dict, tier: ModelTier) -> tuple[dict, int, int]:
+        """Analyze patterns across summaries from multiple sources."""
+        summaries = input_data.get("summaries", [])
+        question = input_data.get("question", "")
+
+        # Combine summaries for analysis
+        combined = "\n\n".join(
+            [f"Source: {s.get('source', 'unknown')}\n{s.get('summary', '')}" for s in summaries],
+        )
+
+        system = """You are a research analyst. Analyze the summaries to identify:
+1. Common patterns and themes
+2. Contradictions or disagreements
+3. Key insights
+4. Complexity level (simple, moderate, complex)
+
+Provide a structured analysis."""
+
+        user_message = f"Research question: {question}\n\nSummaries to analyze:\n{combined}"
+
+        response, input_tokens, output_tokens = await self._call_llm(
+            tier,
+            system,
+            user_message,
+            max_tokens=2048,
+        )
+
+        # Estimate complexity from response length and content
+        self._detected_complexity = min(len(response) / 2000, 1.0)
+
+        return (
+            {
+                "patterns": [{"pattern": response, "sources": [], "confidence": 0.85}],
+                "complexity": self._detected_complexity,
+                "question": question,
+                "summary_count": len(summaries),
+                "analysis": response,
+            },
+            input_tokens,
+            output_tokens,
+        )
+
+    async def _synthesize(self, input_data: dict, tier: ModelTier) -> tuple[dict, int, int]:
+        """Synthesize final insights from multi-source analysis.
+
+        Supports XML-enhanced prompts when enabled in workflow config.
+        """
+        _patterns = input_data.get("patterns", [])
+        complexity = input_data.get("complexity", 0.5)
+        question = input_data.get("question", "")
+        analysis = input_data.get("analysis", "")
+
+        # Build input payload
+        input_payload = f"""Research question: {question}
+
+Analysis to synthesize:
+{analysis}
+
+Complexity level: {complexity:.2f}"""
+
+        # Check if XML prompts are enabled
+        if self._is_xml_enabled():
+            user_message = self._render_xml_prompt(
+                role="expert research synthesizer",
+                goal="Synthesize analysis into comprehensive answer with key insights",
+                instructions=[
+                    "Provide a comprehensive answer to the research question",
+                    "Highlight key insights and takeaways",
+                    "Note any caveats or areas needing further research",
+                    "Structure your response clearly with sections if appropriate",
+                    "Provide 1-2 concrete next steps or decisions",
+                ],
+                constraints=[
+                    "Be thorough, insightful, and actionable",
+                    "Focus on practical implications",
+                    "3-5 paragraphs for main answer",
+                ],
+                input_type="research_analysis",
+                input_payload=input_payload,
+                extra={
+                    "complexity_score": complexity,
+                },
+            )
+            system = None
+        else:
+            system = """You are an expert synthesizer. Based on the analysis provided:
+1. Provide a comprehensive answer to the research question
+2. Highlight key insights and takeaways
+3. Note any caveats or areas needing further research
+4. Structure your response clearly with sections if appropriate
+
+Be thorough, insightful, and actionable."""
+
+            user_message = f"""{input_payload}
+
+Provide a comprehensive synthesis and answer."""
+
+        response, input_tokens, output_tokens = await self._call_llm(
+            tier,
+            system or "",
+            user_message,
+            max_tokens=4096,
+        )
+
+        # Parse XML response if enforcement is enabled
+        parsed_data = self._parse_xml_response(response)
+
+        synthesis = {
+            "answer": response,
+            "key_insights": [],
+            "confidence": 0.85,
+            "model_tier_used": tier.value,
+            "complexity_score": complexity,
+        }
+
+        # Merge parsed XML data if available
+        if parsed_data.get("xml_parsed"):
+            synthesis.update(
+                {
+                    "xml_parsed": True,
+                    "summary": parsed_data.get("summary"),
+                    "findings": parsed_data.get("findings", []),
+                    "checklist": parsed_data.get("checklist", []),
+                },
+            )
+            # Extract key insights from parsed response
+            extra = parsed_data.get("_parsed_response")
+            if extra and hasattr(extra, "extra"):
+                key_insights = extra.extra.get("key_insights", [])
+                if key_insights:
+                    synthesis["key_insights"] = key_insights
+
+        return synthesis, input_tokens, output_tokens

attune/workflows/routing.py

@@ -0,0 +1,168 @@
+"""Tier routing strategies for workflow execution.
+
+Provides pluggable routing algorithms to determine which model tier
+should handle each workflow stage.
+
+Copyright 2025 Smart-AI-Memory
+Licensed under Fair Source License 0.9
+"""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from dataclasses import dataclass
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from attune.workflows.base import ModelTier
+
+
+@dataclass
+class RoutingContext:
+    """Context information for routing decisions.
+
+    Attributes:
+        task_type: Type of task (analyze, generate, review, etc.)
+        input_size: Estimated input tokens
+        complexity: Task complexity (simple, moderate, complex)
+        budget_remaining: Remaining budget in USD
+        latency_sensitivity: Latency requirements (low, medium, high)
+    """
+
+    task_type: str
+    input_size: int
+    complexity: str  # "simple" | "moderate" | "complex"
+    budget_remaining: float
+    latency_sensitivity: str  # "low" | "medium" | "high"
+
+
+class TierRoutingStrategy(ABC):
+    """Abstract base class for tier routing strategies.
+
+    Subclasses implement different routing algorithms:
+    - CostOptimizedRouting: Minimize cost
+    - PerformanceOptimizedRouting: Minimize latency
+    - BalancedRouting: Balance cost and performance
+    - HybridRouting: User-configured tier mappings
+    """
+
+    @abstractmethod
+    def route(self, context: RoutingContext) -> ModelTier:
+        """Route task to appropriate tier.
+
+        Args:
+            context: Routing context with task information
+
+        Returns:
+            ModelTier to use for this task
+        """
+        pass
+
+    @abstractmethod
+    def can_fallback(self, tier: ModelTier) -> bool:
+        """Whether fallback to cheaper tier is allowed.
+
+        Args:
+            tier: The tier that failed or exceeded budget
+
+        Returns:
+            True if fallback is allowed, False otherwise
+        """
+        pass
+
+
+class CostOptimizedRouting(TierRoutingStrategy):
+    """Route to cheapest tier that can handle the task.
+
+    Default strategy. Prioritizes cost savings over speed.
+
+    Example:
+        >>> strategy = CostOptimizedRouting()
+        >>> tier = strategy.route(context)  # CHEAP for simple tasks
+    """
+
+    def route(self, context: RoutingContext) -> ModelTier:
+        """Route based on task complexity, preferring cheaper tiers."""
+        from attune.workflows.base import ModelTier
+
+        if context.complexity == "simple":
+            return ModelTier.CHEAP
+        elif context.complexity == "complex":
+            return ModelTier.PREMIUM
+        return ModelTier.CAPABLE
+
+    def can_fallback(self, tier: ModelTier) -> bool:
+        """Allow fallback except for CHEAP tier."""
+        from attune.workflows.base import ModelTier
+
+        return tier != ModelTier.CHEAP
+
+
+class PerformanceOptimizedRouting(TierRoutingStrategy):
+    """Route to fastest tier regardless of cost.
+
+    Use for latency-sensitive workflows like interactive tools.
+
+    Example:
+        >>> strategy = PerformanceOptimizedRouting()
+        >>> tier = strategy.route(context)  # PREMIUM for high latency sensitivity
+    """
+
+    def route(self, context: RoutingContext) -> ModelTier:
+        """Route based on latency requirements."""
+        from attune.workflows.base import ModelTier
+
+        if context.latency_sensitivity == "high":
+            return ModelTier.PREMIUM
+        return ModelTier.CAPABLE
+
+    def can_fallback(self, tier: ModelTier) -> bool:
+        """Never fallback - performance is priority."""
+        return False
+
+
+class BalancedRouting(TierRoutingStrategy):
+    """Balance cost and performance with budget awareness.
+
+    Adjusts tier selection based on remaining budget and task complexity.
+
+    Example:
+        >>> strategy = BalancedRouting(total_budget=50.0)
+        >>> tier = strategy.route(context)  # Adapts based on budget
+    """
+
+    def __init__(self, total_budget: float):
+        """Initialize with total budget.
+
+        Args:
+            total_budget: Total budget in USD for this workflow execution
+
+        Raises:
+            ValueError: If total_budget is not positive
+        """
+        if total_budget <= 0:
+            raise ValueError("total_budget must be positive")
+        self.total_budget = total_budget
+
+    def route(self, context: RoutingContext) -> ModelTier:
+        """Route based on budget ratio and complexity."""
+        from attune.workflows.base import ModelTier
+
+        budget_ratio = context.budget_remaining / self.total_budget
+
+        # Low budget - use cheap tier
+        if budget_ratio < 0.2:
+            return ModelTier.CHEAP
+
+        # High budget + complex task - use premium
+        if budget_ratio > 0.7 and context.complexity == "complex":
+            return ModelTier.PREMIUM
+
+        # Default to capable
+        return ModelTier.CAPABLE
+
+    def can_fallback(self, tier: ModelTier) -> bool:
+        """Allow fallback when budget-constrained."""
+        return True
+
+