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

htmlgraph/analytics/strategic/suggestion_engine.py

@@ -0,0 +1,747 @@
+"""
+SuggestionEngine - Generates context-aware suggestions with ranking.
+
+This module provides intelligent suggestion generation based on detected patterns:
+1. Proactive suggestions - Suggest next actions based on detected patterns
+2. Delegation recommendations - Suggest which subagent would be best for current task
+3. Parameter optimization - Suggest optimal token budgets, parallelization levels
+4. Risk assessment - Suggest when to use Sonnet vs Opus based on task complexity
+
+Usage:
+    from htmlgraph.analytics.strategic import SuggestionEngine
+
+    engine = SuggestionEngine(db_path)
+
+    # Get suggestions for current context
+    suggestions = engine.suggest(context)
+
+    # Rank suggestions by relevance
+    ranked = engine.rank(suggestions)
+
+    # Generate Task() code from pattern
+    code = engine.generate_task_code(pattern)
+"""
+
+import hashlib
+import json
+import logging
+import sqlite3
+from dataclasses import dataclass, field
+from enum import Enum
+from pathlib import Path
+from typing import Any
+
+from htmlgraph.analytics.strategic.pattern_detector import (
+    DelegationChain,
+    ErrorPattern,
+    Pattern,
+    PatternDetector,
+    ToolSequencePattern,
+)
+
+logger = logging.getLogger(__name__)
+
+
+class SuggestionType(Enum):
+    """Types of suggestions that can be generated."""
+
+    NEXT_ACTION = "next_action"  # Suggest next tool/action
+    DELEGATION = "delegation"  # Suggest which agent to delegate to
+    PARAMETER = "parameter"  # Suggest optimal parameters
+    MODEL_SELECTION = "model_selection"  # Suggest which model to use
+    ERROR_RESOLUTION = "error_resolution"  # Suggest how to resolve error
+    WORKFLOW = "workflow"  # Suggest workflow optimization
+
+
+@dataclass
+class TaskContext:
+    """
+    Context for generating suggestions.
+
+    Captures current state to enable context-aware suggestions.
+
+    Attributes:
+        session_id: Current session ID
+        recent_tools: List of recently used tools (most recent last)
+        current_task: Description of current task (if known)
+        recent_errors: List of recent error messages
+        agent_type: Current agent type (orchestrator, researcher, etc.)
+        model: Current model being used
+        token_budget: Remaining token budget (if tracked)
+        feature_id: Current feature being worked on (if known)
+        metadata: Additional context data
+    """
+
+    session_id: str = ""
+    recent_tools: list[str] = field(default_factory=list)
+    current_task: str = ""
+    recent_errors: list[str] = field(default_factory=list)
+    agent_type: str = "orchestrator"
+    model: str = "claude-sonnet"
+    token_budget: int | None = None
+    feature_id: str | None = None
+    metadata: dict[str, Any] = field(default_factory=dict)
+
+    @classmethod
+    def from_hook_input(cls, hook_input: dict[str, Any]) -> "TaskContext":
+        """
+        Create TaskContext from PreToolUse hook input.
+
+        Args:
+            hook_input: Hook input dictionary
+
+        Returns:
+            TaskContext instance
+        """
+        return cls(
+            session_id=hook_input.get("session_id", ""),
+            recent_tools=hook_input.get("recent_tools", []),
+            current_task=hook_input.get("prompt", ""),
+            recent_errors=hook_input.get("recent_errors", []),
+            agent_type=hook_input.get("agent_type", "orchestrator"),
+            model=hook_input.get("model", "claude-sonnet"),
+            token_budget=hook_input.get("token_budget"),
+            feature_id=hook_input.get("feature_id"),
+            metadata=hook_input.get("metadata", {}),
+        )
+
+
+@dataclass
+class Suggestion:
+    """
+    A suggestion generated by the engine.
+
+    Attributes:
+        suggestion_id: Unique identifier
+        suggestion_type: Type of suggestion
+        title: Short title for the suggestion
+        description: Detailed explanation
+        confidence: Confidence score (0.0-1.0)
+        relevance: Relevance to current context (0.0-1.0)
+        action_code: Code snippet to execute the suggestion (if applicable)
+        source_patterns: Pattern IDs that informed this suggestion
+        metadata: Additional suggestion-specific data
+    """
+
+    suggestion_id: str
+    suggestion_type: SuggestionType
+    title: str
+    description: str
+    confidence: float = 0.0
+    relevance: float = 0.0
+    action_code: str | None = None
+    source_patterns: list[str] = field(default_factory=list)
+    metadata: dict[str, Any] = field(default_factory=dict)
+
+    def to_dict(self) -> dict[str, Any]:
+        """Convert suggestion to dictionary for serialization."""
+        return {
+            "suggestion_id": self.suggestion_id,
+            "suggestion_type": self.suggestion_type.value,
+            "title": self.title,
+            "description": self.description,
+            "confidence": self.confidence,
+            "relevance": self.relevance,
+            "action_code": self.action_code,
+            "source_patterns": self.source_patterns,
+            "metadata": self.metadata,
+        }
+
+    @staticmethod
+    def generate_id(suggestion_type: SuggestionType, content: str) -> str:
+        """Generate unique suggestion ID."""
+        hash_input = f"{suggestion_type.value}:{content}"
+        hash_obj = hashlib.md5(hash_input.encode())
+        return f"sug-{hash_obj.hexdigest()[:8]}"
+
+    def score(self) -> float:
+        """
+        Calculate overall score for ranking.
+
+        Score = (confidence * 0.5) + (relevance * 0.5)
+        """
+        return (self.confidence * 0.5) + (self.relevance * 0.5)
+
+
+class SuggestionEngine:
+    """
+    Generates context-aware suggestions based on detected patterns.
+
+    The engine:
+    1. Analyzes current context (recent tools, errors, task)
+    2. Matches context against known patterns
+    3. Generates relevant suggestions
+    4. Ranks suggestions by confidence and relevance
+    """
+
+    def __init__(self, db_path: Path | str | None = None):
+        """
+        Initialize suggestion engine.
+
+        Args:
+            db_path: Path to HtmlGraph database. If None, uses default location.
+        """
+        if db_path is None:
+            from htmlgraph.config import get_database_path
+
+            db_path = get_database_path()
+
+        self.db_path = Path(db_path)
+        self._pattern_detector = PatternDetector(db_path)
+        self._conn: sqlite3.Connection | None = None
+
+    def _get_connection(self) -> sqlite3.Connection:
+        """Get database connection with row factory."""
+        if self._conn is None:
+            self._conn = sqlite3.connect(str(self.db_path))
+            self._conn.row_factory = sqlite3.Row
+        return self._conn
+
+    def close(self) -> None:
+        """Close database connections."""
+        if self._conn:
+            self._conn.close()
+            self._conn = None
+        self._pattern_detector.close()
+
+    def suggest(
+        self,
+        context: TaskContext,
+        max_suggestions: int = 5,
+    ) -> list[Suggestion]:
+        """
+        Generate suggestions based on current context.
+
+        Args:
+            context: Current task context
+            max_suggestions: Maximum number of suggestions to return
+
+        Returns:
+            List of suggestions sorted by score
+        """
+        suggestions: list[Suggestion] = []
+
+        # Generate suggestions from different sources
+        suggestions.extend(self._suggest_from_tool_patterns(context))
+        suggestions.extend(self._suggest_from_delegation_patterns(context))
+        suggestions.extend(self._suggest_from_error_patterns(context))
+        suggestions.extend(self._suggest_model_selection(context))
+
+        # Rank and limit
+        ranked = self.rank(suggestions)
+        return ranked[:max_suggestions]
+
+    def _suggest_from_tool_patterns(self, context: TaskContext) -> list[Suggestion]:
+        """
+        Generate next-action suggestions from tool sequence patterns.
+
+        If recent tools match the start of a known high-success pattern,
+        suggest completing the pattern.
+
+        Args:
+            context: Current task context
+
+        Returns:
+            List of next-action suggestions
+        """
+        suggestions: list[Suggestion] = []
+
+        if len(context.recent_tools) < 2:
+            return suggestions
+
+        try:
+            # Get tool sequence patterns
+            patterns = self._pattern_detector.detect_tool_sequences(
+                window_size=3, min_frequency=3, days_back=30
+            )
+
+            # Find patterns that match recent tool sequence
+            recent = context.recent_tools[-2:]  # Last 2 tools
+
+            for pattern in patterns:
+                if not isinstance(pattern, ToolSequencePattern):
+                    continue
+
+                # Check if recent tools match start of pattern
+                if len(pattern.sequence) >= 3 and pattern.sequence[:2] == recent:
+                    next_tool = pattern.sequence[2]
+
+                    # Calculate relevance based on pattern success rate
+                    relevance = pattern.success_rate / 100
+
+                    suggestion = Suggestion(
+                        suggestion_id=Suggestion.generate_id(
+                            SuggestionType.NEXT_ACTION, f"next:{next_tool}"
+                        ),
+                        suggestion_type=SuggestionType.NEXT_ACTION,
+                        title=f"Consider using {next_tool} next",
+                        description=(
+                            f"Pattern '{' → '.join(pattern.sequence)}' has "
+                            f"{pattern.success_rate:.0f}% success rate across "
+                            f"{pattern.frequency} occurrences."
+                        ),
+                        confidence=pattern.confidence,
+                        relevance=relevance,
+                        source_patterns=[pattern.pattern_id],
+                        metadata={
+                            "next_tool": next_tool,
+                            "full_sequence": pattern.sequence,
+                            "success_rate": pattern.success_rate,
+                        },
+                    )
+                    suggestions.append(suggestion)
+
+        except Exception as e:
+            logger.warning(f"Error generating tool pattern suggestions: {e}")
+
+        return suggestions
+
+    def _suggest_from_delegation_patterns(
+        self, context: TaskContext
+    ) -> list[Suggestion]:
+        """
+        Generate delegation suggestions from chain patterns.
+
+        Suggest which agent to delegate to based on successful delegation chains.
+
+        Args:
+            context: Current task context
+
+        Returns:
+            List of delegation suggestions
+        """
+        suggestions: list[Suggestion] = []
+
+        try:
+            # Get delegation chain patterns
+            patterns = self._pattern_detector.detect_delegation_chains(
+                min_frequency=2, days_back=30
+            )
+
+            current_agent = context.agent_type
+
+            for pattern in patterns:
+                if not isinstance(pattern, DelegationChain):
+                    continue
+
+                # Check if current agent is in chain
+                if current_agent in pattern.agents:
+                    idx = pattern.agents.index(current_agent)
+                    if idx < len(pattern.agents) - 1:
+                        next_agent = pattern.agents[idx + 1]
+
+                        # Calculate relevance based on pattern success rate
+                        relevance = pattern.success_rate / 100
+
+                        suggestion = Suggestion(
+                            suggestion_id=Suggestion.generate_id(
+                                SuggestionType.DELEGATION, f"delegate:{next_agent}"
+                            ),
+                            suggestion_type=SuggestionType.DELEGATION,
+                            title=f"Consider delegating to {next_agent}",
+                            description=(
+                                f"Delegation chain '{' → '.join(pattern.agents)}' has "
+                                f"{pattern.success_rate:.0f}% success rate."
+                            ),
+                            confidence=pattern.confidence,
+                            relevance=relevance,
+                            action_code=self._generate_delegation_code(
+                                next_agent, context
+                            ),
+                            source_patterns=[pattern.pattern_id],
+                            metadata={
+                                "next_agent": next_agent,
+                                "full_chain": pattern.agents,
+                                "success_rate": pattern.success_rate,
+                            },
+                        )
+                        suggestions.append(suggestion)
+
+        except Exception as e:
+            logger.warning(f"Error generating delegation suggestions: {e}")
+
+        return suggestions
+
+    def _suggest_from_error_patterns(self, context: TaskContext) -> list[Suggestion]:
+        """
+        Generate error resolution suggestions from error patterns.
+
+        If recent errors match known patterns, suggest resolution strategies.
+
+        Args:
+            context: Current task context
+
+        Returns:
+            List of error resolution suggestions
+        """
+        suggestions: list[Suggestion] = []
+
+        if not context.recent_errors:
+            return suggestions
+
+        try:
+            # Get error patterns
+            patterns = self._pattern_detector.detect_error_patterns(
+                min_frequency=2, days_back=30
+            )
+
+            for error in context.recent_errors[-3:]:  # Check last 3 errors
+                error_lower = error.lower()
+
+                for pattern in patterns:
+                    if not isinstance(pattern, ErrorPattern):
+                        continue
+
+                    # Check if error matches pattern
+                    if pattern.error_type in error_lower or any(
+                        word in error_lower
+                        for word in pattern.error_message_pattern.lower().split()
+                    ):
+                        # Build resolution description
+                        resolution_desc = ""
+                        if pattern.resolution_strategies:
+                            strategies = ", ".join(pattern.resolution_strategies[:3])
+                            resolution_desc = f" Common resolutions: {strategies}."
+
+                        suggestion = Suggestion(
+                            suggestion_id=Suggestion.generate_id(
+                                SuggestionType.ERROR_RESOLUTION,
+                                f"error:{pattern.error_type}",
+                            ),
+                            suggestion_type=SuggestionType.ERROR_RESOLUTION,
+                            title=f"Resolve {pattern.error_type}",
+                            description=(
+                                f"This error pattern has occurred {pattern.frequency} times "
+                                f"with {pattern.success_rate:.0f}% resolution rate.{resolution_desc}"
+                            ),
+                            confidence=pattern.confidence,
+                            relevance=0.8,  # High relevance for matching errors
+                            source_patterns=[pattern.pattern_id],
+                            metadata={
+                                "error_type": pattern.error_type,
+                                "resolution_strategies": pattern.resolution_strategies,
+                                "tool_context": pattern.tool_context,
+                            },
+                        )
+                        suggestions.append(suggestion)
+                        break  # One suggestion per error
+
+        except Exception as e:
+            logger.warning(f"Error generating error resolution suggestions: {e}")
+
+        return suggestions
+
+    def _suggest_model_selection(self, context: TaskContext) -> list[Suggestion]:
+        """
+        Suggest model selection based on task complexity.
+
+        Uses heuristics to determine if Haiku, Sonnet, or Opus is appropriate.
+
+        Args:
+            context: Current task context
+
+        Returns:
+            List of model selection suggestions
+        """
+        suggestions: list[Suggestion] = []
+
+        task = context.current_task.lower()
+
+        # Simple heuristics for model selection
+        # Complex tasks that benefit from Opus
+        complex_indicators = [
+            "refactor",
+            "architecture",
+            "design",
+            "optimize",
+            "security",
+            "performance",
+            "complex",
+            "critical",
+        ]
+
+        # Simple tasks suitable for Haiku
+        simple_indicators = [
+            "format",
+            "lint",
+            "typo",
+            "rename",
+            "move",
+            "copy",
+            "list",
+            "show",
+            "status",
+        ]
+
+        is_complex = any(ind in task for ind in complex_indicators)
+        is_simple = any(ind in task for ind in simple_indicators)
+
+        current_model = context.model.lower()
+
+        if is_complex and "opus" not in current_model:
+            suggestion = Suggestion(
+                suggestion_id=Suggestion.generate_id(
+                    SuggestionType.MODEL_SELECTION, "use:opus"
+                ),
+                suggestion_type=SuggestionType.MODEL_SELECTION,
+                title="Consider using Opus for this task",
+                description=(
+                    "This task appears complex and may benefit from Claude Opus's "
+                    "enhanced reasoning capabilities."
+                ),
+                confidence=0.6,
+                relevance=0.7,
+                metadata={"recommended_model": "claude-opus", "reason": "complex_task"},
+            )
+            suggestions.append(suggestion)
+
+        elif is_simple and "haiku" not in current_model:
+            suggestion = Suggestion(
+                suggestion_id=Suggestion.generate_id(
+                    SuggestionType.MODEL_SELECTION, "use:haiku"
+                ),
+                suggestion_type=SuggestionType.MODEL_SELECTION,
+                title="Consider using Haiku for this task",
+                description=(
+                    "This task appears simple and Haiku could complete it faster "
+                    "and more cost-effectively."
+                ),
+                confidence=0.6,
+                relevance=0.6,
+                metadata={"recommended_model": "claude-haiku", "reason": "simple_task"},
+            )
+            suggestions.append(suggestion)
+
+        return suggestions
+
+    def rank(self, suggestions: list[Suggestion]) -> list[Suggestion]:
+        """
+        Rank suggestions by score.
+
+        Args:
+            suggestions: List of suggestions to rank
+
+        Returns:
+            Sorted list of suggestions (highest score first)
+        """
+        return sorted(suggestions, key=lambda s: s.score(), reverse=True)
+
+    def explain(self, suggestion: Suggestion) -> str:
+        """
+        Generate a human-readable explanation for a suggestion.
+
+        Args:
+            suggestion: Suggestion to explain
+
+        Returns:
+            Explanation text
+        """
+        explanation_parts = [
+            f"**{suggestion.title}**",
+            "",
+            f"{suggestion.description}",
+            "",
+            f"Confidence: {suggestion.confidence:.0%}",
+            f"Relevance: {suggestion.relevance:.0%}",
+        ]
+
+        if suggestion.source_patterns:
+            explanation_parts.append(
+                f"Based on patterns: {', '.join(suggestion.source_patterns)}"
+            )
+
+        if suggestion.action_code:
+            explanation_parts.extend(
+                [
+                    "",
+                    "Suggested code:",
+                    "```python",
+                    suggestion.action_code,
+                    "```",
+                ]
+            )
+
+        return "\n".join(explanation_parts)
+
+    def generate_task_code(self, pattern: Pattern) -> str:
+        """
+        Generate Task() code snippet from a pattern.
+
+        Creates executable code that applies the pattern.
+
+        Args:
+            pattern: Pattern to generate code from
+
+        Returns:
+            Python code snippet for Task() call
+        """
+        if isinstance(pattern, ToolSequencePattern):
+            return self._generate_sequence_task_code(pattern)
+        elif isinstance(pattern, DelegationChain):
+            return self._generate_chain_task_code(pattern)
+        elif isinstance(pattern, ErrorPattern):
+            return self._generate_error_resolution_code(pattern)
+        else:
+            return "# No code generation available for this pattern type"
+
+    def _generate_sequence_task_code(self, pattern: ToolSequencePattern) -> str:
+        """Generate Task() code for tool sequence pattern."""
+        sequence_desc = " → ".join(pattern.sequence)
+        return f'''# Apply pattern: {sequence_desc}
+# Success rate: {pattern.success_rate:.0f}%
+Task(
+    prompt="""
+    Follow this successful workflow pattern:
+    {sequence_desc}
+
+    Execute each step in sequence, validating results before proceeding.
+    """,
+    max_tokens=8000
+)'''
+
+    def _generate_chain_task_code(self, pattern: DelegationChain) -> str:
+        """Generate Task() code for delegation chain pattern."""
+        if len(pattern.agents) < 2:
+            return "# Invalid delegation chain"
+
+        first_agent = pattern.agents[0]
+        second_agent = pattern.agents[1]
+        chain_desc = " → ".join(pattern.agents)
+
+        return f'''# Apply delegation chain: {chain_desc}
+# Success rate: {pattern.success_rate:.0f}%
+Task(
+    prompt="""
+    As {first_agent}, analyze the task and delegate to {second_agent}.
+
+    Successful chain pattern: {chain_desc}
+    """,
+    max_tokens=8000
+)'''
+
+    def _generate_error_resolution_code(self, pattern: ErrorPattern) -> str:
+        """Generate Task() code for error resolution pattern."""
+        strategies = (
+            ", ".join(pattern.resolution_strategies[:3])
+            if pattern.resolution_strategies
+            else "analyze and fix"
+        )
+
+        return f'''# Resolve {pattern.error_type}
+# Resolution rate: {pattern.success_rate:.0f}%
+Task(
+    prompt="""
+    Resolve {pattern.error_type} error.
+
+    Common resolution strategies: {strategies}
+
+    Tools commonly used in context: {", ".join(pattern.tool_context[:3]) if pattern.tool_context else "various"}
+    """,
+    max_tokens=8000
+)'''
+
+    def _generate_delegation_code(self, target_agent: str, context: TaskContext) -> str:
+        """Generate Task() code for delegation suggestion."""
+        return f'''Task(
+    prompt="""
+    Delegate to {target_agent} agent for the following task:
+    {context.current_task[:200] if context.current_task else "Current task"}
+    """,
+    max_tokens=8000
+)'''
+
+    def store_suggestion(self, suggestion: Suggestion, context: TaskContext) -> bool:
+        """
+        Store a suggestion in the database for feedback tracking.
+
+        Args:
+            suggestion: Suggestion to store
+            context: Context in which suggestion was generated
+
+        Returns:
+            True if stored successfully, False otherwise
+        """
+        conn = self._get_connection()
+        cursor = conn.cursor()
+
+        try:
+            cursor.execute(
+                """
+                INSERT INTO delegation_suggestions
+                (suggestion_id, suggestion_type, session_id, title, description,
+                 confidence, relevance, action_code, source_patterns, metadata,
+                 created_at)
+                VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, datetime('now'))
+            """,
+                (
+                    suggestion.suggestion_id,
+                    suggestion.suggestion_type.value,
+                    context.session_id,
+                    suggestion.title,
+                    suggestion.description,
+                    suggestion.confidence,
+                    suggestion.relevance,
+                    suggestion.action_code,
+                    json.dumps(suggestion.source_patterns),
+                    json.dumps(suggestion.metadata),
+                ),
+            )
+
+            conn.commit()
+            return True
+
+        except sqlite3.Error as e:
+            logger.error(f"Error storing suggestion: {e}")
+            return False
+
+    def get_recent_suggestions(
+        self,
+        session_id: str,
+        limit: int = 10,
+    ) -> list[Suggestion]:
+        """
+        Get recent suggestions for a session.
+
+        Args:
+            session_id: Session to query
+            limit: Maximum number of suggestions
+
+        Returns:
+            List of recent suggestions
+        """
+        conn = self._get_connection()
+        cursor = conn.cursor()
+
+        try:
+            cursor.execute(
+                """
+                SELECT * FROM delegation_suggestions
+                WHERE session_id = ?
+                ORDER BY created_at DESC
+                LIMIT ?
+            """,
+                (session_id, limit),
+            )
+
+            suggestions = []
+            for row in cursor.fetchall():
+                suggestion = Suggestion(
+                    suggestion_id=row["suggestion_id"],
+                    suggestion_type=SuggestionType(row["suggestion_type"]),
+                    title=row["title"],
+                    description=row["description"],
+                    confidence=row["confidence"],
+                    relevance=row["relevance"],
+                    action_code=row["action_code"],
+                    source_patterns=json.loads(row["source_patterns"])
+                    if row["source_patterns"]
+                    else [],
+                    metadata=json.loads(row["metadata"]) if row["metadata"] else {},
+                )
+                suggestions.append(suggestion)
+
+            return suggestions
+
+        except sqlite3.Error as e:
+            logger.error(f"Error retrieving suggestions: {e}")
+            return []