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

mcp_ticketer/analysis/similarity.py

@@ -0,0 +1,224 @@
+"""Ticket similarity detection using TF-IDF and fuzzy matching.
+
+This module provides similarity analysis between tickets to detect:
+- Duplicate tickets that should be merged
+- Related tickets that should be linked
+- Similar work that could be consolidated
+
+Uses TF-IDF vectorization with cosine similarity for content analysis,
+and fuzzy string matching for title comparison.
+"""
+
+from typing import TYPE_CHECKING
+
+from pydantic import BaseModel
+from rapidfuzz import fuzz
+from sklearn.feature_extraction.text import TfidfVectorizer
+from sklearn.metrics.pairwise import cosine_similarity
+
+if TYPE_CHECKING:
+    from ..core.models import Task
+
+
+class SimilarityResult(BaseModel):
+    """Result of similarity analysis between two tickets.
+
+    Attributes:
+        ticket1_id: ID of first ticket
+        ticket1_title: Title of first ticket
+        ticket2_id: ID of second ticket
+        ticket2_title: Title of second ticket
+        similarity_score: Overall similarity score (0.0-1.0)
+        similarity_reasons: List of reasons for similarity
+        suggested_action: Recommended action (merge, link, ignore)
+        confidence: Confidence in the similarity (0.0-1.0)
+
+    """
+
+    ticket1_id: str
+    ticket1_title: str
+    ticket2_id: str
+    ticket2_title: str
+    similarity_score: float  # 0.0-1.0
+    similarity_reasons: list[str]
+    suggested_action: str  # "merge", "link", "ignore"
+    confidence: float
+
+
+class TicketSimilarityAnalyzer:
+    """Analyzes tickets to find similar/duplicate entries.
+
+    Uses a combination of TF-IDF vectorization on titles and descriptions,
+    plus fuzzy string matching on titles to identify similar tickets.
+
+    Attributes:
+        threshold: Minimum similarity score to report (0.0-1.0)
+        title_weight: Weight given to title similarity (0.0-1.0)
+        description_weight: Weight given to description similarity (0.0-1.0)
+
+    """
+
+    def __init__(
+        self,
+        threshold: float = 0.75,
+        title_weight: float = 0.7,
+        description_weight: float = 0.3,
+    ):
+        """Initialize the similarity analyzer.
+
+        Args:
+            threshold: Minimum similarity score to report (default: 0.75)
+            title_weight: Weight for title similarity (default: 0.7)
+            description_weight: Weight for description similarity (default: 0.3)
+
+        """
+        self.threshold = threshold
+        self.title_weight = title_weight
+        self.description_weight = description_weight
+
+    def find_similar_tickets(
+        self,
+        tickets: list["Task"],
+        target_ticket: "Task | None" = None,
+        limit: int = 10,
+    ) -> list[SimilarityResult]:
+        """Find similar tickets using TF-IDF + cosine similarity.
+
+        Args:
+            tickets: List of tickets to analyze
+            target_ticket: Find similar to this ticket (if None, find all pairs)
+            limit: Maximum results to return
+
+        Returns:
+            List of similarity results above threshold, sorted by score
+
+        """
+        if len(tickets) < 2:
+            return []
+
+        # Build corpus for TF-IDF
+        titles = [t.title for t in tickets]
+        descriptions = [t.description or "" for t in tickets]
+
+        # TF-IDF on titles
+        title_vectorizer = TfidfVectorizer(
+            min_df=1, stop_words="english", lowercase=True, ngram_range=(1, 2)
+        )
+        title_matrix = title_vectorizer.fit_transform(titles)
+
+        # TF-IDF on descriptions (if available)
+        desc_matrix = None
+        if any(descriptions):
+            desc_vectorizer = TfidfVectorizer(
+                min_df=1, stop_words="english", lowercase=True, ngram_range=(1, 2)
+            )
+            desc_matrix = desc_vectorizer.fit_transform(descriptions)
+
+        # Compute similarity matrices
+        title_similarity = cosine_similarity(title_matrix)
+
+        if desc_matrix is not None:
+            desc_similarity = cosine_similarity(desc_matrix)
+            # Weighted combination
+            combined_similarity = (
+                self.title_weight * title_similarity
+                + self.description_weight * desc_similarity
+            )
+        else:
+            # Only use title similarity if no descriptions
+            combined_similarity = title_similarity
+
+        results = []
+
+        if target_ticket:
+            # Find similar to specific ticket
+            target_idx = next(
+                (i for i, t in enumerate(tickets) if t.id == target_ticket.id),
+                None,
+            )
+            if target_idx is None:
+                return []
+
+            for i, ticket in enumerate(tickets):
+                if i == target_idx:
+                    continue
+
+                score = float(combined_similarity[target_idx, i])
+                if score >= self.threshold:
+                    results.append(self._create_result(target_ticket, ticket, score))
+        else:
+            # Find all similar pairs
+            for i in range(len(tickets)):
+                for j in range(i + 1, len(tickets)):
+                    score = float(combined_similarity[i, j])
+                    if score >= self.threshold:
+                        results.append(
+                            self._create_result(tickets[i], tickets[j], score)
+                        )
+
+        # Sort by score and limit
+        results.sort(key=lambda x: x.similarity_score, reverse=True)
+        return results[:limit]
+
+    def _create_result(
+        self,
+        ticket1: "Task",
+        ticket2: "Task",
+        score: float,
+    ) -> SimilarityResult:
+        """Create similarity result with analysis.
+
+        Args:
+            ticket1: First ticket
+            ticket2: Second ticket
+            score: Similarity score
+
+        Returns:
+            SimilarityResult with detailed analysis
+
+        """
+        reasons = []
+
+        # Title similarity using fuzzy matching
+        title_sim = fuzz.ratio(ticket1.title, ticket2.title) / 100.0
+        if title_sim > 0.8:
+            reasons.append("very_similar_titles")
+        elif title_sim > 0.6:
+            reasons.append("similar_titles")
+
+        # Tag overlap
+        tags1 = set(ticket1.tags or [])
+        tags2 = set(ticket2.tags or [])
+        if tags1 and tags2:
+            overlap = len(tags1 & tags2) / len(tags1 | tags2)
+            if overlap > 0.5:
+                reasons.append(f"tag_overlap_{int(overlap*100)}%")
+
+        # Same state
+        if ticket1.state == ticket2.state:
+            reasons.append("same_state")
+
+        # Same assignee
+        assignee1 = getattr(ticket1, "assignee", None)
+        assignee2 = getattr(ticket2, "assignee", None)
+        if assignee1 and assignee2 and assignee1 == assignee2:
+            reasons.append("same_assignee")
+
+        # Determine action
+        if score > 0.9:
+            action = "merge"  # Very likely duplicates
+        elif score > 0.75:
+            action = "link"  # Related, should be linked
+        else:
+            action = "ignore"  # Low confidence
+
+        return SimilarityResult(
+            ticket1_id=ticket1.id or "unknown",
+            ticket1_title=ticket1.title,
+            ticket2_id=ticket2.id or "unknown",
+            ticket2_title=ticket2.title,
+            similarity_score=score,
+            similarity_reasons=reasons,
+            suggested_action=action,
+            confidence=score,
+        )

mcp_ticketer/analysis/staleness.py

@@ -0,0 +1,266 @@
+"""Stale ticket detection based on age and activity.
+
+This module identifies tickets that may need closing or review based on:
+- Age: How long since the ticket was created
+- Inactivity: How long since the last update
+- State: Tickets in certain states (open, waiting, blocked)
+- Priority: Lower priority tickets are more likely to be stale
+
+The staleness score combines these factors to identify candidates for cleanup.
+"""
+
+from datetime import datetime
+from typing import TYPE_CHECKING
+
+from pydantic import BaseModel
+
+if TYPE_CHECKING:
+    from ..core.models import Task, TicketState
+
+
+class StalenessResult(BaseModel):
+    """Result of staleness analysis for a ticket.
+
+    Attributes:
+        ticket_id: ID of the stale ticket
+        ticket_title: Title of the stale ticket
+        ticket_state: Current state of the ticket
+        age_days: Days since ticket was created
+        days_since_update: Days since last update
+        days_since_comment: Days since last comment (if available)
+        staleness_score: Overall staleness score (0.0-1.0, higher = staler)
+        suggested_action: Recommended action (close, review, keep)
+        reason: Human-readable explanation
+
+    """
+
+    ticket_id: str
+    ticket_title: str
+    ticket_state: str
+    age_days: int
+    days_since_update: int
+    days_since_comment: int | None
+    staleness_score: float  # 0.0-1.0
+    suggested_action: str  # "close", "review", "keep"
+    reason: str
+
+
+class StaleTicketDetector:
+    """Detects stale tickets based on age and activity.
+
+    Analyzes tickets to find those that are old, inactive, and may be
+    candidates for closing or review. Uses configurable thresholds for
+    age and activity, along with state and priority factors.
+
+    Attributes:
+        age_threshold: Minimum age in days to consider
+        activity_threshold: Days without activity to consider stale
+        check_states: List of states to check for staleness
+
+    """
+
+    def __init__(
+        self,
+        age_threshold_days: int = 90,
+        activity_threshold_days: int = 30,
+        check_states: list["TicketState"] | None = None,
+    ):
+        """Initialize the stale ticket detector.
+
+        Args:
+            age_threshold_days: Minimum age to consider (default: 90)
+            activity_threshold_days: Days without activity (default: 30)
+            check_states: Ticket states to check (default: open, waiting, blocked)
+
+        """
+        from ..core.models import TicketState
+
+        self.age_threshold = age_threshold_days
+        self.activity_threshold = activity_threshold_days
+        self.check_states = check_states or [
+            TicketState.OPEN,
+            TicketState.WAITING,
+            TicketState.BLOCKED,
+        ]
+
+    def find_stale_tickets(
+        self,
+        tickets: list["Task"],
+        limit: int = 50,
+    ) -> list[StalenessResult]:
+        """Find stale tickets that may need attention.
+
+        Args:
+            tickets: List of tickets to analyze
+            limit: Maximum results
+
+        Returns:
+            List of staleness results, sorted by staleness score
+
+        """
+        now = datetime.now()
+        results = []
+
+        for ticket in tickets:
+            # Skip tickets not in check_states
+            if ticket.state not in self.check_states:
+                continue
+
+            # Calculate metrics
+            age_days = self._days_since(ticket.created_at, now)
+            days_since_update = self._days_since(ticket.updated_at, now)
+
+            # Check staleness criteria
+            is_old = age_days > self.age_threshold
+            is_inactive = days_since_update > self.activity_threshold
+
+            if is_old and is_inactive:
+                staleness_score = self._calculate_staleness_score(
+                    age_days, days_since_update, ticket
+                )
+
+                result = StalenessResult(
+                    ticket_id=ticket.id or "unknown",
+                    ticket_title=ticket.title,
+                    ticket_state=(
+                        ticket.state.value
+                        if hasattr(ticket.state, "value")
+                        else str(ticket.state)
+                    ),
+                    age_days=age_days,
+                    days_since_update=days_since_update,
+                    days_since_comment=None,  # Can be enhanced with comment data
+                    staleness_score=staleness_score,
+                    suggested_action=self._suggest_action(staleness_score),
+                    reason=self._build_reason(age_days, days_since_update, ticket),
+                )
+                results.append(result)
+
+        # Sort by staleness score
+        results.sort(key=lambda x: x.staleness_score, reverse=True)
+        return results[:limit]
+
+    def _days_since(self, dt: datetime | None, now: datetime) -> int:
+        """Calculate days since a datetime.
+
+        Args:
+            dt: Datetime to calculate from
+            now: Current datetime
+
+        Returns:
+            Number of days since dt (0 if dt is None)
+
+        """
+        if dt is None:
+            return 0
+        # Handle timezone-aware and naive datetimes
+        if dt.tzinfo is not None and now.tzinfo is None:
+            now = now.replace(tzinfo=dt.tzinfo)
+        elif dt.tzinfo is None and now.tzinfo is not None:
+            dt = dt.replace(tzinfo=now.tzinfo)
+        return (now - dt).days
+
+    def _calculate_staleness_score(
+        self,
+        age_days: int,
+        days_since_update: int,
+        ticket: "Task",
+    ) -> float:
+        """Calculate staleness score (0.0-1.0, higher = staler).
+
+        Args:
+            age_days: Days since creation
+            days_since_update: Days since last update
+            ticket: The ticket being analyzed
+
+        Returns:
+            Staleness score between 0.0 and 1.0
+
+        """
+        from ..core.models import Priority, TicketState
+
+        # Base score from age and inactivity
+        age_factor = min(age_days / 365, 1.0)  # Normalize to 1 year
+        activity_factor = min(days_since_update / 180, 1.0)  # Normalize to 6 months
+
+        base_score = (age_factor + activity_factor) / 2
+
+        # Priority adjustment (low priority = more stale)
+        priority_weights = {
+            Priority.CRITICAL: 0.0,
+            Priority.HIGH: 0.3,
+            Priority.MEDIUM: 0.7,
+            Priority.LOW: 1.0,
+        }
+        priority_factor = priority_weights.get(ticket.priority, 0.5)
+
+        # State adjustment
+        state_weights = {
+            TicketState.BLOCKED: 0.8,  # Blocked tickets are very stale
+            TicketState.WAITING: 0.9,  # Waiting tickets are very stale
+            TicketState.OPEN: 0.6,
+        }
+        state_factor = state_weights.get(ticket.state, 0.5)
+
+        # Weighted combination
+        final_score = base_score * 0.5 + priority_factor * 0.3 + state_factor * 0.2
+
+        return min(final_score, 1.0)
+
+    def _suggest_action(self, score: float) -> str:
+        """Suggest action based on staleness score.
+
+        Args:
+            score: Staleness score
+
+        Returns:
+            Suggested action string
+
+        """
+        if score > 0.8:
+            return "close"  # Very stale, likely won't be done
+        elif score > 0.6:
+            return "review"  # Moderately stale, needs review
+        else:
+            return "keep"  # Still relevant
+
+    def _build_reason(
+        self,
+        age_days: int,
+        days_since_update: int,
+        ticket: "Task",
+    ) -> str:
+        """Build human-readable reason string.
+
+        Args:
+            age_days: Days since creation
+            days_since_update: Days since last update
+            ticket: The ticket being analyzed
+
+        Returns:
+            Human-readable explanation
+
+        """
+        from ..core.models import Priority, TicketState
+
+        reasons = []
+
+        if age_days > 365:
+            reasons.append(f"created {age_days} days ago")
+        elif age_days > self.age_threshold:
+            reasons.append(f"old ({age_days} days)")
+
+        if days_since_update > 180:
+            reasons.append(f"no updates for {days_since_update} days")
+        elif days_since_update > self.activity_threshold:
+            reasons.append(f"inactive for {days_since_update} days")
+
+        if ticket.state == TicketState.BLOCKED:
+            reasons.append("blocked state")
+        elif ticket.state == TicketState.WAITING:
+            reasons.append("waiting state")
+
+        if ticket.priority == Priority.LOW:
+            reasons.append("low priority")
+
+        return ", ".join(reasons)

mcp_ticketer/automation/__init__.py

@@ -0,0 +1,11 @@
+"""Automation features for MCP Ticketer.
+
+This module provides automated workflows including:
+- Automatic project status updates on ticket transitions
+- Real-time epic/project health monitoring
+- Automated summaries and recommendations
+"""
+
+from .project_updates import AutoProjectUpdateManager
+
+__all__ = ["AutoProjectUpdateManager"]