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

empathy_os/workflows/research_synthesis.py

@@ -1,404 +0,0 @@
-"""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 empathy_os.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 empathy_os.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

empathy_os/workflows/routing.py

@@ -1,168 +0,0 @@
-"""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 empathy_os.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 empathy_os.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 empathy_os.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 empathy_os.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 empathy_os.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
-
-