titan-cli 0.1.0__py3-none-any.whl

titan_plugin_jira/agents/response_parser.py

@@ -0,0 +1,435 @@
+# plugins/titan-plugin-jira/titan_plugin_jira/agents/response_parser.py
+"""
+Robust AI response parser for JiraAgent.
+
+This module provides a generic, robust parsing strategy for AI responses:
+1. Try JSON parsing first (most reliable)
+2. Fall back to regex-based parsing if JSON fails
+3. Provide sensible defaults if both fail
+4. Validate all extracted data
+
+Based on lessons learned from PR #91 (IssueGeneratorAgent).
+"""
+
+import json
+import re
+from typing import Dict, Any, List, Optional, Callable
+from dataclasses import dataclass
+
+
+@dataclass
+class ParseResult:
+    """Result of parsing with metadata."""
+    data: Dict[str, Any]
+    method_used: str  # "json", "regex", or "fallback"
+    success: bool
+    errors: List[str] = None
+
+    def __post_init__(self):
+        if self.errors is None:
+            self.errors = []
+
+
+class AIResponseParser:
+    """
+    Generic parser for AI responses with multiple fallback strategies.
+
+    Parsing strategies (in order of preference):
+    1. JSON - Most reliable, structured format
+    2. Regex - Fallback for text-based responses
+    3. Default - Sensible defaults if all else fails
+
+    Example:
+        parser = AIResponseParser()
+
+        # Define schema
+        schema = {
+            "functional": (list, []),
+            "non_functional": (list, []),
+            "technical_approach": (str, None)
+        }
+
+        # Parse with JSON
+        result = parser.parse_json(content, schema)
+
+        # Or parse with regex patterns
+        patterns = {
+            "functional": r"FUNCTIONAL_REQUIREMENTS:\\s*\\n((?:- .+\\n?)+)",
+            "non_functional": r"NON_FUNCTIONAL_REQUIREMENTS:\\s*\\n((?:- .+\\n?)+)"
+        }
+        result = parser.parse_regex(content, patterns, schema)
+    """
+
+    def __init__(self, strict: bool = False):
+        """
+        Initialize parser.
+
+        Args:
+            strict: If True, raise exceptions on parsing errors.
+                   If False, log warnings and use defaults.
+        """
+        self.strict = strict
+
+    def parse_json(
+        self,
+        content: str,
+        schema: Dict[str, tuple],
+        validate_fn: Optional[Callable] = None
+    ) -> ParseResult:
+        """
+        Parse JSON response with schema validation.
+
+        Args:
+            content: Raw AI response content
+            schema: Dict mapping field names to (type, default) tuples
+                   Example: {"risks": (list, []), "complexity": (str, None)}
+            validate_fn: Optional validation function(data) -> List[str] errors
+
+        Returns:
+            ParseResult with parsed data
+        """
+        try:
+            # Try to find JSON block in content
+            json_match = re.search(r'```json\s*\n(.+?)\n```', content, re.DOTALL)
+            if json_match:
+                json_str = json_match.group(1)
+            else:
+                # Try parsing entire content as JSON
+                json_str = content.strip()
+
+            data = json.loads(json_str)
+
+            # Validate and fill defaults
+            result_data = {}
+            errors = []
+
+            for field, (expected_type, default) in schema.items():
+                if field in data:
+                    value = data[field]
+                    # Type check
+                    if not isinstance(value, expected_type):
+                        errors.append(
+                            f"Field '{field}' has wrong type: "
+                            f"expected {expected_type.__name__}, got {type(value).__name__}"
+                        )
+                        result_data[field] = default
+                    else:
+                        result_data[field] = value
+                else:
+                    # Use default if field missing
+                    result_data[field] = default
+                    if default is None:
+                        errors.append(f"Field '{field}' is missing")
+
+            # Custom validation
+            if validate_fn:
+                validation_errors = validate_fn(result_data)
+                errors.extend(validation_errors)
+
+            # Collect errors but don't log (no logging strategy defined yet)
+
+            return ParseResult(
+                data=result_data,
+                method_used="json",
+                success=len(errors) == 0,
+                errors=errors
+            )
+
+        except json.JSONDecodeError as e:
+            # Return empty result, caller will try fallback
+            return ParseResult(
+                data={field: default for field, (_, default) in schema.items()},
+                method_used="json",
+                success=False,
+                errors=[f"JSON decode error: {e}"]
+            )
+
+    def parse_regex(
+        self,
+        content: str,
+        patterns: Dict[str, str],
+        schema: Dict[str, tuple],
+        list_separator: str = r"\n-\s*"
+    ) -> ParseResult:
+        """
+        Parse text response using regex patterns.
+
+        Args:
+            content: Raw AI response content
+            patterns: Dict mapping field names to regex patterns
+            schema: Dict mapping field names to (type, default) tuples
+            list_separator: Regex pattern for splitting list items
+
+        Returns:
+            ParseResult with parsed data
+        """
+        result_data = {}
+        errors = []
+
+        for field, (expected_type, default) in schema.items():
+            if field not in patterns:
+                # No pattern, use default
+                result_data[field] = default
+                continue
+
+            pattern = patterns[field]
+            match = re.search(pattern, content, re.IGNORECASE | re.DOTALL)
+
+            if not match:
+                # Pattern didn't match, use default
+                result_data[field] = default
+                errors.append(f"Pattern for '{field}' not found in content")
+                continue
+
+            # Extract matched content
+            matched_text = match.group(1).strip()
+
+            # Convert to expected type
+            if expected_type is list:
+                # Split by list separator (e.g., "- item")
+                items = re.split(list_separator, matched_text)
+                items = [item.strip() for item in items if item.strip()]
+                result_data[field] = items
+            elif expected_type is str:
+                result_data[field] = matched_text
+            elif expected_type is int:
+                try:
+                    result_data[field] = int(matched_text)
+                except ValueError:
+                    result_data[field] = default
+                    errors.append(f"Could not convert '{field}' to int: {matched_text}")
+            else:
+                # Unknown type, store as string
+                result_data[field] = matched_text
+
+        return ParseResult(
+            data=result_data,
+            method_used="regex",
+            success=len(errors) == 0,
+            errors=errors
+        )
+
+    def parse_with_fallback(
+        self,
+        content: str,
+        schema: Dict[str, tuple],
+        json_first: bool = True,
+        regex_patterns: Optional[Dict[str, str]] = None,
+        validate_fn: Optional[Callable] = None
+    ) -> ParseResult:
+        """
+        Parse response with automatic fallback strategy.
+
+        Args:
+            content: Raw AI response
+            schema: Field schema
+            json_first: Try JSON before regex
+            regex_patterns: Patterns for regex fallback
+            validate_fn: Optional validation function
+
+        Returns:
+            ParseResult with parsed data using best available method
+        """
+        if json_first:
+            # Try JSON first
+            result = self.parse_json(content, schema, validate_fn)
+            if result.success:
+                return result
+
+            # Fall back to regex
+            if regex_patterns:
+                result = self.parse_regex(content, regex_patterns, schema)
+                if result.success or not result.errors:
+                    return result
+        else:
+            # Try regex first (for legacy text-based responses)
+            if regex_patterns:
+                result = self.parse_regex(content, regex_patterns, schema)
+                if result.success:
+                    return result
+
+            # Fall back to JSON
+            result = self.parse_json(content, schema, validate_fn)
+            if result.success:
+                return result
+
+        # Both failed, return defaults
+        return ParseResult(
+            data={field: default for field, (_, default) in schema.items()},
+            method_used="fallback",
+            success=False,
+            errors=["All parsing strategies failed"]
+        )
+
+
+# ==================== SPECIFIC PARSERS FOR JIRA AGENT ====================
+
+class JiraAgentParser:
+    """
+    Specialized parser for JiraAgent responses.
+
+    Provides pre-configured parsers for all JiraAgent AI operations:
+    - Requirements extraction
+    - Risk analysis
+    - Dependencies detection
+    - Subtasks suggestion
+    """
+
+    def __init__(self, strict: bool = False):
+        self.parser = AIResponseParser(strict=strict)
+
+    def parse_requirements(self, content: str) -> Dict[str, Any]:
+        """
+        Parse requirements extraction response.
+
+        Expected JSON format:
+        {
+            "functional": ["req1", "req2"],
+            "non_functional": ["nfr1", "nfr2"],
+            "acceptance_criteria": ["ac1", "ac2"],
+            "technical_approach": "approach description"
+        }
+
+        Fallback regex patterns for text-based responses.
+        """
+        schema = {
+            "functional": (list, []),
+            "non_functional": (list, []),
+            "acceptance_criteria": (list, []),
+            "technical_approach": (str, None)
+        }
+
+        regex_patterns = {
+            "functional": r'FUNCTIONAL_REQUIREMENTS:\s*\n((?:-\s*.+\n?)+)',
+            "non_functional": r'NON_FUNCTIONAL_REQUIREMENTS:\s*\n((?:-\s*.+\n?)+)',
+            "acceptance_criteria": r'ACCEPTANCE_CRITERIA:\s*\n((?:-\s*.+\n?)+)',
+            "technical_approach": r'TECHNICAL_APPROACH:\s*\n(.+?)(?=\n[A-Z_]+:|$)'
+        }
+
+        result = self.parser.parse_with_fallback(
+            content,
+            schema,
+            json_first=True,
+            regex_patterns=regex_patterns
+        )
+
+        return result.data
+
+    def parse_risks(self, content: str) -> Dict[str, Any]:
+        """
+        Parse risk analysis response.
+
+        Expected JSON format:
+        {
+            "risks": ["risk1", "risk2"],
+            "edge_cases": ["case1", "case2"],
+            "complexity": "Medium",
+            "effort": "3-5 days"
+        }
+        """
+        schema = {
+            "risks": (list, []),
+            "edge_cases": (list, []),
+            "complexity": (str, None),
+            "effort": (str, None)
+        }
+
+        regex_patterns = {
+            "risks": r'RISKS:\s*\n((?:-\s*.+\n?)+)',
+            "edge_cases": r'EDGE_CASES:\s*\n((?:-\s*.+\n?)+)',
+            "complexity": r'COMPLEXITY:\s*(.+)',
+            "effort": r'EFFORT_ESTIMATE:\s*(.+)'
+        }
+
+        result = self.parser.parse_with_fallback(
+            content,
+            schema,
+            json_first=True,
+            regex_patterns=regex_patterns
+        )
+
+        return result.data
+
+    def parse_dependencies(self, content: str) -> Dict[str, Any]:
+        """
+        Parse dependencies detection response.
+
+        Expected JSON format:
+        {
+            "dependencies": ["dep1", "dep2"]
+        }
+        """
+        schema = {
+            "dependencies": (list, [])
+        }
+
+        regex_patterns = {
+            "dependencies": r'DEPENDENCIES:\s*\n((?:-\s*.+\n?)+)'
+        }
+
+        result = self.parser.parse_with_fallback(
+            content,
+            schema,
+            json_first=True,
+            regex_patterns=regex_patterns
+        )
+
+        return result.data
+
+    def parse_subtasks(self, content: str) -> Dict[str, Any]:
+        """
+        Parse subtasks suggestion response.
+
+        Expected JSON format:
+        {
+            "subtasks": [
+                {"summary": "Task 1", "description": "Desc 1"},
+                {"summary": "Task 2", "description": "Desc 2"}
+            ]
+        }
+        """
+        schema = {
+            "subtasks": (list, [])
+        }
+
+        # Try JSON first
+        result = self.parser.parse_json(content, schema)
+
+        if not result.success:
+            # Fallback: manual regex parsing for text-based subtasks
+            subtasks = self._parse_subtasks_regex(content)
+            return {"subtasks": subtasks}
+
+        # Validate subtask structure
+        valid_subtasks = []
+        for subtask in result.data.get("subtasks", []):
+            if isinstance(subtask, dict) and "summary" in subtask:
+                valid_subtasks.append({
+                    "summary": subtask.get("summary", ""),
+                    "description": subtask.get("description", "")
+                })
+
+        return {"subtasks": valid_subtasks}
+
+    def _parse_subtasks_regex(self, content: str) -> List[Dict[str, str]]:
+        """Fallback regex parser for subtasks in text format."""
+        subtasks = []
+        current_subtask = None
+
+        for line in content.split("\n"):
+            line = line.strip()
+
+            if line.startswith("SUBTASK_"):
+                if current_subtask:
+                    subtasks.append(current_subtask)
+                current_subtask = {"summary": "", "description": ""}
+            elif current_subtask:
+                if line.startswith("Summary:"):
+                    current_subtask["summary"] = line.split(":", 1)[1].strip()
+                elif line.startswith("Description:"):
+                    current_subtask["description"] = line.split(":", 1)[1].strip()
+
+        if current_subtask:
+            subtasks.append(current_subtask)
+
+        return subtasks

titan_plugin_jira/agents/token_tracker.py

@@ -0,0 +1,223 @@
+# plugins/titan-plugin-jira/titan_plugin_jira/agents/token_tracker.py
+"""
+Centralized token tracking for JiraAgent.
+
+Addresses PR #74 comment: "Token Tracking Inconsistente"
+Provides consistent, transparent token usage tracking across all AI operations.
+"""
+
+from dataclasses import dataclass
+from typing import Any, Dict, List, Optional
+from enum import Enum
+
+MAX_BUDGET_MULTIPLIER = 10
+
+class OperationType(Enum):
+    """Types of AI operations that consume tokens."""
+    REQUIREMENTS_EXTRACTION = "requirements_extraction"
+    RISK_ANALYSIS = "risk_analysis"
+    DEPENDENCY_DETECTION = "dependency_detection"
+    SUBTASK_SUGGESTION = "subtask_suggestion"
+    COMMENT_GENERATION = "comment_generation"
+    DESCRIPTION_ENHANCEMENT = "description_enhancement"
+    SMART_LABELING = "smart_labeling"
+
+
+@dataclass
+class TokenUsage:
+    """Record of token usage for a single operation."""
+    operation: OperationType
+    tokens_used: int
+    issue_key: Optional[str] = None
+    success: bool = True
+    error: Optional[str] = None
+
+
+@dataclass
+class TokenBudget:
+    """
+    Token budget configuration for different operation types.
+
+    Based on PR #74 comment about hardcoded magic numbers.
+    Centralizes token allocation instead of using `max_tokens // 4` throughout code.
+    """
+    # Base max_tokens from config (e.g., 2000)
+    base_max_tokens: int
+
+    # Multipliers for different operations (0.0 to 1.0)
+    requirements_multiplier: float = 1.0  # Full budget
+    risk_multiplier: float = 1.0  # Full budget
+    dependency_multiplier: float = 0.25  # 1/4 budget (was hardcoded as // 4)
+    subtask_multiplier: float = 1.0  # Full budget
+    comment_multiplier: float = 0.5  # 1/2 budget (was hardcoded as // 2)
+    description_multiplier: float = 1.0  # Full budget
+    labeling_multiplier: float = 0.25  # 1/4 budget
+
+    def get_budget(self, operation: OperationType) -> int:
+        """
+        Get token budget for a specific operation.
+
+        Args:
+            operation: The type of operation
+
+        Returns:
+            Maximum tokens allowed for this operation
+        """
+        multipliers = {
+            OperationType.REQUIREMENTS_EXTRACTION: self.requirements_multiplier,
+            OperationType.RISK_ANALYSIS: self.risk_multiplier,
+            OperationType.DEPENDENCY_DETECTION: self.dependency_multiplier,
+            OperationType.SUBTASK_SUGGESTION: self.subtask_multiplier,
+            OperationType.COMMENT_GENERATION: self.comment_multiplier,
+            OperationType.DESCRIPTION_ENHANCEMENT: self.description_multiplier,
+            OperationType.SMART_LABELING: self.labeling_multiplier,
+        }
+
+        multiplier = multipliers.get(operation, 1.0)
+        return int(self.base_max_tokens * multiplier)
+
+
+class TokenTracker:
+    """
+    Tracks token usage across all AI operations in a session.
+
+    Features:
+    - Consistent tracking across all operations
+    - Budget enforcement
+    - Usage reporting and analytics
+    - Per-operation and total tracking
+    """
+
+    def __init__(self, budget: TokenBudget):
+        """
+        Initialize token tracker.
+
+        Args:
+            budget: Token budget configuration
+        """
+        self.budget = budget
+        self.usage_history: List[TokenUsage] = []
+        self._total_tokens = 0
+
+    def record_usage(
+        self,
+        operation: OperationType,
+        tokens_used: int,
+        issue_key: Optional[str] = None,
+        success: bool = True,
+        error: Optional[str] = None
+    ) -> None:
+        """
+        Record token usage for an operation.
+
+        Args:
+            operation: Type of operation
+            tokens_used: Number of tokens consumed
+            issue_key: Optional issue key being processed
+            success: Whether the operation succeeded
+            error: Optional error message if operation failed
+        """
+        usage = TokenUsage(
+            operation=operation,
+            tokens_used=tokens_used,
+            issue_key=issue_key,
+            success=success,
+            error=error
+        )
+
+        self.usage_history.append(usage)
+        self._total_tokens += tokens_used
+
+    def get_total_tokens(self) -> int:
+        """Get total tokens used across all operations."""
+        return self._total_tokens
+
+    def get_tokens_by_operation(self) -> Dict[OperationType, int]:
+        """
+        Get token usage broken down by operation type.
+
+        Returns:
+            Dict mapping operation type to total tokens used
+        """
+        result = {}
+        for usage in self.usage_history:
+            op_type = usage.operation
+            result[op_type] = result.get(op_type, 0) + usage.tokens_used
+
+        return result
+
+    def get_failed_operations(self) -> List[TokenUsage]:
+        """Get list of operations that failed."""
+        return [u for u in self.usage_history if not u.success]
+
+    def get_summary(self) -> Dict[str, Any]:
+        """
+        Get comprehensive usage summary.
+
+        Returns:
+            Dict with total, by_operation, failed_count, etc.
+        """
+        by_operation = self.get_tokens_by_operation()
+        failed = self.get_failed_operations()
+
+        return {
+            "total_tokens": self._total_tokens,
+            "operation_count": len(self.usage_history),
+            "by_operation": {
+                op.value: tokens for op, tokens in by_operation.items()
+            },
+            "failed_operations": len(failed),
+            "budget_base": self.budget.base_max_tokens,
+            "success_rate": (
+                (len(self.usage_history) - len(failed)) / len(self.usage_history)
+                if self.usage_history else 1.0
+            )
+        }
+
+    def format_summary(self) -> str:
+        """
+        Format usage summary as human-readable string.
+
+        Returns:
+            Formatted summary text
+        """
+        summary = self.get_summary()
+
+        lines = [
+            "Token Usage Summary:",
+            f"  Total Tokens: {summary['total_tokens']}",
+            f"  Operations: {summary['operation_count']}",
+            f"  Success Rate: {summary['success_rate']:.1%}",
+            "",
+            "By Operation:"
+        ]
+
+        for op_name, tokens in summary['by_operation'].items():
+            lines.append(f"  - {op_name}: {tokens} tokens")
+
+        if summary['failed_operations'] > 0:
+            lines.append("")
+            lines.append(f"Failed Operations: {summary['failed_operations']}")
+
+        return "\n".join(lines)
+
+    def check_budget(self, operation: OperationType) -> bool:
+        """
+        Check if there's budget remaining for an operation.
+
+        Args:
+            operation: Operation type to check
+
+        Returns:
+            True if within budget, False otherwise
+        """
+        
+        # For simplicity, just check if we haven't exceeded total budget
+        # Could implement more sophisticated per-operation tracking
+
+        return self._total_tokens < (self.budget.base_max_tokens * MAX_BUDGET_MULTIPLIER)  # Allow 10x for multi-issue analysis
+
+    def reset(self) -> None:
+        """Reset tracker (useful for new analysis session)."""
+        self.usage_history = []
+        self._total_tokens = 0