mcp-ticketer 0.12.0__py3-none-any.whl → 2.0.1__py3-none-any.whl

mcp_ticketer/core/priority_matcher.py

@@ -0,0 +1,463 @@
+"""Semantic priority matcher for natural language ticket priority inputs.
+
+This module provides intelligent priority matching that accepts natural language inputs
+and resolves them to universal Priority values with confidence scoring.
+
+Features:
+- Comprehensive synonym dictionary (20+ synonyms per priority)
+- Multi-stage matching pipeline (exact → synonym → fuzzy)
+- Confidence scoring with thresholds
+- Support for all 4 universal priorities
+- Natural language understanding
+
+Design Decision: Multi-Stage Matching Pipeline
+----------------------------------------------
+The matcher uses a cascading approach to maximize accuracy while maintaining
+flexibility:
+
+1. Exact Match: Direct priority name match (confidence: 1.0)
+2. Synonym Match: Pre-defined synonym lookup (confidence: 0.95)
+3. Fuzzy Match: Levenshtein distance with thresholds (confidence: 0.70-0.95)
+
+This approach ensures high confidence for common inputs while gracefully handling
+typos and variations.
+
+Performance Considerations:
+- Average match time: <5ms (target: <10ms)
+- Synonym lookup: O(1) with dict hashing
+- Fuzzy matching: O(n) where n = number of priorities (4)
+- Memory footprint: <500KB for matcher instance
+
+Example:
+    >>> matcher = SemanticPriorityMatcher()
+    >>> result = matcher.match_priority("urgent")
+    >>> print(f"{result.priority.value} (confidence: {result.confidence})")
+    critical (confidence: 0.95)
+
+    >>> result = matcher.match_priority("asap")
+    >>> print(f"{result.priority.value} (confidence: {result.confidence})")
+    critical (confidence: 0.95)
+
+    >>> suggestions = matcher.suggest_priorities("important", top_n=3)
+    >>> for s in suggestions:
+    ...     print(f"{s.priority.value}: {s.confidence}")
+    high: 0.95
+    critical: 0.65
+
+Ticket Reference: ISS-0002 - Add semantic priority matching for natural language inputs
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+try:
+    from rapidfuzz import fuzz
+
+    FUZZY_AVAILABLE = True
+except ImportError:
+    FUZZY_AVAILABLE = False
+
+from .models import Priority
+
+
+@dataclass
+class PriorityMatchResult:
+    """Result of a priority matching operation.
+
+    Attributes:
+        priority: Matched Priority
+        confidence: Confidence score (0.0-1.0)
+        match_type: Type of match used (exact, synonym, fuzzy)
+        original_input: Original user input string
+        suggestions: Alternative matches for ambiguous inputs
+
+    """
+
+    priority: Priority
+    confidence: float
+    match_type: str
+    original_input: str
+    suggestions: list[PriorityMatchResult] | None = None
+
+    def is_high_confidence(self) -> bool:
+        """Check if confidence is high enough for auto-apply."""
+        return self.confidence >= 0.90
+
+    def is_medium_confidence(self) -> bool:
+        """Check if confidence is medium (needs confirmation)."""
+        return 0.70 <= self.confidence < 0.90
+
+    def is_low_confidence(self) -> bool:
+        """Check if confidence is too low (ambiguous)."""
+        return self.confidence < 0.70
+
+
+class SemanticPriorityMatcher:
+    """Intelligent priority matcher with natural language support.
+
+    Provides comprehensive synonym matching, fuzzy matching, and confidence
+    scoring for ticket priority assignment.
+
+    The synonym dictionary includes 20+ synonyms across all 4 universal priorities,
+    covering common variations, typos, and platform-specific terminology.
+
+    Ticket Reference: ISS-0002
+    """
+
+    # Comprehensive synonym dictionary for all universal priorities
+    PRIORITY_SYNONYMS: dict[Priority, list[str]] = {
+        Priority.CRITICAL: [
+            "critical",
+            "urgent",
+            "asap",
+            "as soon as possible",
+            "emergency",
+            "blocker",
+            "blocking",
+            "show stopper",
+            "show-stopper",
+            "showstopper",
+            "highest",
+            "p0",
+            "p-0",
+            "priority 0",
+            "needs immediate attention",
+            "immediate attention",
+            "very urgent",
+            "right now",
+            "drop everything",
+            "top priority",
+            "mission critical",
+            "business critical",
+            "sev 0",
+            "sev0",
+            "severity 0",
+            "must have",
+        ],
+        Priority.HIGH: [
+            "high",
+            "important",
+            "soon",
+            "needs attention",
+            "p1",
+            "p-1",
+            "priority 1",
+            "high priority",
+            "should do",
+            "should have",
+            "significant",
+            "pressing",
+            "time sensitive",
+            "time-sensitive",
+            "sev 1",
+            "sev1",
+            "severity 1",
+            "major",
+            "escalated",
+            "higher",
+            "elevated",
+        ],
+        Priority.MEDIUM: [
+            "medium",
+            "normal",
+            "standard",
+            "regular",
+            "moderate",
+            "average",
+            "default",
+            "typical",
+            "p2",
+            "p-2",
+            "priority 2",
+            "medium priority",
+            "could have",
+            "sev 2",
+            "sev2",
+            "severity 2",
+            "routine",
+            "ordinary",
+        ],
+        Priority.LOW: [
+            "low",
+            "minor",
+            "whenever",
+            "low priority",
+            "not urgent",
+            "nice to have",
+            "nice-to-have",
+            "backlog",
+            "someday",
+            "if time permits",
+            "when possible",
+            "optional",
+            "can wait",
+            "lowest",
+            "p3",
+            "p-3",
+            "priority 3",
+            "trivial",
+            "cosmetic",
+            "sev 3",
+            "sev3",
+            "severity 3",
+            "won't have",
+            "wont have",
+        ],
+    }
+
+    # Confidence thresholds
+    CONFIDENCE_HIGH = 0.90
+    CONFIDENCE_MEDIUM = 0.70
+    FUZZY_THRESHOLD_HIGH = 90
+    FUZZY_THRESHOLD_MEDIUM = 70
+
+    def __init__(self) -> None:
+        """Initialize the semantic priority matcher.
+
+        Creates reverse lookup dictionary for O(1) synonym matching.
+        """
+        # Build reverse lookup: synonym -> (priority, is_exact)
+        self._synonym_to_priority: dict[str, tuple[Priority, bool]] = {}
+
+        for priority in Priority:
+            # Add exact priority value
+            self._synonym_to_priority[priority.value.lower()] = (priority, True)
+
+            # Add all synonyms
+            for synonym in self.PRIORITY_SYNONYMS.get(priority, []):
+                self._synonym_to_priority[synonym.lower()] = (priority, False)
+
+    def match_priority(
+        self,
+        user_input: str,
+        adapter_priorities: list[str] | None = None,
+    ) -> PriorityMatchResult:
+        """Match user input to universal priority with confidence score.
+
+        Uses multi-stage matching pipeline:
+        1. Exact match against priority values
+        2. Synonym lookup
+        3. Fuzzy matching with Levenshtein distance
+
+        Args:
+            user_input: Natural language priority input from user
+            adapter_priorities: Optional list of adapter-specific priority names
+
+        Returns:
+            PriorityMatchResult with matched priority and confidence score
+
+        Example:
+            >>> matcher = SemanticPriorityMatcher()
+            >>> result = matcher.match_priority("urgent")
+            >>> print(f"{result.priority.value}: {result.confidence}")
+            critical: 0.95
+
+            >>> result = matcher.match_priority("criticl")  # typo
+            >>> print(f"{result.priority.value}: {result.confidence}")
+            critical: 0.85
+
+        Ticket Reference: ISS-0002
+        """
+        if not user_input:
+            # Default to MEDIUM for empty input
+            return PriorityMatchResult(
+                priority=Priority.MEDIUM,
+                confidence=0.5,
+                match_type="default",
+                original_input=user_input,
+            )
+
+        # Normalize input
+        normalized = user_input.strip().lower()
+
+        # Handle whitespace-only input (after normalization)
+        if not normalized:
+            return PriorityMatchResult(
+                priority=Priority.MEDIUM,
+                confidence=0.5,
+                match_type="default",
+                original_input=user_input,
+            )
+
+        # Stage 1: Exact match
+        exact_result = self._exact_match(normalized)
+        if exact_result:
+            return exact_result
+
+        # Stage 2: Synonym match
+        synonym_result = self._synonym_match(normalized)
+        if synonym_result:
+            return synonym_result
+
+        # Stage 3: Fuzzy match
+        fuzzy_result = self._fuzzy_match(normalized)
+        if fuzzy_result:
+            return fuzzy_result
+
+        # No good match found - return suggestions
+        suggestions = self.suggest_priorities(user_input, top_n=3)
+        return PriorityMatchResult(
+            priority=suggestions[0].priority if suggestions else Priority.MEDIUM,
+            confidence=suggestions[0].confidence if suggestions else 0.5,
+            match_type="fallback",
+            original_input=user_input,
+            suggestions=suggestions,
+        )
+
+    def suggest_priorities(
+        self,
+        user_input: str,
+        top_n: int = 3,
+    ) -> list[PriorityMatchResult]:
+        """Return top N priority suggestions for ambiguous inputs.
+
+        Uses fuzzy matching to rank all possible priorities by similarity.
+        Useful for providing user with multiple options when confidence is low.
+
+        Args:
+            user_input: Natural language priority input
+            top_n: Number of suggestions to return (default: 3)
+
+        Returns:
+            List of PriorityMatchResult sorted by confidence (highest first)
+
+        Example:
+            >>> matcher = SemanticPriorityMatcher()
+            >>> suggestions = matcher.suggest_priorities("importnt", top_n=3)
+            >>> for s in suggestions:
+            ...     print(f"{s.priority.value}: {s.confidence:.2f}")
+            high: 0.85
+            medium: 0.45
+            critical: 0.42
+
+        Ticket Reference: ISS-0002
+        """
+        if not FUZZY_AVAILABLE:
+            # Without fuzzy matching, return all priorities with low confidence
+            return [
+                PriorityMatchResult(
+                    priority=priority,
+                    confidence=0.5,
+                    match_type="suggestion",
+                    original_input=user_input,
+                )
+                for priority in Priority
+            ][:top_n]
+
+        normalized = user_input.strip().lower()
+        suggestions: list[tuple[Priority, float, str]] = []
+
+        # Calculate similarity for each priority and its synonyms
+        for priority in Priority:
+            # Check priority value
+            priority_similarity = fuzz.ratio(normalized, priority.value.lower())
+            max_similarity = priority_similarity
+            match_text = priority.value
+
+            # Check synonyms
+            for synonym in self.PRIORITY_SYNONYMS.get(priority, []):
+                similarity = fuzz.ratio(normalized, synonym.lower())
+                if similarity > max_similarity:
+                    max_similarity = similarity
+                    match_text = synonym
+
+            # Convert similarity to confidence (0-100 → 0.0-1.0)
+            confidence = max_similarity / 100.0
+            suggestions.append((priority, confidence, match_text))
+
+        # Sort by confidence descending
+        suggestions.sort(key=lambda x: x[1], reverse=True)
+
+        # Convert to PriorityMatchResult
+        return [
+            PriorityMatchResult(
+                priority=priority,
+                confidence=conf,
+                match_type="suggestion",
+                original_input=user_input,
+            )
+            for priority, conf, _ in suggestions[:top_n]
+        ]
+
+    def _exact_match(self, normalized_input: str) -> PriorityMatchResult | None:
+        """Match exact priority value."""
+        for priority in Priority:
+            if normalized_input == priority.value.lower():
+                return PriorityMatchResult(
+                    priority=priority,
+                    confidence=1.0,
+                    match_type="exact",
+                    original_input=normalized_input,
+                )
+        return None
+
+    def _synonym_match(self, normalized_input: str) -> PriorityMatchResult | None:
+        """Match using synonym dictionary."""
+        if normalized_input in self._synonym_to_priority:
+            priority, is_exact = self._synonym_to_priority[normalized_input]
+            return PriorityMatchResult(
+                priority=priority,
+                confidence=1.0 if is_exact else 0.95,
+                match_type="exact" if is_exact else "synonym",
+                original_input=normalized_input,
+            )
+        return None
+
+    def _fuzzy_match(self, normalized_input: str) -> PriorityMatchResult | None:
+        """Match using fuzzy string matching."""
+        if not FUZZY_AVAILABLE:
+            return None
+
+        best_match: tuple[Priority, float, str] | None = None
+
+        for priority in Priority:
+            # Check priority value
+            priority_similarity = fuzz.ratio(normalized_input, priority.value.lower())
+
+            if priority_similarity >= self.FUZZY_THRESHOLD_MEDIUM:
+                if best_match is None or priority_similarity > best_match[1]:
+                    best_match = (priority, priority_similarity, "priority_value")
+
+            # Check synonyms
+            for synonym in self.PRIORITY_SYNONYMS.get(priority, []):
+                similarity = fuzz.ratio(normalized_input, synonym.lower())
+                if similarity >= self.FUZZY_THRESHOLD_MEDIUM:
+                    if best_match is None or similarity > best_match[1]:
+                        best_match = (priority, similarity, "synonym")
+
+        if best_match:
+            priority, similarity, match_source = best_match
+
+            # Calculate confidence based on similarity
+            if similarity >= self.FUZZY_THRESHOLD_HIGH:
+                confidence = 0.85 + (similarity - self.FUZZY_THRESHOLD_HIGH) / 100.0
+            else:
+                confidence = 0.70 + (similarity - self.FUZZY_THRESHOLD_MEDIUM) / 200.0
+
+            return PriorityMatchResult(
+                priority=priority,
+                confidence=min(confidence, 0.95),  # Cap at 0.95
+                match_type="fuzzy",
+                original_input=normalized_input,
+            )
+
+        return None
+
+
+# Singleton instance for convenience
+_default_matcher: SemanticPriorityMatcher | None = None
+
+
+def get_priority_matcher() -> SemanticPriorityMatcher:
+    """Get the default priority matcher instance.
+
+    Returns:
+        Singleton SemanticPriorityMatcher instance
+
+    Ticket Reference: ISS-0002
+    """
+    global _default_matcher
+    if _default_matcher is None:
+        _default_matcher = SemanticPriorityMatcher()
+    return _default_matcher

mcp_ticketer/core/project_config.py

@@ -167,7 +167,14 @@ class HybridConfig:
 
 @dataclass
 class TicketerConfig:
-    """Complete ticketer configuration with hierarchical resolution."""
+    """Complete ticketer configuration with hierarchical resolution.
+
+    Supports URL parsing for default_project field:
+    - Linear URLs: https://linear.app/workspace/project/project-slug-abc123
+    - JIRA URLs: https://company.atlassian.net/browse/PROJ-123
+    - GitHub URLs: https://github.com/owner/repo/projects/1
+    - Plain IDs: PROJ-123, abc-123, 1 (backward compatible)
+    """
 
     default_adapter: str = "aitrackdown"
     project_configs: dict[str, ProjectConfig] = field(default_factory=dict)
@@ -176,8 +183,56 @@ class TicketerConfig:
 
     # Default values for ticket operations
     default_user: str | None = None  # Default assignee (user_id or email)
-    default_project: str | None = None  # Default project/epic ID
+    default_project: str | None = None  # Default project/epic ID (supports URLs)
     default_epic: str | None = None  # Alias for default_project (backward compat)
+    default_tags: list[str] | None = None  # Default tags for new tickets
+    default_team: str | None = None  # Default team ID/key for multi-team platforms
+    default_cycle: str | None = None  # Default sprint/cycle ID for timeline scoping
+    assignment_labels: list[str] | None = None  # Labels indicating ticket assignment
+
+    # Automatic project updates configuration (1M-315)
+    auto_project_updates: dict[str, Any] | None = None  # Auto update settings
+
+    def __post_init__(self):
+        """Normalize default_project if it's a URL."""
+        if self.default_project:
+            self.default_project = self._normalize_project_id(self.default_project)
+        if self.default_epic:
+            self.default_epic = self._normalize_project_id(self.default_epic)
+
+    def _normalize_project_id(self, value: str) -> str:
+        """Normalize project ID by extracting from URL if needed.
+
+        Args:
+            value: Project ID or URL
+
+        Returns:
+            Normalized project ID (plain ID, not URL)
+
+        Examples:
+            >>> config._normalize_project_id("PROJ-123")
+            'PROJ-123'
+            >>> config._normalize_project_id("https://linear.app/team/project/abc-123")
+            'abc-123'
+
+        """
+        from .url_parser import is_url, normalize_project_id
+
+        try:
+            # If it's a URL, use auto-detection (don't rely on default_adapter)
+            # This allows users to paste URLs from any platform
+            if is_url(value):
+                normalized = normalize_project_id(value, adapter_type=None)
+            else:
+                # For plain IDs, just return as-is
+                normalized = normalize_project_id(value, self.default_adapter)
+
+            logger.debug(f"Normalized '{value}' to '{normalized}'")
+            return normalized
+        except Exception as e:
+            # If normalization fails, log warning but keep original value
+            logger.warning(f"Failed to normalize project ID '{value}': {e}")
+            return value
 
     def to_dict(self) -> dict[str, Any]:
         """Convert to dictionary for JSON serialization."""
@@ -198,6 +253,16 @@ class TicketerConfig:
             result["default_project"] = self.default_project
         if self.default_epic is not None:
             result["default_epic"] = self.default_epic
+        if self.default_tags is not None:
+            result["default_tags"] = self.default_tags
+        if self.default_team is not None:
+            result["default_team"] = self.default_team
+        if self.default_cycle is not None:
+            result["default_cycle"] = self.default_cycle
+        if self.assignment_labels is not None:
+            result["assignment_labels"] = self.assignment_labels
+        if self.auto_project_updates is not None:
+            result["auto_project_updates"] = self.auto_project_updates
         return result
 
     @classmethod
@@ -228,6 +293,11 @@ class TicketerConfig:
             default_user=data.get("default_user"),
             default_project=data.get("default_project"),
             default_epic=data.get("default_epic"),
+            default_tags=data.get("default_tags"),
+            default_team=data.get("default_team"),
+            default_cycle=data.get("default_cycle"),
+            assignment_labels=data.get("assignment_labels"),
+            auto_project_updates=data.get("auto_project_updates"),
         )
 
 
@@ -238,21 +308,69 @@ class ConfigValidator:
     def validate_linear_config(config: dict[str, Any]) -> tuple[bool, str | None]:
         """Validate Linear adapter configuration.
 
+        Args:
+            config: Linear configuration dictionary
+
         Returns:
             Tuple of (is_valid, error_message)
 
         """
+        import logging
+        import re
+
+        logger = logging.getLogger(__name__)
+
         required = ["api_key"]
-        for field in required:
-            if field not in config or not config[field]:
-                return False, f"Linear config missing required field: {field}"
+        missing_fields = []
+
+        for field_name in required:
+            if field_name not in config or not config[field_name]:
+                missing_fields.append(field_name)
+
+        if missing_fields:
+            return (
+                False,
+                f"Linear config missing required fields: {', '.join(missing_fields)}",
+            )
 
-        # Require either team_key or team_id (team_id is preferred)
-        if not config.get("team_key") and not config.get("team_id"):
+        # Require either team_key or team_id (team_key is preferred)
+        has_team_key = config.get("team_key") and config["team_key"].strip()
+        has_team_id = config.get("team_id") and config["team_id"].strip()
+
+        if not has_team_key and not has_team_id:
             return (
                 False,
-                "Linear config requires either team_key (short key like 'BTA') or team_id (UUID)",
+                "Linear config requires either team_key (short key like 'ENG') or team_id (UUID)",
+            )
+
+        # Validate team_id format if provided (should be UUID)
+        if has_team_id:
+            team_id = config["team_id"]
+            uuid_pattern = re.compile(
+                r"^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$",
+                re.IGNORECASE,
+            )
+
+            if not uuid_pattern.match(team_id):
+                # Not a UUID - could be a team_key mistakenly stored as team_id
+                logger.warning(
+                    f"team_id '{team_id}' is not a UUID format. "
+                    f"It will be treated as team_key and resolved at runtime."
+                )
+                # Move it to team_key if team_key is empty
+                if not has_team_key:
+                    config["team_key"] = team_id
+                    del config["team_id"]
+                    logger.info(f"Moved non-UUID team_id to team_key: {team_id}")
+
+        # Validate user_email format if provided
+        if config.get("user_email"):
+            email = config["user_email"]
+            email_pattern = re.compile(
+                r"^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}$"
             )
+            if not email_pattern.match(email):
+                return False, f"Invalid email format for user_email: {email}"
 
         return True, None
 
@@ -279,9 +397,9 @@ class ConfigValidator:
 
         # Otherwise need explicit owner and repo
         required = ["owner", "repo"]
-        for field in required:
-            if field not in config or not config[field]:
-                return False, f"GitHub config missing required field: {field}"
+        for field_name in required:
+            if field_name not in config or not config[field_name]:
+                return False, f"GitHub config missing required field: {field_name}"
 
         return True, None
 
@@ -294,9 +412,9 @@ class ConfigValidator:
 
         """
         required = ["server", "email", "api_token"]
-        for field in required:
-            if field not in config or not config[field]:
-                return False, f"JIRA config missing required field: {field}"
+        for field_name in required:
+            if field_name not in config or not config[field_name]:
+                return False, f"JIRA config missing required field: {field_name}"
 
         # Validate server URL format
         server = config["server"]