anvil-dev-framework 0.1.7 → 0.1.8

package/global/lib/context_optimizer.py

@@ -0,0 +1,323 @@
+"""
+Context Optimizer Service for Anvil Framework.
+
+Provides intelligent context loading to reduce initial token consumption
+while ensuring relevant information is available when needed.
+
+Features:
+- Trigger keyword detection for on-demand command loading
+- Session-level caching to avoid redundant loads
+- Integration with token_metrics for tracking
+- Compressed CLAUDE.md format support
+
+Usage:
+    from context_optimizer import ContextOptimizer, get_optimizer
+
+    optimizer = get_optimizer()
+    suggestions = optimizer.detect_triggers("help with anti-patterns")
+    optimizer.mark_loaded("patterns")
+"""
+
+import re
+from pathlib import Path
+from typing import Optional, Dict, List, Set, Any
+from dataclasses import dataclass, field
+from datetime import datetime
+
+# Try to import token_metrics for integration
+try:
+    from token_metrics import TokenMetrics, get_metrics
+    METRICS_AVAILABLE = True
+except ImportError:
+    METRICS_AVAILABLE = False
+
+
+@dataclass
+class TriggerRule:
+    """A rule mapping keywords to an on-demand command."""
+    command: str
+    keywords: List[str]
+    description: str
+    estimated_tokens: int
+    priority: int = 2  # 1=high, 2=medium, 3=low
+
+
+@dataclass
+class LoadSuggestion:
+    """A suggestion to load an on-demand command."""
+    command: str
+    reason: str
+    estimated_tokens: int
+    priority: int
+    keywords_matched: List[str]
+
+
+# Default trigger rules mapping keywords to on-demand commands
+DEFAULT_TRIGGER_RULES: List[TriggerRule] = [
+    TriggerRule(
+        command="/patterns",
+        keywords=[
+            "anti-pattern", "antipattern", "bad practice", "avoid",
+            "mistake", "wrong", "should not", "shouldn't",
+            "learned pattern", "code pattern", "confidence",
+            "rule of three", "premature abstraction", "over-engineering"
+        ],
+        description="Anti-patterns, learned patterns, and code patterns",
+        estimated_tokens=1500,
+        priority=1
+    ),
+    TriggerRule(
+        command="/checklist",
+        keywords=[
+            "checklist", "quality", "before pr", "before commit",
+            "verification", "check", "validate", "pre-merge",
+            "lint", "test", "typecheck", "evidence"
+        ],
+        description="Quality gates and implementation checklists",
+        estimated_tokens=1200,
+        priority=1
+    ),
+    TriggerRule(
+        command="/audit",
+        keywords=[
+            "token", "context", "usage", "consumption",
+            "how much", "budget", "waste", "efficiency"
+        ],
+        description="Real-time token consumption analysis",
+        estimated_tokens=800,
+        priority=2
+    ),
+    TriggerRule(
+        command="/explore",
+        keywords=[
+            "explore", "discovery", "investigate", "understand",
+            "how does", "where is", "find", "search"
+        ],
+        description="Discovery phase for new feature work",
+        estimated_tokens=600,
+        priority=2
+    ),
+    TriggerRule(
+        command="/ralph",
+        keywords=[
+            "ralph", "autonomous", "unattended", "overnight",
+            "long running", "migration", "refactor"
+        ],
+        description="Ralph Wiggum autonomous execution mode",
+        estimated_tokens=1000,
+        priority=3
+    ),
+]
+
+
+class ContextOptimizer:
+    """
+    Intelligent context loading optimizer.
+
+    Tracks loaded commands and suggests relevant on-demand loads
+    based on trigger keywords in user prompts.
+    """
+
+    def __init__(self, custom_rules: Optional[List[TriggerRule]] = None):
+        """Initialize the optimizer."""
+        # Copy rules to avoid mutating DEFAULT_TRIGGER_RULES
+        self.rules = list(custom_rules) if custom_rules is not None else list(DEFAULT_TRIGGER_RULES)
+        self._loaded_commands: Set[str] = set()
+        self._session_start = datetime.now()
+        self._suggestion_history: List[LoadSuggestion] = []
+        self._metrics: Optional[Any] = None
+
+        # Try to connect to metrics
+        if METRICS_AVAILABLE:
+            try:
+                self._metrics = get_metrics()
+            except Exception:
+                pass
+
+    def detect_triggers(
+        self,
+        text: str,
+        include_loaded: bool = False
+    ) -> List[LoadSuggestion]:
+        """
+        Detect trigger keywords in text and return load suggestions.
+
+        Args:
+            text: The text to analyze (usually user prompt)
+            include_loaded: If True, include already-loaded commands
+
+        Returns:
+            List of LoadSuggestion sorted by priority
+        """
+        text_lower = text.lower()
+        suggestions: List[LoadSuggestion] = []
+
+        for rule in self.rules:
+            # Skip if already loaded (unless include_loaded)
+            if not include_loaded and rule.command in self._loaded_commands:
+                continue
+
+            # Find matching keywords
+            matched = [kw for kw in rule.keywords if kw in text_lower]
+
+            if matched:
+                suggestions.append(LoadSuggestion(
+                    command=rule.command,
+                    reason=rule.description,
+                    estimated_tokens=rule.estimated_tokens,
+                    priority=rule.priority,
+                    keywords_matched=matched
+                ))
+
+        # Sort by priority (lower = higher priority), then by match count
+        suggestions.sort(key=lambda s: (s.priority, -len(s.keywords_matched)))
+
+        return suggestions
+
+    def mark_loaded(self, command: str, tokens: Optional[int] = None) -> None:
+        """
+        Mark a command as loaded in this session.
+
+        Args:
+            command: The command name (e.g., "/patterns")
+            tokens: Optional token count to record in metrics
+        """
+        # Normalize command name
+        if not command.startswith("/"):
+            command = "/" + command
+
+        self._loaded_commands.add(command)
+
+        # Record in metrics if available
+        if tokens and self._metrics:
+            try:
+                self._metrics.record_component_load(
+                    component_type="command",
+                    component_name=command.lstrip("/"),
+                    tokens=tokens,
+                    source=f"global/commands/{command.lstrip('/')}.md"
+                )
+            except Exception:
+                pass
+
+    def is_loaded(self, command: str) -> bool:
+        """Check if a command has been loaded in this session."""
+        if not command.startswith("/"):
+            command = "/" + command
+        return command in self._loaded_commands
+
+    def get_loaded_commands(self) -> List[str]:
+        """Get list of commands loaded in this session."""
+        return list(self._loaded_commands)
+
+    def get_estimated_savings(self) -> Dict[str, Any]:
+        """
+        Estimate token savings from deferred loading.
+
+        Returns:
+            Dict with savings metrics
+        """
+        total_deferred = sum(
+            rule.estimated_tokens
+            for rule in self.rules
+            if rule.command not in self._loaded_commands
+        )
+
+        total_loaded = sum(
+            rule.estimated_tokens
+            for rule in self.rules
+            if rule.command in self._loaded_commands
+        )
+
+        total_available = sum(rule.estimated_tokens for rule in self.rules)
+
+        return {
+            "total_available_tokens": total_available,
+            "loaded_tokens": total_loaded,
+            "deferred_tokens": total_deferred,
+            "commands_loaded": len(self._loaded_commands),
+            "commands_deferred": len(self.rules) - len(self._loaded_commands),
+            "savings_percent": round(
+                (total_deferred / total_available * 100) if total_available else 0, 1
+            )
+        }
+
+    def format_suggestions(
+        self,
+        suggestions: List[LoadSuggestion],
+        max_suggestions: int = 3
+    ) -> str:
+        """
+        Format load suggestions as a readable message.
+
+        Args:
+            suggestions: List of suggestions to format
+            max_suggestions: Maximum number to include
+
+        Returns:
+            Formatted string for display
+        """
+        if not suggestions:
+            return ""
+
+        lines = ["**Relevant commands available:**"]
+
+        for suggestion in suggestions[:max_suggestions]:
+            priority_icon = {1: "!", 2: "-", 3: "o"}.get(suggestion.priority, "-")
+            lines.append(
+                f"  {priority_icon} `{suggestion.command}` — {suggestion.reason} "
+                f"(~{suggestion.estimated_tokens} tokens)"
+            )
+
+        if len(suggestions) > max_suggestions:
+            lines.append(f"  ... and {len(suggestions) - max_suggestions} more")
+
+        return "\n".join(lines)
+
+    def add_rule(self, rule: TriggerRule) -> None:
+        """Add a custom trigger rule."""
+        self.rules.append(rule)
+
+    def reset_session(self) -> None:
+        """Reset session state (clear loaded commands)."""
+        self._loaded_commands.clear()
+        self._suggestion_history.clear()
+        self._session_start = datetime.now()
+
+
+# Global singleton instance
+_optimizer_instance: Optional[ContextOptimizer] = None
+
+
+def get_optimizer() -> ContextOptimizer:
+    """Get the global ContextOptimizer instance."""
+    global _optimizer_instance
+    if _optimizer_instance is None:
+        _optimizer_instance = ContextOptimizer()
+    return _optimizer_instance
+
+
+def detect_triggers(text: str) -> List[LoadSuggestion]:
+    """Convenience function to detect triggers using global instance."""
+    return get_optimizer().detect_triggers(text)
+
+
+def format_trigger_table() -> str:
+    """
+    Format a compact trigger table for CLAUDE.md.
+
+    Returns a markdown table showing trigger keywords and their commands.
+    """
+    lines = [
+        "| Trigger | Command | Description |",
+        "|---------|---------|-------------|"
+    ]
+
+    for rule in DEFAULT_TRIGGER_RULES:
+        # Show top 3 keywords
+        keywords = ", ".join(rule.keywords[:3])
+        if len(rule.keywords) > 3:
+            keywords += "..."
+        lines.append(f"| {keywords} | `{rule.command}` | {rule.description} |")
+
+    return "\n".join(lines)

package/global/lib/linear_provider.py

@@ -4,15 +4,24 @@ LinearProvider - Linear API adapter for Anvil Framework.
 Wraps the Linear GraphQL API to provide the IssueProvider interface.
 Uses the LINEAR_API_KEY environment variable for authentication.
 
+Features:
+- Smart result filtering for token efficiency (Phase 5)
+- Status-based, priority-based, and date-based filtering
+- Compact mode for reduced token consumption
+
 Usage:
     from linear_provider import LinearProvider
 
     provider = LinearProvider(team_key="ANV")
     issues = provider.list_issues(status=IssueStatus.TODO)
+
+    # Smart filtering for token efficiency
+    issues = provider.list_issues_smart(max_results=10, days_back=7)
 """
 
 import os
-from datetime import datetime, timezone
+from dataclasses import dataclass, field
+from datetime import datetime, timezone, timedelta
 from typing import Optional
 import json
 
@@ -29,6 +38,21 @@ except ImportError:
     from issue_provider import BaseProvider
 
 
+@dataclass
+class FilterOptions:
+    """
+    Smart filtering options for token-efficient Linear queries.
+
+    Used by list_issues_smart() to reduce data returned.
+    """
+    max_results: int = 10
+    days_back: Optional[int] = 7  # Only issues updated in last N days
+    exclude_done: bool = True  # Exclude completed/cancelled
+    exclude_backlog: bool = False  # Exclude backlog items
+    priority_threshold: Optional[Priority] = None  # Only P0-P2, etc.
+    compact_mode: bool = False  # Return minimal fields for display
+
+
 class LinearProvider(BaseProvider):
     """
     Linear API adapter implementing IssueProvider interface.
@@ -128,9 +152,9 @@ class LinearProvider(BaseProvider):
             "Content-Type": "application/json"
         }
 
-        # Cache for state UUIDs (populated on first use)
-        self._state_cache: dict[str, dict] = {}
-        self._state_cache_initialized = False
+        # Cache for state UUIDs per team (populated on first use)
+        # Structure: {team_id: {state_name_lower: state_data}}
+        self._state_cache: dict[str, dict[str, dict]] = {}
 
         # Cache for label UUIDs (populated on first use)
         self._label_cache: dict[str, str] = {}  # name -> id
@@ -205,12 +229,19 @@ class LinearProvider(BaseProvider):
 
         raise ValueError(f"Team not found: {self.team_key}")
 
-    def _ensure_state_cache(self):
-        """Initialize state cache if needed."""
-        if self._state_cache_initialized:
+    def _ensure_state_cache(self, team_id: Optional[str] = None):
+        """Initialize state cache for a team if needed.
+
+        Args:
+            team_id: Team UUID to cache states for. If None, uses provider's team.
+        """
+        if team_id is None:
+            team_id = self._get_team_id()
+
+        # Check if already cached for this team
+        if team_id in self._state_cache:
             return
 
-        team_id = self._get_team_id()
         query = """
         query($teamId: String!) {
           team(id: $teamId) {
@@ -227,22 +258,58 @@ class LinearProvider(BaseProvider):
         result = self._query(query, {"teamId": team_id})
         states = result.get("team", {}).get("states", {}).get("nodes", [])
 
+        # Initialize team's cache
+        self._state_cache[team_id] = {}
         for state in states:
             name_lower = state.get("name", "").lower()
-            self._state_cache[name_lower] = state
+            self._state_cache[team_id][name_lower] = state
+
+    def _get_state_id(self, status: IssueStatus, team_id: Optional[str] = None) -> Optional[str]:
+        """Get Linear state UUID for an IssueStatus.
 
-        self._state_cache_initialized = True
+        Args:
+            status: The IssueStatus to look up.
+            team_id: Team UUID to get state for. If None, uses provider's team.
+
+        Returns:
+            The state UUID, or None if not found.
+        """
+        if team_id is None:
+            team_id = self._get_team_id()
 
-    def _get_state_id(self, status: IssueStatus) -> Optional[str]:
-        """Get Linear state UUID for an IssueStatus."""
-        self._ensure_state_cache()
+        self._ensure_state_cache(team_id)
 
         state_name = self.STATUS_TO_STATE_NAME.get(status, "").lower()
-        if state_name in self._state_cache:
-            return self._state_cache[state_name].get("id")
+        team_states = self._state_cache.get(team_id, {})
+        if state_name in team_states:
+            return team_states[state_name].get("id")
 
         return None
 
+    def _get_issue_team_id(self, identifier: str) -> Optional[str]:
+        """Look up an issue's team ID by identifier.
+
+        Args:
+            identifier: Issue identifier (e.g., "ANV-123").
+
+        Returns:
+            The team UUID, or None if issue not found.
+        """
+        query = """
+        query($id: String!) {
+          issue(id: $id) {
+            team {
+              id
+            }
+          }
+        }
+        """
+        try:
+            result = self._query(query, {"id": identifier})
+            return result.get("issue", {}).get("team", {}).get("id")
+        except Exception:
+            return None
+
     def _ensure_label_cache(self):
         """Initialize label cache if needed."""
         if self._label_cache_initialized:
@@ -416,6 +483,131 @@ class LinearProvider(BaseProvider):
 
         return issues[:limit]
 
+    def list_issues_smart(
+        self,
+        options: Optional[FilterOptions] = None,
+        project: Optional[str] = None
+    ) -> list[Issue]:
+        """
+        List issues with smart filtering for token efficiency.
+
+        This method applies intelligent filtering to reduce the number of
+        issues returned, minimizing token consumption when displaying results.
+
+        Args:
+            options: FilterOptions instance (defaults to sensible settings)
+            project: Optional project filter
+
+        Returns:
+            Filtered list of Issue objects, sorted by relevance.
+        """
+        if options is None:
+            options = FilterOptions()
+
+        # Fetch more than needed to allow for filtering
+        fetch_limit = min(options.max_results * 3, 100)
+        all_issues = self.list_issues(project=project, limit=fetch_limit)
+
+        return self._apply_filters(all_issues, options)
+
+    def _apply_filters(
+        self,
+        issues: list[Issue],
+        options: FilterOptions
+    ) -> list[Issue]:
+        """
+        Apply smart filtering to a list of issues.
+
+        Args:
+            issues: List of issues to filter
+            options: Filtering options
+
+        Returns:
+            Filtered and sorted list of issues
+        """
+        filtered = issues
+
+        # Date-based filtering
+        if options.days_back is not None:
+            cutoff = datetime.now(timezone.utc) - timedelta(days=options.days_back)
+            filtered = [
+                i for i in filtered
+                if i.updated_at and i.updated_at >= cutoff
+            ]
+
+        # Status filtering
+        if options.exclude_done:
+            filtered = [
+                i for i in filtered
+                if i.status not in {IssueStatus.DONE, IssueStatus.CANCELLED}
+            ]
+
+        if options.exclude_backlog:
+            filtered = [
+                i for i in filtered
+                if i.status != IssueStatus.BACKLOG
+            ]
+
+        # Priority filtering
+        if options.priority_threshold:
+            threshold_value = options.priority_threshold.value
+            filtered = [
+                i for i in filtered
+                if i.priority.value <= threshold_value
+            ]
+
+        # Sort by priority (lower = more urgent) then by updated_at (recent first)
+        def sort_key(issue: Issue) -> tuple:
+            priority = issue.priority.value if issue.priority else 999
+            updated = issue.updated_at or datetime.min.replace(tzinfo=timezone.utc)
+            # Negate timestamp for descending order (most recent first)
+            return (priority, -updated.timestamp())
+
+        filtered.sort(key=sort_key)
+
+        # Apply max_results limit
+        return filtered[:options.max_results]
+
+    def get_filtering_stats(
+        self,
+        original_count: int,
+        filtered_count: int,
+        options: FilterOptions
+    ) -> dict:
+        """
+        Get statistics about filtering effectiveness.
+
+        Useful for tracking and optimizing token efficiency.
+
+        Args:
+            original_count: Number of issues before filtering
+            filtered_count: Number of issues after filtering
+            options: The filter options used
+
+        Returns:
+            Dict with filtering statistics
+        """
+        reduction_pct = (
+            ((original_count - filtered_count) / original_count * 100)
+            if original_count > 0 else 0
+        )
+
+        return {
+            "original_count": original_count,
+            "filtered_count": filtered_count,
+            "reduction_percent": round(reduction_pct, 1),
+            "filters_applied": {
+                "days_back": options.days_back,
+                "exclude_done": options.exclude_done,
+                "exclude_backlog": options.exclude_backlog,
+                "priority_threshold": (
+                    options.priority_threshold.name
+                    if options.priority_threshold else None
+                ),
+                "max_results": options.max_results,
+            }
+        }
+
     def get_issue(self, identifier: str) -> Optional[Issue]:
         """Get a single issue by identifier (e.g., ANV-72)."""
         query = """
@@ -593,7 +785,9 @@ class LinearProvider(BaseProvider):
         if priority is not None:
             input_data["priority"] = self.PRIORITY_TO_LINEAR.get(priority, 2)
         if status is not None:
-            state_id = self._get_state_id(status)
+            # Look up issue's team to get correct state UUID (ANV-232)
+            issue_team_id = self._get_issue_team_id(identifier)
+            state_id = self._get_state_id(status, team_id=issue_team_id)
             if state_id:
                 input_data["stateId"] = state_id
         # Handle labels (resolve names to UUIDs)