htmlgraph 0.9.3__py3-none-any.whl → 0.27.5__py3-none-any.whl

htmlgraph/orchestration/live_events.py

@@ -0,0 +1,377 @@
+"""
+Live Event Publisher for Real-Time WebSocket Streaming.
+
+This module provides a centralized way to publish live events that will be
+streamed to connected WebSocket clients in real-time. Events are stored in
+a SQLite table and polled by the WebSocket handler.
+
+Usage:
+    from htmlgraph.orchestration.live_events import LiveEventPublisher
+
+    publisher = LiveEventPublisher()
+    publisher.spawner_start("gemini", "Analyze codebase", parent_event_id="evt-123")
+    publisher.spawner_phase("gemini", "executing", progress=50)
+    publisher.spawner_complete("gemini", success=True, duration=15.3, response="...")
+"""
+
+import json
+import logging
+import os
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any
+
+logger = logging.getLogger(__name__)
+
+
+class LiveEventPublisher:
+    """
+    Publisher for live events that get streamed via WebSocket.
+
+    Events are written to the live_events table in SQLite and polled
+    by the dashboard WebSocket handler for real-time streaming.
+    """
+
+    def __init__(self, db_path: str | None = None):
+        """
+        Initialize the live event publisher.
+
+        Args:
+            db_path: Path to SQLite database. If None, uses default location.
+        """
+        self._db_path = db_path
+        self._db: Any = None
+
+    def _get_db(self) -> Any:
+        """Get or create database connection."""
+        if self._db is None:
+            try:
+                from htmlgraph.db.schema import HtmlGraphDB
+
+                if self._db_path:
+                    self._db = HtmlGraphDB(self._db_path)
+                else:
+                    # Use project database path from environment or cwd
+                    project_root = os.getenv("HTMLGRAPH_PROJECT_ROOT", os.getcwd())
+                    default_path = str(
+                        Path(project_root) / ".htmlgraph" / "index.sqlite"
+                    )
+
+                    # Check if database exists
+                    if not Path(default_path).exists():
+                        logger.debug(f"Database not found at {default_path}")
+                        return None
+
+                    self._db = HtmlGraphDB(default_path)
+            except Exception as e:
+                logger.warning(f"Failed to initialize database for live events: {e}")
+                return None
+        return self._db
+
+    def _get_session_id(self) -> str | None:
+        """Get current session ID from environment."""
+        return os.getenv("HTMLGRAPH_PARENT_SESSION") or os.getenv("CLAUDE_SESSION_ID")
+
+    def publish(
+        self,
+        event_type: str,
+        event_data: dict[str, Any],
+        parent_event_id: str | None = None,
+        session_id: str | None = None,
+        spawner_type: str | None = None,
+    ) -> int | None:
+        """
+        Publish a live event for WebSocket streaming.
+
+        Args:
+            event_type: Type of event (e.g., spawner_start, spawner_complete)
+            event_data: Event payload dictionary
+            parent_event_id: Parent event ID for hierarchical linking
+            session_id: Session this event belongs to
+            spawner_type: Spawner type if applicable (gemini, codex, copilot)
+
+        Returns:
+            Live event ID if successful, None otherwise
+        """
+        db = self._get_db()
+        if db is None:
+            logger.debug("Database not available for live events")
+            return None
+
+        # Add timestamp to event data if not present
+        if "timestamp" not in event_data:
+            event_data["timestamp"] = datetime.now(timezone.utc).isoformat()
+
+        # Use session from environment if not provided
+        if session_id is None:
+            session_id = self._get_session_id()
+
+        try:
+            result: int | None = db.insert_live_event(
+                event_type=event_type,
+                event_data=event_data,
+                parent_event_id=parent_event_id,
+                session_id=session_id,
+                spawner_type=spawner_type,
+            )
+            return result
+        except Exception as e:
+            logger.warning(f"Failed to publish live event: {e}")
+            return None
+
+    def spawner_start(
+        self,
+        spawner_type: str,
+        prompt: str,
+        parent_event_id: str | None = None,
+        model: str | None = None,
+        session_id: str | None = None,
+    ) -> int | None:
+        """
+        Publish a spawner start event.
+
+        Args:
+            spawner_type: Type of spawner (gemini, codex, copilot)
+            prompt: Task prompt being executed
+            parent_event_id: Parent delegation event ID
+            model: Model being used (optional)
+            session_id: Session ID (optional, auto-detected)
+
+        Returns:
+            Live event ID if successful
+        """
+        event_data = {
+            "spawner_type": spawner_type,
+            "prompt_preview": prompt[:200] if prompt else "",
+            "prompt_length": len(prompt) if prompt else 0,
+            "status": "started",
+            "phase": "initializing",
+        }
+        if model:
+            event_data["model"] = model
+
+        return self.publish(
+            event_type="spawner_start",
+            event_data=event_data,
+            parent_event_id=parent_event_id,
+            session_id=session_id,
+            spawner_type=spawner_type,
+        )
+
+    def spawner_phase(
+        self,
+        spawner_type: str,
+        phase: str,
+        progress: int | None = None,
+        details: str | None = None,
+        parent_event_id: str | None = None,
+        session_id: str | None = None,
+    ) -> int | None:
+        """
+        Publish a spawner phase update event.
+
+        Args:
+            spawner_type: Type of spawner (gemini, codex, copilot)
+            phase: Current phase (e.g., "executing", "processing", "streaming")
+            progress: Progress percentage (0-100) if applicable
+            details: Additional details about the phase
+            parent_event_id: Parent delegation event ID
+            session_id: Session ID (optional, auto-detected)
+
+        Returns:
+            Live event ID if successful
+        """
+        event_data: dict[str, Any] = {
+            "spawner_type": spawner_type,
+            "phase": phase,
+            "status": "in_progress",
+        }
+        if progress is not None:
+            event_data["progress"] = progress
+        if details:
+            event_data["details"] = details[:200]
+
+        return self.publish(
+            event_type="spawner_phase",
+            event_data=event_data,
+            parent_event_id=parent_event_id,
+            session_id=session_id,
+            spawner_type=spawner_type,
+        )
+
+    def spawner_complete(
+        self,
+        spawner_type: str,
+        success: bool,
+        duration_seconds: float | None = None,
+        response_preview: str | None = None,
+        tokens_used: int | None = None,
+        error: str | None = None,
+        parent_event_id: str | None = None,
+        session_id: str | None = None,
+    ) -> int | None:
+        """
+        Publish a spawner completion event.
+
+        Args:
+            spawner_type: Type of spawner (gemini, codex, copilot)
+            success: Whether the spawner completed successfully
+            duration_seconds: Execution duration in seconds
+            response_preview: Preview of the response (first 200 chars)
+            tokens_used: Number of tokens used
+            error: Error message if failed
+            parent_event_id: Parent delegation event ID
+            session_id: Session ID (optional, auto-detected)
+
+        Returns:
+            Live event ID if successful
+        """
+        event_data: dict[str, Any] = {
+            "spawner_type": spawner_type,
+            "success": success,
+            "status": "completed" if success else "failed",
+            "phase": "done",
+        }
+        if duration_seconds is not None:
+            event_data["duration_seconds"] = round(duration_seconds, 2)
+        if response_preview:
+            event_data["response_preview"] = response_preview[:200]
+        if tokens_used is not None:
+            event_data["tokens_used"] = tokens_used
+        if error:
+            event_data["error"] = error[:500]
+
+        return self.publish(
+            event_type="spawner_complete",
+            event_data=event_data,
+            parent_event_id=parent_event_id,
+            session_id=session_id,
+            spawner_type=spawner_type,
+        )
+
+    def spawner_tool_use(
+        self,
+        spawner_type: str,
+        tool_name: str,
+        tool_input: dict[str, Any] | None = None,
+        parent_event_id: str | None = None,
+        session_id: str | None = None,
+    ) -> int | None:
+        """
+        Publish a spawner tool use event (when spawned AI uses a tool).
+
+        Args:
+            spawner_type: Type of spawner (gemini, codex, copilot)
+            tool_name: Name of the tool being used
+            tool_input: Tool input parameters
+            parent_event_id: Parent delegation event ID
+            session_id: Session ID (optional, auto-detected)
+
+        Returns:
+            Live event ID if successful
+        """
+        event_data: dict[str, Any] = {
+            "spawner_type": spawner_type,
+            "tool_name": tool_name,
+            "status": "tool_use",
+            "phase": "executing",
+        }
+        if tool_input:
+            # Truncate tool input for preview
+            input_str = json.dumps(tool_input)
+            event_data["tool_input_preview"] = input_str[:200]
+
+        return self.publish(
+            event_type="spawner_tool_use",
+            event_data=event_data,
+            parent_event_id=parent_event_id,
+            session_id=session_id,
+            spawner_type=spawner_type,
+        )
+
+    def spawner_message(
+        self,
+        spawner_type: str,
+        message: str,
+        role: str = "assistant",
+        parent_event_id: str | None = None,
+        session_id: str | None = None,
+    ) -> int | None:
+        """
+        Publish a spawner message event (when spawned AI sends a message).
+
+        Args:
+            spawner_type: Type of spawner (gemini, codex, copilot)
+            message: Message content
+            role: Message role (assistant, user, system)
+            parent_event_id: Parent delegation event ID
+            session_id: Session ID (optional, auto-detected)
+
+        Returns:
+            Live event ID if successful
+        """
+        event_data = {
+            "spawner_type": spawner_type,
+            "message_preview": message[:200] if message else "",
+            "message_length": len(message) if message else 0,
+            "role": role,
+            "status": "streaming",
+            "phase": "responding",
+        }
+
+        return self.publish(
+            event_type="spawner_message",
+            event_data=event_data,
+            parent_event_id=parent_event_id,
+            session_id=session_id,
+            spawner_type=spawner_type,
+        )
+
+
+# Global singleton instance for convenience
+_publisher: LiveEventPublisher | None = None
+
+
+def get_publisher(db_path: str | None = None) -> LiveEventPublisher:
+    """
+    Get the global LiveEventPublisher instance.
+
+    Args:
+        db_path: Optional database path (only used on first call)
+
+    Returns:
+        LiveEventPublisher instance
+    """
+    global _publisher
+    if _publisher is None:
+        _publisher = LiveEventPublisher(db_path)
+    return _publisher
+
+
+def publish_live_event(
+    event_type: str,
+    event_data: dict[str, Any],
+    parent_event_id: str | None = None,
+    session_id: str | None = None,
+    spawner_type: str | None = None,
+) -> int | None:
+    """
+    Convenience function to publish a live event using the global publisher.
+
+    Args:
+        event_type: Type of event
+        event_data: Event payload
+        parent_event_id: Parent event ID
+        session_id: Session ID
+        spawner_type: Spawner type
+
+    Returns:
+        Live event ID if successful
+    """
+    return get_publisher().publish(
+        event_type=event_type,
+        event_data=event_data,
+        parent_event_id=parent_event_id,
+        session_id=session_id,
+        spawner_type=spawner_type,
+    )

htmlgraph/orchestration/model_selection.py

@@ -0,0 +1,327 @@
+"""Intelligent model selection for task routing.
+
+import logging
+
+logger = logging.getLogger(__name__)
+
+This module provides functionality to select the best AI model for a given task
+based on task type, complexity, and budget constraints.
+
+Model Selection Strategy:
+- Exploration: Use Gemini (free tier) for cost-effective research
+- Debugging: Use Claude Sonnet (high context) for complex error analysis
+- Implementation: Use Codex (programming specialized) for code generation
+- Quality: Use Claude Haiku (fast) for linting and formatting
+
+Fallback Chain:
+Each model has fallback options if primary model is unavailable:
+- Gemini → Claude Haiku → Claude Sonnet
+- Codex → Claude Sonnet
+- Copilot → Claude Sonnet
+"""
+
+from enum import Enum
+
+
+class TaskType(str, Enum):
+    """Task classification types."""
+
+    EXPLORATION = "exploration"
+    DEBUGGING = "debugging"
+    IMPLEMENTATION = "implementation"
+    QUALITY = "quality"
+    GENERAL = "general"
+
+
+class ComplexityLevel(str, Enum):
+    """Complexity assessment levels."""
+
+    LOW = "low"
+    MEDIUM = "medium"
+    HIGH = "high"
+
+
+class BudgetMode(str, Enum):
+    """Budget constraints."""
+
+    FREE = "free"  # Use only free models
+    BALANCED = "balanced"  # Balance cost and quality
+    QUALITY = "quality"  # Prioritize best model
+
+
+class ModelSelection:
+    """Intelligent model selection engine."""
+
+    # Decision matrix: (task_type, complexity, budget) -> model
+    DECISION_MATRIX = {
+        # Exploration tasks - prioritize free/cheap options
+        (TaskType.EXPLORATION, ComplexityLevel.LOW, BudgetMode.FREE): "gemini",
+        (TaskType.EXPLORATION, ComplexityLevel.MEDIUM, BudgetMode.FREE): "gemini",
+        (TaskType.EXPLORATION, ComplexityLevel.HIGH, BudgetMode.FREE): "gemini",
+        (TaskType.EXPLORATION, ComplexityLevel.LOW, BudgetMode.BALANCED): "gemini",
+        (TaskType.EXPLORATION, ComplexityLevel.MEDIUM, BudgetMode.BALANCED): "gemini",
+        (
+            TaskType.EXPLORATION,
+            ComplexityLevel.HIGH,
+            BudgetMode.BALANCED,
+        ): "claude-sonnet",
+        (
+            TaskType.EXPLORATION,
+            ComplexityLevel.LOW,
+            BudgetMode.QUALITY,
+        ): "claude-sonnet",
+        (
+            TaskType.EXPLORATION,
+            ComplexityLevel.MEDIUM,
+            BudgetMode.QUALITY,
+        ): "claude-sonnet",
+        (TaskType.EXPLORATION, ComplexityLevel.HIGH, BudgetMode.QUALITY): "claude-opus",
+        # Debugging tasks - need strong reasoning
+        (TaskType.DEBUGGING, ComplexityLevel.LOW, BudgetMode.FREE): "claude-haiku",
+        (TaskType.DEBUGGING, ComplexityLevel.MEDIUM, BudgetMode.FREE): "claude-haiku",
+        (TaskType.DEBUGGING, ComplexityLevel.HIGH, BudgetMode.FREE): "claude-haiku",
+        (TaskType.DEBUGGING, ComplexityLevel.LOW, BudgetMode.BALANCED): "claude-sonnet",
+        (
+            TaskType.DEBUGGING,
+            ComplexityLevel.MEDIUM,
+            BudgetMode.BALANCED,
+        ): "claude-sonnet",
+        (TaskType.DEBUGGING, ComplexityLevel.HIGH, BudgetMode.BALANCED): "claude-opus",
+        (TaskType.DEBUGGING, ComplexityLevel.LOW, BudgetMode.QUALITY): "claude-opus",
+        (TaskType.DEBUGGING, ComplexityLevel.MEDIUM, BudgetMode.QUALITY): "claude-opus",
+        (TaskType.DEBUGGING, ComplexityLevel.HIGH, BudgetMode.QUALITY): "claude-opus",
+        # Implementation tasks - balance speed and quality
+        (TaskType.IMPLEMENTATION, ComplexityLevel.LOW, BudgetMode.FREE): "claude-haiku",
+        (
+            TaskType.IMPLEMENTATION,
+            ComplexityLevel.MEDIUM,
+            BudgetMode.FREE,
+        ): "claude-haiku",
+        (
+            TaskType.IMPLEMENTATION,
+            ComplexityLevel.HIGH,
+            BudgetMode.FREE,
+        ): "claude-haiku",
+        (TaskType.IMPLEMENTATION, ComplexityLevel.LOW, BudgetMode.BALANCED): "codex",
+        (TaskType.IMPLEMENTATION, ComplexityLevel.MEDIUM, BudgetMode.BALANCED): "codex",
+        (
+            TaskType.IMPLEMENTATION,
+            ComplexityLevel.HIGH,
+            BudgetMode.BALANCED,
+        ): "claude-opus",
+        (
+            TaskType.IMPLEMENTATION,
+            ComplexityLevel.LOW,
+            BudgetMode.QUALITY,
+        ): "claude-opus",
+        (
+            TaskType.IMPLEMENTATION,
+            ComplexityLevel.MEDIUM,
+            BudgetMode.QUALITY,
+        ): "claude-opus",
+        (
+            TaskType.IMPLEMENTATION,
+            ComplexityLevel.HIGH,
+            BudgetMode.QUALITY,
+        ): "claude-opus",
+        # Quality tasks - fast and cheap
+        (TaskType.QUALITY, ComplexityLevel.LOW, BudgetMode.FREE): "claude-haiku",
+        (TaskType.QUALITY, ComplexityLevel.MEDIUM, BudgetMode.FREE): "claude-haiku",
+        (TaskType.QUALITY, ComplexityLevel.HIGH, BudgetMode.FREE): "claude-haiku",
+        (TaskType.QUALITY, ComplexityLevel.LOW, BudgetMode.BALANCED): "claude-haiku",
+        (
+            TaskType.QUALITY,
+            ComplexityLevel.MEDIUM,
+            BudgetMode.BALANCED,
+        ): "claude-sonnet",
+        (TaskType.QUALITY, ComplexityLevel.HIGH, BudgetMode.BALANCED): "claude-sonnet",
+        (TaskType.QUALITY, ComplexityLevel.LOW, BudgetMode.QUALITY): "claude-sonnet",
+        (TaskType.QUALITY, ComplexityLevel.MEDIUM, BudgetMode.QUALITY): "claude-opus",
+        (TaskType.QUALITY, ComplexityLevel.HIGH, BudgetMode.QUALITY): "claude-opus",
+        # General tasks - safe defaults
+        (TaskType.GENERAL, ComplexityLevel.LOW, BudgetMode.FREE): "claude-haiku",
+        (TaskType.GENERAL, ComplexityLevel.MEDIUM, BudgetMode.FREE): "claude-haiku",
+        (TaskType.GENERAL, ComplexityLevel.HIGH, BudgetMode.FREE): "claude-haiku",
+        (TaskType.GENERAL, ComplexityLevel.LOW, BudgetMode.BALANCED): "claude-sonnet",
+        (
+            TaskType.GENERAL,
+            ComplexityLevel.MEDIUM,
+            BudgetMode.BALANCED,
+        ): "claude-sonnet",
+        (TaskType.GENERAL, ComplexityLevel.HIGH, BudgetMode.BALANCED): "claude-opus",
+        (TaskType.GENERAL, ComplexityLevel.LOW, BudgetMode.QUALITY): "claude-opus",
+        (TaskType.GENERAL, ComplexityLevel.MEDIUM, BudgetMode.QUALITY): "claude-opus",
+        (TaskType.GENERAL, ComplexityLevel.HIGH, BudgetMode.QUALITY): "claude-opus",
+    }
+
+    # Fallback chains for when primary model is unavailable
+    FALLBACK_CHAINS = {
+        "gemini": ["claude-haiku", "claude-sonnet", "claude-opus"],
+        "codex": ["claude-sonnet", "claude-opus"],
+        "copilot": ["claude-sonnet", "claude-opus"],
+        "claude-haiku": ["claude-sonnet", "claude-opus"],
+        "claude-sonnet": ["claude-opus", "claude-haiku"],
+        "claude-opus": ["claude-sonnet", "claude-haiku"],
+    }
+
+    @staticmethod
+    def select_model(
+        task_type: str | TaskType,
+        complexity: str | ComplexityLevel = "medium",
+        budget: str | BudgetMode = "balanced",
+    ) -> str:
+        """
+        Select best model for the given task parameters.
+
+        Args:
+            task_type: Type of task (exploration, debugging, implementation, quality, general)
+            complexity: Task complexity level (low, medium, high). Default: medium
+            budget: Budget mode (free, balanced, quality). Default: balanced
+
+        Returns:
+            Model name (e.g., "claude-sonnet", "gemini")
+
+        Example:
+            >>> model = ModelSelection.select_model("implementation", "high", "balanced")
+            >>> logger.info("%s", model)
+            'claude-opus'
+        """
+        # Normalize inputs
+        if isinstance(task_type, str):
+            try:
+                task_type = TaskType(task_type)
+            except ValueError:
+                task_type = TaskType.GENERAL
+
+        if isinstance(complexity, str):
+            try:
+                complexity = ComplexityLevel(complexity)
+            except ValueError:
+                complexity = ComplexityLevel.MEDIUM
+
+        if isinstance(budget, str):
+            try:
+                budget = BudgetMode(budget)
+            except ValueError:
+                budget = BudgetMode.BALANCED
+
+        # Look up in decision matrix
+        key = (task_type, complexity, budget)
+        return ModelSelection.DECISION_MATRIX.get(key, "claude-sonnet")
+
+    @staticmethod
+    def get_fallback_chain(primary_model: str) -> list[str]:
+        """
+        Get fallback models if primary model is unavailable.
+
+        Args:
+            primary_model: Primary model name
+
+        Returns:
+            List of fallback models in order of preference
+
+        Example:
+            >>> fallbacks = ModelSelection.get_fallback_chain("gemini")
+            >>> logger.info("%s", fallbacks)
+            ['claude-haiku', 'claude-sonnet', 'claude-opus']
+        """
+        return ModelSelection.FALLBACK_CHAINS.get(primary_model, ["claude-sonnet"])
+
+    @staticmethod
+    def estimate_tokens(
+        task_description: str, complexity: str | ComplexityLevel = "medium"
+    ) -> int:
+        """
+        Estimate token usage for a task.
+
+        Args:
+            task_description: Description of the task
+            complexity: Task complexity level
+
+        Returns:
+            Estimated tokens for the task
+
+        Estimation formula:
+        - Low complexity: ~500-1000 tokens
+        - Medium complexity: ~1000-5000 tokens
+        - High complexity: ~5000-20000 tokens
+        """
+        if isinstance(complexity, str):
+            try:
+                complexity = ComplexityLevel(complexity)
+            except ValueError:
+                complexity = ComplexityLevel.MEDIUM
+
+        # Base estimate on description length
+        description_tokens = len(task_description.split()) * 1.3  # ~1.3 tokens per word
+
+        # Add complexity multiplier
+        multipliers = {
+            ComplexityLevel.LOW: 1.0,
+            ComplexityLevel.MEDIUM: 2.0,
+            ComplexityLevel.HIGH: 5.0,
+        }
+
+        multiplier = multipliers.get(complexity, 2.0)
+        return int(description_tokens * multiplier)
+
+    @staticmethod
+    def is_model_available(model: str) -> bool:
+        """
+        Check if a model is available (basic check).
+
+        Args:
+            model: Model name to check
+
+        Returns:
+            True if model is known, False otherwise
+
+        Note:
+            This is a simple availability check. For actual availability,
+            you should check Claude CLI, Gemini CLI, etc.
+        """
+        available_models = {
+            "gemini",
+            "codex",
+            "copilot",
+            "claude-haiku",
+            "claude-sonnet",
+            "claude-opus",
+        }
+        return model in available_models
+
+
+def select_model(
+    task_type: str = "general",
+    complexity: str = "medium",
+    budget: str = "balanced",
+) -> str:
+    """
+    Convenience function for model selection.
+
+    Args:
+        task_type: Type of task. Default: general
+        complexity: Complexity level. Default: medium
+        budget: Budget mode. Default: balanced
+
+    Returns:
+        Recommended model name
+
+    Example:
+        >>> model = select_model("implementation", "high")
+        >>> logger.info("%s", model)
+    """
+    return ModelSelection.select_model(task_type, complexity, budget)
+
+
+def get_fallback_chain(model: str) -> list[str]:
+    """
+    Convenience function for getting fallback models.
+
+    Args:
+        model: Primary model name
+
+    Returns:
+        List of fallback models
+    """
+    return ModelSelection.get_fallback_chain(model)