empathy-framework 4.7.1__py3-none-any.whl → 4.8.0__py3-none-any.whl

empathy_os/workflows/progress.py

@@ -11,12 +11,35 @@ from __future__ import annotations
 
 import asyncio
 import json
-from collections.abc import Callable, Coroutine
+import logging
+import sys
+import uuid
+from collections.abc import Callable, Coroutine, Generator
+from contextlib import contextmanager
 from dataclasses import dataclass, field
 from datetime import datetime
 from enum import Enum
 from typing import Any, Protocol
 
+logger = logging.getLogger(__name__)
+
+# Rich imports with fallback
+try:
+    from rich.console import Console, Group
+    from rich.live import Live
+    from rich.panel import Panel
+    from rich.progress import BarColumn, Progress, SpinnerColumn, TaskID, TextColumn
+    from rich.table import Table
+    from rich.text import Text
+
+    RICH_AVAILABLE = True
+except ImportError:
+    RICH_AVAILABLE = False
+    Console = None  # type: ignore
+    Live = None  # type: ignore
+    Panel = None  # type: ignore
+    Progress = None  # type: ignore
+
 
 class ProgressStatus(Enum):
     """Status of a workflow or stage."""
@@ -361,9 +384,9 @@ class ProgressTracker:
         for callback in self._callbacks:
             try:
                 callback(update)
-            except Exception as e:
-                # Log but don't fail on callback errors
-                print(f"Progress callback error: {e}")
+            except Exception:  # noqa: BLE001
+                # INTENTIONAL: Callbacks are optional - never fail workflow on callback error
+                logger.warning("Progress callback error", exc_info=True)
 
         # Call async callbacks
         for async_callback in self._async_callbacks:
@@ -387,39 +410,111 @@ class ProgressReporter(Protocol):
 
 
 class ConsoleProgressReporter:
-    """Simple console-based progress reporter for CLI usage."""
+    """Console-based progress reporter optimized for IDE environments.
 
-    def __init__(self, verbose: bool = False):
+    Provides clear, readable progress output that works reliably in:
+    - VSCode integrated terminal
+    - VSCode output panel
+    - IDE debug consoles
+    - Standard terminals
+
+    Uses Unicode symbols that render correctly in most environments.
+    """
+
+    def __init__(self, verbose: bool = False, show_tokens: bool = False):
+        """Initialize console progress reporter.
+
+        Args:
+            verbose: Show additional details (fallback info, errors)
+            show_tokens: Include token counts in output
+        """
         self.verbose = verbose
+        self.show_tokens = show_tokens
+        self._start_time: datetime | None = None
+        self._stage_times: dict[str, int] = {}
 
     def report(self, update: ProgressUpdate) -> None:
-        """Print progress to console."""
-        percent = f"{update.percent_complete:.0f}%"
+        """Print progress to console.
+
+        Args:
+            update: Progress update from the tracker
+        """
+        # Track start time for elapsed calculation
+        if self._start_time is None:
+            self._start_time = datetime.now()
+
+        percent = f"{update.percent_complete:3.0f}%"
         cost = f"${update.cost_so_far:.4f}"
+
+        # Status icons that work in most environments
         status_icon = {
             ProgressStatus.PENDING: "○",
-            ProgressStatus.RUNNING: "◐",
-            ProgressStatus.COMPLETED: "●",
+            ProgressStatus.RUNNING: "►",
+            ProgressStatus.COMPLETED: "✓",
             ProgressStatus.FAILED: "✗",
-            ProgressStatus.SKIPPED: "◌",
-            ProgressStatus.FALLBACK: "↩",
+            ProgressStatus.SKIPPED: "–",
+            ProgressStatus.FALLBACK: "↻",
             ProgressStatus.RETRYING: "↻",
         }.get(update.status, "?")
 
         # Get current tier from running stage
         tier_info = ""
+        model_info = ""
         if update.current_stage and update.stages:
             for stage in update.stages:
-                if stage.name == update.current_stage and stage.status == ProgressStatus.RUNNING:
-                    tier_info = f" [{stage.tier.upper()}]"
+                if stage.name == update.current_stage:
+                    if stage.status == ProgressStatus.RUNNING:
+                        tier_info = f" [{stage.tier.upper()}]"
+                        if stage.model:
+                            model_info = f" ({stage.model})"
+                    # Track stage duration
+                    if stage.duration_ms > 0:
+                        self._stage_times[stage.name] = stage.duration_ms
                     break
 
-        print(f"[{percent}] {status_icon} {update.message}{tier_info} ({cost})")
-
-        if self.verbose and update.fallback_info:
-            print(f"       Fallback: {update.fallback_info}")
-        if self.verbose and update.error:
-            print(f"       Error: {update.error}")
+        # Build output line
+        elapsed = ""
+        if self._start_time:
+            elapsed_sec = (datetime.now() - self._start_time).total_seconds()
+            if elapsed_sec >= 1:
+                elapsed = f" [{elapsed_sec:.1f}s]"
+
+        tokens_str = ""
+        if self.show_tokens and update.tokens_so_far > 0:
+            tokens_str = f" | {update.tokens_so_far:,} tokens"
+
+        # Format: [100%] ✓ Completed optimize [PREMIUM] ($0.0279) [12.3s]
+        output = f"[{percent}] {status_icon} {update.message}{tier_info} ({cost}{tokens_str}){elapsed}"
+        print(output)
+
+        # Verbose output
+        if self.verbose:
+            if update.fallback_info:
+                print(f"         ↳ Fallback: {update.fallback_info}")
+            if update.error:
+                print(f"         ↳ Error: {update.error}")
+
+        # Print summary only on final workflow completion (not stage completion)
+        if update.status == ProgressStatus.COMPLETED and "workflow" in update.message.lower():
+            self._print_summary(update)
+
+    def _print_summary(self, update: ProgressUpdate) -> None:
+        """Print workflow completion summary."""
+        if not self._stage_times:
+            return
+
+        print("")
+        print("─" * 50)
+        print("Stage Summary:")
+        for stage in update.stages:
+            if stage.status == ProgressStatus.COMPLETED:
+                duration_ms = stage.duration_ms or self._stage_times.get(stage.name, 0)
+                duration_str = f"{duration_ms}ms" if duration_ms < 1000 else f"{duration_ms/1000:.1f}s"
+                cost_str = f"${stage.cost:.4f}" if stage.cost > 0 else "—"
+                print(f"  {stage.name}: {duration_str} | {cost_str}")
+            elif stage.status == ProgressStatus.SKIPPED:
+                print(f"  {stage.name}: skipped")
+        print("─" * 50)
 
     async def report_async(self, update: ProgressUpdate) -> None:
         """Async version just calls sync."""
@@ -463,8 +558,6 @@ def create_progress_tracker(
         Configured ProgressTracker instance
 
     """
-    import uuid
-
     tracker = ProgressTracker(
         workflow_name=workflow_name,
         workflow_id=uuid.uuid4().hex[:12],
@@ -475,3 +568,212 @@ def create_progress_tracker(
         tracker.add_callback(reporter.report)
 
     return tracker
+
+
+class RichProgressReporter:
+    """Rich-based live progress display with spinner, progress bar, and metrics.
+
+    Provides real-time visual feedback during workflow execution:
+    - Progress bar showing stage completion (1/3, 2/3, etc.)
+    - Spinner during active LLM API calls
+    - Real-time cost and token display
+    - In-place updates (no terminal scrolling)
+
+    Requires Rich library. Falls back gracefully if unavailable.
+    """
+
+    def __init__(self, workflow_name: str, stage_names: list[str]) -> None:
+        """Initialize the Rich progress reporter.
+
+        Args:
+            workflow_name: Name of the workflow for display
+            stage_names: List of stage names for progress tracking
+        """
+        if not RICH_AVAILABLE:
+            raise RuntimeError("Rich library required for RichProgressReporter")
+
+        self.workflow_name = workflow_name
+        self.stage_names = stage_names
+        self.console = Console()
+        self._live: Live | None = None
+        self._progress: Progress | None = None
+        self._task_id: TaskID | None = None
+        self._current_stage = ""
+        self._cost = 0.0
+        self._tokens = 0
+        self._status = ProgressStatus.PENDING
+
+    def start(self) -> None:
+        """Start the live progress display."""
+        if not RICH_AVAILABLE or Progress is None or Live is None:
+            return
+
+        self._progress = Progress(
+            SpinnerColumn(),
+            TextColumn("[bold blue]{task.description}"),
+            BarColumn(bar_width=30),
+            TextColumn("[progress.percentage]{task.percentage:>3.0f}%"),
+            TextColumn("({task.completed}/{task.total})"),
+            console=self.console,
+            transient=False,
+        )
+
+        self._task_id = self._progress.add_task(
+            self.workflow_name,
+            total=len(self.stage_names),
+        )
+
+        self._live = Live(
+            self._create_display(),
+            console=self.console,
+            refresh_per_second=4,
+            transient=False,
+        )
+        self._live.start()
+
+    def stop(self) -> None:
+        """Stop the live progress display."""
+        if self._live:
+            self._live.stop()
+            self._live = None
+
+    def report(self, update: ProgressUpdate) -> None:
+        """Handle a progress update.
+
+        Args:
+            update: Progress update from the tracker
+        """
+        self._current_stage = update.current_stage
+        self._cost = update.cost_so_far
+        self._tokens = update.tokens_so_far
+        self._status = update.status
+
+        # Update progress bar
+        if self._progress is not None and self._task_id is not None:
+            completed = sum(
+                1 for s in update.stages if s.status == ProgressStatus.COMPLETED
+            )
+            self._progress.update(
+                self._task_id,
+                completed=completed,
+                description=f"{self.workflow_name}: {update.current_stage}",
+            )
+
+        # Refresh display
+        if self._live:
+            self._live.update(self._create_display())
+
+    async def report_async(self, update: ProgressUpdate) -> None:
+        """Async version of report."""
+        self.report(update)
+
+    def _create_display(self) -> Panel:
+        """Create the Rich display panel.
+
+        Returns:
+            Rich Panel containing progress information
+        """
+        if not RICH_AVAILABLE or Panel is None or Table is None:
+            raise RuntimeError("Rich not available")
+
+        # Build metrics table
+        metrics = Table(show_header=False, box=None, padding=(0, 2))
+        metrics.add_column("Label", style="dim")
+        metrics.add_column("Value", style="bold")
+
+        metrics.add_row("Cost:", f"${self._cost:.4f}")
+        metrics.add_row("Tokens:", f"{self._tokens:,}")
+        metrics.add_row("Stage:", self._current_stage or "Starting...")
+
+        # Status indicator
+        status_style = {
+            ProgressStatus.PENDING: "dim",
+            ProgressStatus.RUNNING: "blue",
+            ProgressStatus.COMPLETED: "green",
+            ProgressStatus.FAILED: "red",
+            ProgressStatus.FALLBACK: "yellow",
+            ProgressStatus.RETRYING: "yellow",
+        }.get(self._status, "white")
+
+        status_text = Text(self._status.value.upper(), style=status_style)
+
+        # Combine into panel
+        if self._progress is not None:
+            content = Group(self._progress, metrics)
+        else:
+            content = metrics
+
+        return Panel(
+            content,
+            title=f"[bold]{self.workflow_name}[/bold]",
+            subtitle=status_text,
+            border_style=status_style,
+        )
+
+    def __enter__(self) -> RichProgressReporter:
+        """Context manager entry."""
+        self.start()
+        return self
+
+    def __exit__(self, exc_type, exc_val, exc_tb) -> None:
+        """Context manager exit."""
+        self.stop()
+
+
+@contextmanager
+def live_progress(
+    workflow_name: str,
+    stage_names: list[str],
+    console: Console | None = None,
+) -> Generator[tuple[ProgressTracker, RichProgressReporter | None], None, None]:
+    """Context manager for live progress display during workflow execution.
+
+    Provides a ProgressTracker with optional Rich-based live display.
+    Falls back gracefully when Rich is unavailable or output is not a TTY.
+
+    Args:
+        workflow_name: Name of the workflow
+        stage_names: List of stage names in order
+        console: Optional Rich Console (creates new one if not provided)
+
+    Yields:
+        Tuple of (ProgressTracker, RichProgressReporter or None)
+
+    Example:
+        with live_progress("Code Review", ["analyze", "review", "summarize"]) as (tracker, _):
+            tracker.start_workflow()
+            for stage in stages:
+                tracker.start_stage(stage)
+                # ... do work ...
+                tracker.complete_stage(stage, cost=0.01, tokens_in=100, tokens_out=50)
+            tracker.complete_workflow()
+    """
+    tracker = ProgressTracker(
+        workflow_name=workflow_name,
+        workflow_id=uuid.uuid4().hex[:12],
+        stage_names=stage_names,
+    )
+
+    reporter: RichProgressReporter | None = None
+
+    # Use Rich if available and output is a TTY
+    if RICH_AVAILABLE and sys.stdout.isatty():
+        try:
+            reporter = RichProgressReporter(workflow_name, stage_names)
+            tracker.add_callback(reporter.report)
+            reporter.start()
+        except Exception:  # noqa: BLE001
+            # INTENTIONAL: Rich display is optional - fall back to console output
+            reporter = None
+            simple_reporter = ConsoleProgressReporter(verbose=False)
+            tracker.add_callback(simple_reporter.report)
+    else:
+        # No Rich or not a TTY - use simple console reporter
+        simple_reporter = ConsoleProgressReporter(verbose=False)
+        tracker.add_callback(simple_reporter.report)
+
+    try:
+        yield tracker, reporter
+    finally:
+        if reporter:
+            reporter.stop()

empathy_os/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 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
+
+

empathy_os/workflows/secure_release.py

@@ -166,6 +166,7 @@ class SecureReleasePipeline:
                 _get_crew_audit,
                 crew_report_to_workflow_format,
             )
+
             adapters_available = True
         except ImportError:
             adapters_available = False