monoco-toolkit 0.3.10__py3-none-any.whl → 0.3.12__py3-none-any.whl

monoco/core/watcher/__init__.py

@@ -0,0 +1,57 @@
+"""
+Watcher Module - Layer 1 of the Event Automation Framework.
+
+This module provides file system watching capabilities with event emission.
+It is part of the three-layer architecture:
+- Layer 1: File Watcher (this module)
+- Layer 2: Action Router
+- Layer 3: Action Executor
+
+Example Usage:
+    >>> from monoco.core.watcher import IssueWatcher, WatchConfig
+    >>> from pathlib import Path
+    >>> 
+    >>> config = WatchConfig(
+    ...     path=Path("./Issues"),
+    ...     patterns=["*.md"],
+    ...     recursive=True,
+    ... )
+    >>> watcher = IssueWatcher(config)
+    >>> await watcher.start()
+    >>> # Events are automatically emitted to EventBus
+    >>> await watcher.stop()
+"""
+
+from .base import (
+    ChangeType,
+    FieldChange,
+    FileEvent,
+    FilesystemWatcher,
+    PollingWatcher,
+    WatchdogWatcher,
+    WatchConfig,
+)
+from .issue import IssueWatcher, IssueFileEvent
+from .memo import MemoWatcher, MemoFileEvent
+from .task import TaskWatcher, TaskFileEvent
+from .dropzone import DropzoneWatcher, DropzoneFileEvent
+
+__all__ = [
+    # Base classes
+    "ChangeType",
+    "FieldChange",
+    "FileEvent",
+    "FilesystemWatcher",
+    "PollingWatcher",
+    "WatchdogWatcher",
+    "WatchConfig",
+    # Concrete watchers
+    "IssueWatcher",
+    "IssueFileEvent",
+    "MemoWatcher",
+    "MemoFileEvent",
+    "TaskWatcher",
+    "TaskFileEvent",
+    "DropzoneWatcher",
+    "DropzoneFileEvent",
+]

monoco/core/watcher/base.py

@@ -0,0 +1,365 @@
+"""
+Base abstractions for FilesystemWatcher - Layer 1 of the event automation framework.
+
+This module defines the core abstractions for file system event watching:
+- FilesystemWatcher: Abstract base class for all file watchers
+- FileEvent: Dataclass representing a file system event
+- WatchConfig: Configuration for file watching
+- ChangeType: Enum for types of file changes
+"""
+
+from __future__ import annotations
+
+import asyncio
+import inspect
+import logging
+from abc import ABC, abstractmethod
+from dataclasses import dataclass, field
+from datetime import datetime
+from enum import Enum, auto
+from pathlib import Path
+from typing import Any, Callable, Dict, List, Optional, Set, Union
+
+from monoco.core.scheduler import AgentEventType, EventBus, event_bus
+
+logger = logging.getLogger(__name__)
+
+
+class ChangeType(Enum):
+    """Types of file system changes."""
+    CREATED = "created"
+    MODIFIED = "modified"
+    DELETED = "deleted"
+    MOVED = "moved"
+    RENAMED = "renamed"
+
+
+@dataclass
+class FileEvent:
+    """
+    Represents a file system event.
+    
+    Attributes:
+        path: Path to the file or directory
+        change_type: Type of change (created, modified, deleted, etc.)
+        watcher_name: Name of the watcher that emitted this event
+        old_path: Original path for move/rename events
+        old_content: Previous content hash or snapshot (for content tracking)
+        new_content: Current content hash or snapshot
+        metadata: Additional event metadata
+        timestamp: Event timestamp
+    """
+    path: Path
+    change_type: ChangeType
+    watcher_name: str
+    old_path: Optional[Path] = None
+    old_content: Optional[str] = None
+    new_content: Optional[str] = None
+    metadata: Dict[str, Any] = field(default_factory=dict)
+    timestamp: datetime = field(default_factory=datetime.now)
+    
+    def to_agent_event_type(self) -> Optional[AgentEventType]:
+        """Convert FileEvent to AgentEventType if applicable."""
+        # This will be overridden by specific watchers
+        return None
+    
+    def to_payload(self) -> Dict[str, Any]:
+        """Convert to payload dict for EventBus."""
+        return {
+            "path": str(self.path),
+            "change_type": self.change_type.value,
+            "watcher_name": self.watcher_name,
+            "old_path": str(self.old_path) if self.old_path else None,
+            "old_content": self.old_content,
+            "new_content": self.new_content,
+            "metadata": self.metadata,
+            "timestamp": self.timestamp.isoformat(),
+        }
+
+
+@dataclass
+class WatchConfig:
+    """
+    Configuration for file watching.
+    
+    Attributes:
+        path: Path to watch (file or directory)
+        patterns: Glob patterns to match (e.g., "*.md", "*.yaml")
+        exclude_patterns: Patterns to exclude
+        recursive: Whether to watch recursively
+        field_extractors: Optional field extractors for content parsing
+        poll_interval: Polling interval in seconds (for polling-based watchers)
+    """
+    path: Path
+    patterns: List[str] = field(default_factory=lambda: ["*"])
+    exclude_patterns: List[str] = field(default_factory=list)
+    recursive: bool = True
+    field_extractors: Dict[str, Callable[[str], Any]] = field(default_factory=dict)
+    poll_interval: float = 5.0
+    
+    def should_watch(self, file_path: Path) -> bool:
+        """Check if a file should be watched based on patterns."""
+        # Check exclude patterns first
+        for pattern in self.exclude_patterns:
+            if file_path.match(pattern):
+                return False
+        
+        # Check include patterns
+        for pattern in self.patterns:
+            if file_path.match(pattern):
+                return True
+        
+        return False
+
+
+@dataclass
+class FieldChange:
+    """Represents a change in a specific field."""
+    field_name: str
+    old_value: Any
+    new_value: Any
+    change_type: ChangeType = ChangeType.MODIFIED
+
+
+class FilesystemWatcher(ABC):
+    """
+    Abstract base class for file system watchers (Layer 1).
+    
+    Responsibilities:
+    - Monitor file system changes
+    - Emit FileEvent objects
+    - Integrate with EventBus for event publishing
+    
+    Lifecycle:
+        1. Create watcher with config
+        2. Call start() to begin watching
+        3. File events are emitted via emit() or callbacks
+        4. Call stop() to cleanup
+    
+    Example:
+        >>> config = WatchConfig(path=Path("./Issues"), patterns=["*.md"])
+        >>> watcher = IssueWatcher(config)
+        >>> await watcher.start()
+        >>> # Events are automatically emitted to EventBus
+        >>> await watcher.stop()
+    """
+    
+    def __init__(
+        self,
+        config: WatchConfig,
+        event_bus: Optional[EventBus] = None,
+        name: Optional[str] = None,
+    ):
+        self.config = config
+        self.event_bus = event_bus or event_bus
+        self.name = name or self.__class__.__name__
+        self._running = False
+        self._callbacks: List[Callable[[FileEvent], None]] = []
+        self._state_cache: Dict[str, Any] = {}  # For tracking state changes
+    
+    @abstractmethod
+    async def start(self) -> None:
+        """Start watching the file system."""
+        pass
+    
+    @abstractmethod
+    async def stop(self) -> None:
+        """Stop watching and cleanup resources."""
+        pass
+    
+    def is_running(self) -> bool:
+        """Check if the watcher is currently running."""
+        return self._running
+    
+    def register_callback(self, callback: Callable[[FileEvent], None]) -> None:
+        """Register a callback for file events."""
+        self._callbacks.append(callback)
+    
+    def unregister_callback(self, callback: Callable[[FileEvent], None]) -> None:
+        """Unregister a callback."""
+        if callback in self._callbacks:
+            self._callbacks.remove(callback)
+    
+    async def emit(self, event: FileEvent) -> None:
+        """
+        Emit a file event to all registered callbacks and EventBus.
+        
+        Args:
+            event: The FileEvent to emit
+        """
+        # Call local callbacks
+        for callback in self._callbacks:
+            try:
+                if inspect.iscoroutinefunction(callback):
+                    await callback(event)
+                else:
+                    callback(event)
+            except Exception as e:
+                logger.error(f"Error in callback for {event}: {e}")
+        
+        # Publish to EventBus if available
+        if self.event_bus:
+            try:
+                agent_event_type = event.to_agent_event_type()
+                if agent_event_type:
+                    await self.event_bus.publish(
+                        agent_event_type,
+                        event.to_payload(),
+                        source=f"watcher.{self.name}",
+                    )
+            except Exception as e:
+                logger.error(f"Error publishing to EventBus: {e}")
+    
+    def _get_file_hash(self, file_path: Path) -> Optional[str]:
+        """Get a hash of file content for change detection."""
+        try:
+            import hashlib
+            content = file_path.read_text(encoding="utf-8")
+            return hashlib.md5(content.encode()).hexdigest()
+        except Exception:
+            return None
+    
+    def _read_file_content(self, file_path: Path) -> Optional[str]:
+        """Read file content safely."""
+        try:
+            return file_path.read_text(encoding="utf-8")
+        except Exception as e:
+            logger.debug(f"Could not read {file_path}: {e}")
+            return None
+    
+    def get_stats(self) -> Dict[str, Any]:
+        """Get watcher statistics."""
+        return {
+            "name": self.name,
+            "running": self._running,
+            "config": {
+                "path": str(self.config.path),
+                "patterns": self.config.patterns,
+                "recursive": self.config.recursive,
+            },
+            "callbacks": len(self._callbacks),
+        }
+
+
+class PollingWatcher(FilesystemWatcher):
+    """
+    Base class for polling-based file watchers.
+    
+    Useful for watching specific files or when native file system
+    events are not available/reliable.
+    """
+    
+    def __init__(
+        self,
+        config: WatchConfig,
+        event_bus: Optional[EventBus] = None,
+        name: Optional[str] = None,
+    ):
+        super().__init__(config, event_bus, name)
+        self._poll_task: Optional[asyncio.Task] = None
+        self._file_states: Dict[Path, Dict[str, Any]] = {}
+    
+    async def start(self) -> None:
+        """Start polling loop."""
+        if self._running:
+            return
+        
+        self._running = True
+        self._poll_task = asyncio.create_task(self._poll_loop())
+        logger.info(f"Started polling watcher: {self.name}")
+    
+    async def stop(self) -> None:
+        """Stop polling loop."""
+        if not self._running:
+            return
+        
+        self._running = False
+        
+        if self._poll_task:
+            self._poll_task.cancel()
+            try:
+                await self._poll_task
+            except asyncio.CancelledError:
+                pass
+            self._poll_task = None
+        
+        logger.info(f"Stopped polling watcher: {self.name}")
+    
+    async def _poll_loop(self) -> None:
+        """Main polling loop."""
+        while self._running:
+            try:
+                await self._check_changes()
+                await asyncio.sleep(self.config.poll_interval)
+            except asyncio.CancelledError:
+                break
+            except Exception as e:
+                logger.error(f"Error in poll loop: {e}")
+                await asyncio.sleep(self.config.poll_interval)
+    
+    @abstractmethod
+    async def _check_changes(self) -> None:
+        """Check for changes - implement in subclass."""
+        pass
+    
+    def _scan_files(self) -> Dict[Path, Dict[str, Any]]:
+        """Scan watched path and return file states."""
+        states = {}
+        
+        if self.config.path.is_file():
+            files = [self.config.path]
+        else:
+            if self.config.recursive:
+                files = list(self.config.path.rglob("*"))
+            else:
+                files = list(self.config.path.glob("*"))
+        
+        for file_path in files:
+            if not file_path.is_file():
+                continue
+            
+            if not self.config.should_watch(file_path):
+                continue
+            
+            try:
+                stat = file_path.stat()
+                content = self._read_file_content(file_path)
+                states[file_path] = {
+                    "mtime": stat.st_mtime,
+                    "size": stat.st_size,
+                    "content": content,
+                    "hash": self._get_file_hash(file_path) if content else None,
+                }
+            except Exception as e:
+                logger.debug(f"Could not stat {file_path}: {e}")
+        
+        return states
+
+
+class WatchdogWatcher(FilesystemWatcher):
+    """
+    Base class for watchdog-based file watchers.
+    
+    Uses the watchdog library for efficient native file system events.
+    """
+    
+    def __init__(
+        self,
+        config: WatchConfig,
+        event_bus: Optional[EventBus] = None,
+        name: Optional[str] = None,
+    ):
+        super().__init__(config, event_bus, name)
+        self._observer: Optional[Any] = None
+    
+    def _should_process(self, file_path: Path) -> bool:
+        """Check if a file should be processed."""
+        # Skip hidden files
+        if file_path.name.startswith("."):
+            return False
+        
+        # Skip temporary files
+        if file_path.suffix in (".tmp", ".temp", ".part", ".swp", "~"):
+            return False
+        
+        return self.config.should_watch(file_path)

monoco/core/watcher/dropzone.py

@@ -0,0 +1,152 @@
+"""
+DropzoneWatcher - Adapter for the existing dropzone watcher.
+
+Part of Layer 1 (File Watcher) in the event automation framework.
+Wraps the existing ingestion watcher to fit the FilesystemWatcher interface.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+from pathlib import Path
+from typing import Any, Callable, Dict, Optional
+
+from monoco.core.scheduler import AgentEventType, EventBus, event_bus
+from monoco.core.ingestion.watcher import (
+    DropzoneWatcher as LegacyDropzoneWatcher,
+    IngestionEvent,
+    IngestionEventType,
+)
+from monoco.core.artifacts.manager import ArtifactManager
+
+from .base import (
+    ChangeType,
+    FileEvent,
+    FilesystemWatcher,
+    WatchConfig,
+)
+
+logger = logging.getLogger(__name__)
+
+
+class DropzoneFileEvent(FileEvent):
+    """FileEvent specific to Dropzone."""
+    
+    def __init__(
+        self,
+        path: Path,
+        change_type: ChangeType,
+        ingestion_event_type: IngestionEventType,
+        artifact_id: Optional[str] = None,
+        **kwargs,
+    ):
+        super().__init__(
+            path=path,
+            change_type=change_type,
+            watcher_name="DropzoneWatcher",
+            **kwargs,
+        )
+        self.ingestion_event_type = ingestion_event_type
+        self.artifact_id = artifact_id
+    
+    def to_agent_event_type(self) -> Optional[AgentEventType]:
+        """Dropzone events don't map directly to agent events."""
+        return None
+    
+    def to_payload(self) -> Dict[str, Any]:
+        """Convert to payload with Dropzone-specific fields."""
+        payload = super().to_payload()
+        payload["ingestion_event_type"] = self.ingestion_event_type.value
+        payload["artifact_id"] = self.artifact_id
+        return payload
+
+
+class DropzoneWatcher(FilesystemWatcher):
+    """
+    Adapter for the existing DropzoneWatcher.
+    
+    Wraps the legacy ingestion watcher to provide a unified interface
+    while maintaining backward compatibility.
+    
+    Example:
+        >>> from monoco.core.artifacts.manager import ArtifactManager
+        >>> artifact_manager = ArtifactManager()
+        >>> config = WatchConfig(path=Path("./.monoco/dropzone"))
+        >>> watcher = DropzoneWatcher(config, artifact_manager)
+        >>> await watcher.start()
+    """
+    
+    def __init__(
+        self,
+        config: WatchConfig,
+        artifact_manager: ArtifactManager,
+        event_bus: Optional[EventBus] = None,
+        name: str = "DropzoneWatcher",
+    ):
+        super().__init__(config, event_bus, name)
+        self.artifact_manager = artifact_manager
+        
+        # Create legacy watcher
+        self._legacy_watcher = LegacyDropzoneWatcher(
+            dropzone_path=config.path,
+            artifact_manager=artifact_manager,
+            process_existing=False,
+        )
+        
+        # Set up event forwarding
+        self._legacy_watcher.set_event_callback(self._on_ingestion_event)
+    
+    async def start(self) -> None:
+        """Start watching the dropzone."""
+        if self._running:
+            return
+        
+        self._legacy_watcher.start()
+        self._running = True
+        logger.info(f"Started DropzoneWatcher: {self.config.path}")
+    
+    async def stop(self) -> None:
+        """Stop watching the dropzone."""
+        if not self._running:
+            return
+        
+        self._legacy_watcher.stop()
+        self._running = False
+        logger.info(f"Stopped DropzoneWatcher: {self.config.path}")
+    
+    def _on_ingestion_event(self, event: IngestionEvent) -> None:
+        """Handle ingestion events from legacy watcher."""
+        # Map ingestion event type to change type
+        change_type_map = {
+            IngestionEventType.FILE_DETECTED: ChangeType.CREATED,
+            IngestionEventType.CONVERSION_STARTED: ChangeType.MODIFIED,
+            IngestionEventType.CONVERSION_COMPLETED: ChangeType.MODIFIED,
+            IngestionEventType.CONVERSION_FAILED: ChangeType.MODIFIED,
+            IngestionEventType.ARTIFACT_REGISTERED: ChangeType.MODIFIED,
+        }
+        
+        change_type = change_type_map.get(event.event_type, ChangeType.MODIFIED)
+        
+        # Create unified event
+        file_event = DropzoneFileEvent(
+            path=event.file_path,
+            change_type=change_type,
+            ingestion_event_type=event.event_type,
+            artifact_id=event.artifact_id,
+            metadata={
+                "task_id": event.task_id,
+                "error_message": event.error_message,
+                **event.metadata,
+            },
+        )
+        
+        # Emit synchronously (called from sync context)
+        asyncio.create_task(self.emit(file_event))
+    
+    def get_stats(self) -> Dict[str, Any]:
+        """Get watcher statistics."""
+        stats = super().get_stats()
+        legacy_stats = self._legacy_watcher.get_stats()
+        stats.update(legacy_stats)
+        return stats