claude-mpm 5.4.41__py3-none-any.whl → 5.6.23__py3-none-any.whl

claude_mpm/commander/inbox/dedup.py

@@ -0,0 +1,128 @@
+"""Event deduplication logic for inbox system.
+
+Prevents duplicate events within a configurable time window using
+content hashing and time-based expiration.
+"""
+
+import hashlib
+from dataclasses import dataclass
+from datetime import datetime, timedelta, timezone
+from typing import Dict
+
+
+@dataclass
+class DedupEntry:
+    """Deduplication cache entry.
+
+    Tracks when an event was first seen and how many times it's appeared.
+
+    Attributes:
+        key: Unique deduplication key
+        first_seen: When this key was first encountered
+        count: Number of times this key has been seen
+    """
+
+    key: str
+    first_seen: datetime
+    count: int = 1
+
+
+class EventDeduplicator:
+    """Prevent duplicate events within a time window.
+
+    Uses content hashing to detect duplicates and time-based expiration
+    to automatically clean up old entries.
+
+    The deduplication key is constructed from:
+    - Project ID
+    - Event type
+    - Title hash (first 8 chars of MD5)
+
+    Example:
+        >>> dedup = EventDeduplicator(window_seconds=60)
+        >>> dedup.is_duplicate("proj_123", "error", "Connection failed")
+        False  # First occurrence
+        >>> dedup.is_duplicate("proj_123", "error", "Connection failed")
+        True   # Duplicate within 60 seconds
+    """
+
+    def __init__(self, window_seconds: int = 60):
+        """Initialize deduplicator with time window.
+
+        Args:
+            window_seconds: Duration in seconds to consider events as duplicates.
+                           Default is 60 seconds.
+        """
+        self.window = timedelta(seconds=window_seconds)
+        self._seen: Dict[str, DedupEntry] = {}
+
+    def make_key(self, project_id: str, event_type: str, title: str) -> str:
+        """Create deduplication key from event attributes.
+
+        Generates a key in the format: {project_id}:{event_type}:{title_hash}
+
+        Args:
+            project_id: Unique project identifier
+            event_type: Type of event (from EventType enum)
+            title: Event title text
+
+        Returns:
+            Composite key string for deduplication
+
+        Example:
+            >>> dedup = EventDeduplicator()
+            >>> dedup.make_key("proj_123", "error", "Connection failed")
+            'proj_123:error:a1b2c3d4'
+        """
+        title_hash = hashlib.md5(title.encode(), usedforsecurity=False).hexdigest()[:8]
+        return f"{project_id}:{event_type}:{title_hash}"
+
+    def is_duplicate(self, project_id: str, event_type: str, title: str) -> bool:
+        """Check if this event is a duplicate within the window.
+
+        Args:
+            project_id: Unique project identifier
+            event_type: Type of event
+            title: Event title
+
+        Returns:
+            True if this is a duplicate, False if it's new
+
+        Side Effects:
+            - Increments count for duplicates
+            - Creates new entry for new events
+            - Cleans up expired entries
+
+        Example:
+            >>> dedup = EventDeduplicator(window_seconds=60)
+            >>> dedup.is_duplicate("proj_123", "error", "Timeout")
+            False  # First occurrence
+            >>> dedup.is_duplicate("proj_123", "error", "Timeout")
+            True   # Duplicate within window
+        """
+        self._cleanup_expired()
+        key = self.make_key(project_id, event_type, title)
+
+        if key in self._seen:
+            self._seen[key].count += 1
+            return True
+
+        self._seen[key] = DedupEntry(
+            key=key,
+            first_seen=datetime.now(timezone.utc),
+        )
+        return False
+
+    def _cleanup_expired(self) -> None:
+        """Remove entries older than the deduplication window.
+
+        Called automatically before each is_duplicate check to prevent
+        unbounded memory growth.
+
+        Side Effects:
+            Removes all entries where (now - first_seen) > window
+        """
+        now = datetime.now(timezone.utc)
+        expired = [k for k, v in self._seen.items() if now - v.first_seen > self.window]
+        for k in expired:
+            del self._seen[k]

claude_mpm/commander/inbox/inbox.py

@@ -0,0 +1,224 @@
+"""Centralized inbox for MPM Commander.
+
+Aggregates events from all projects with filtering, sorting, and pagination.
+"""
+
+import logging
+from dataclasses import dataclass
+from typing import List, Optional
+
+from ..events.manager import EventManager
+from ..models.events import Event, EventPriority, EventType
+from ..registry import ProjectRegistry
+from .dedup import EventDeduplicator
+from .models import InboxItem
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class InboxCounts:
+    """Count of events by priority.
+
+    Provides quick summary statistics for inbox state.
+
+    Attributes:
+        critical: Count of CRITICAL priority events
+        high: Count of HIGH priority events
+        normal: Count of NORMAL priority events
+        low: Count of LOW priority events
+        info: Count of INFO priority events
+        total: Total count of all events
+    """
+
+    critical: int = 0
+    high: int = 0
+    normal: int = 0
+    low: int = 0
+    info: int = 0
+    total: int = 0
+
+
+class Inbox:
+    """Centralized inbox aggregating events from all projects.
+
+    Provides a unified view of all pending events with:
+    - Multi-level filtering (priority, project, event type)
+    - Pagination support
+    - Priority-based sorting
+    - Project metadata enrichment
+    - Deduplication
+
+    Example:
+        >>> inbox = Inbox(event_manager, project_registry)
+        >>> items = inbox.get_items(limit=10, priority=EventPriority.HIGH)
+        >>> counts = inbox.get_counts()
+        >>> print(f"Total pending: {counts.total}")
+    """
+
+    def __init__(
+        self,
+        event_manager: EventManager,
+        project_registry: ProjectRegistry,
+        dedup_window: int = 60,
+    ):
+        """Initialize inbox with dependencies.
+
+        Args:
+            event_manager: Event lifecycle manager
+            project_registry: Project registration system
+            dedup_window: Deduplication window in seconds (default: 60)
+        """
+        self.events = event_manager
+        self.projects = project_registry
+        self.deduplicator = EventDeduplicator(window_seconds=dedup_window)
+
+    def get_items(
+        self,
+        limit: int = 50,
+        offset: int = 0,
+        priority: Optional[EventPriority] = None,
+        project_id: Optional[str] = None,
+        event_type: Optional[EventType] = None,
+    ) -> List[InboxItem]:
+        """Get inbox items with optional filtering and pagination.
+
+        Applies filters in this order:
+        1. Get all pending events (optionally for specific project)
+        2. Filter by priority if specified
+        3. Filter by event type if specified
+        4. Sort by priority (high to low) then created_at (old to new)
+        5. Paginate with limit and offset
+        6. Enrich with project metadata
+
+        Args:
+            limit: Maximum number of items to return (default: 50)
+            offset: Number of items to skip for pagination (default: 0)
+            priority: Filter to specific priority level (optional)
+            project_id: Filter to specific project (optional)
+            event_type: Filter to specific event type (optional)
+
+        Returns:
+            List of enriched InboxItems, sorted and paginated
+
+        Example:
+            # Get first 20 critical events
+            >>> items = inbox.get_items(limit=20, priority=EventPriority.CRITICAL)
+
+            # Get high-priority errors for specific project
+            >>> items = inbox.get_items(
+            ...     priority=EventPriority.HIGH,
+            ...     project_id="proj_123",
+            ...     event_type=EventType.ERROR
+            ... )
+
+            # Pagination: get items 50-100
+            >>> items = inbox.get_items(limit=50, offset=50)
+        """
+        # Get all pending events (optionally filtered by project)
+        pending = self.events.get_pending(project_id)
+
+        # Filter by priority
+        if priority:
+            pending = [e for e in pending if e.priority == priority]
+
+        # Filter by event type
+        if event_type:
+            pending = [e for e in pending if e.type == event_type]
+
+        # Sort by priority (CRITICAL first) then created_at (oldest first)
+        priority_order = [
+            EventPriority.CRITICAL,
+            EventPriority.HIGH,
+            EventPriority.NORMAL,
+            EventPriority.LOW,
+            EventPriority.INFO,
+        ]
+
+        def sort_key(event: Event):
+            pri_idx = (
+                priority_order.index(event.priority)
+                if event.priority in priority_order
+                else 99
+            )
+            return (pri_idx, event.created_at)
+
+        sorted_events = sorted(pending, key=sort_key)
+
+        # Paginate
+        paginated = sorted_events[offset : offset + limit]
+
+        # Enrich with project metadata
+        items = []
+        for event in paginated:
+            project = self.projects.get(event.project_id)
+            if project:
+                session_runtime = None
+                if event.session_id and event.session_id in project.sessions:
+                    session_runtime = project.sessions[event.session_id].runtime
+
+                items.append(
+                    InboxItem(
+                        event=event,
+                        project_name=project.name,
+                        project_path=project.path,
+                        session_runtime=session_runtime,
+                    )
+                )
+
+        return items
+
+    def get_counts(self, project_id: Optional[str] = None) -> InboxCounts:
+        """Get count of pending events by priority.
+
+        Args:
+            project_id: If provided, only count events for this project
+
+        Returns:
+            InboxCounts with breakdown by priority and total
+
+        Example:
+            >>> counts = inbox.get_counts()
+            >>> print(f"Critical: {counts.critical}, Total: {counts.total}")
+
+            >>> project_counts = inbox.get_counts(project_id="proj_123")
+        """
+        pending = self.events.get_pending(project_id)
+
+        counts = InboxCounts()
+        for event in pending:
+            counts.total += 1
+            if event.priority == EventPriority.CRITICAL:
+                counts.critical += 1
+            elif event.priority == EventPriority.HIGH:
+                counts.high += 1
+            elif event.priority == EventPriority.NORMAL:
+                counts.normal += 1
+            elif event.priority == EventPriority.LOW:
+                counts.low += 1
+            elif event.priority == EventPriority.INFO:
+                counts.info += 1
+
+        return counts
+
+    def should_create_event(
+        self, project_id: str, event_type: EventType, title: str
+    ) -> bool:
+        """Check if event should be created (not a duplicate).
+
+        Uses deduplication to prevent creating duplicate events within
+        the configured time window.
+
+        Args:
+            project_id: Project raising the event
+            event_type: Type of event
+            title: Event title
+
+        Returns:
+            True if event should be created, False if it's a duplicate
+
+        Example:
+            >>> if inbox.should_create_event("proj_123", EventType.ERROR, "Timeout"):
+            ...     event = event_manager.create(...)
+        """
+        return not self.deduplicator.is_duplicate(project_id, event_type.value, title)

claude_mpm/commander/inbox/models.py

@@ -0,0 +1,70 @@
+"""Inbox item model for event display enrichment.
+
+Combines event data with project information for inbox rendering.
+"""
+
+from dataclasses import dataclass
+from datetime import datetime, timedelta, timezone
+from typing import Optional
+
+from ..models.events import Event
+
+
+@dataclass
+class InboxItem:
+    """Enriched event for inbox display.
+
+    Combines Event with project metadata and computed display fields.
+
+    Attributes:
+        event: The underlying event
+        project_name: Human-readable project name
+        project_path: Filesystem path to project
+        session_runtime: Optional runtime identifier for the session
+
+    Example:
+        >>> item = InboxItem(
+        ...     event=event,
+        ...     project_name="My App",
+        ...     project_path="/Users/masa/Projects/my-app",
+        ...     session_runtime="python-agent"
+        ... )
+        >>> item.age_display
+        '5m ago'
+    """
+
+    event: Event
+    project_name: str
+    project_path: str
+    session_runtime: Optional[str] = None
+
+    @property
+    def age(self) -> timedelta:
+        """Time since event was created.
+
+        Returns:
+            Timedelta representing event age
+        """
+        return datetime.now(timezone.utc) - self.event.created_at
+
+    @property
+    def age_display(self) -> str:
+        """Human-readable age string.
+
+        Returns age formatted as:
+        - "Xs ago" for under 60 seconds
+        - "Xm ago" for under 60 minutes
+        - "Xh ago" for under 24 hours
+        - "Xd ago" for 24+ hours
+
+        Returns:
+            Formatted age string (e.g., "5m ago", "2h ago", "3d ago")
+        """
+        seconds = int(self.age.total_seconds())
+        if seconds < 60:
+            return f"{seconds}s ago"
+        if seconds < 3600:
+            return f"{seconds // 60}m ago"
+        if seconds < 86400:
+            return f"{seconds // 3600}h ago"
+        return f"{seconds // 86400}d ago"