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

monoco/core/automation/__init__.py

@@ -0,0 +1,51 @@
+"""
+Automation Module - Event-driven automation framework.
+
+This module provides:
+- YAML/JSON configuration parsing
+- Trigger configuration management
+- Field change detection
+- Independent Event Handlers for Agent collaboration (FEAT-0162)
+
+Architecture: No Workflow or Orchestration. Each handler is an independent,
+stateless microservice that responds to specific events. Workflow emerges
+from the natural interaction of handlers.
+"""
+
+from .config import (
+    TriggerConfig,
+    AutomationConfig,
+    load_automation_config,
+)
+from .field_watcher import (
+    YAMLFrontMatterExtractor,
+    FieldWatcher,
+    FieldCondition,
+)
+from .handlers import (
+    TaskFileHandler,
+    IssueStageHandler,
+    MemoThresholdHandler,
+    PRCreatedHandler,
+    start_all_handlers,
+    stop_all_handlers,
+)
+
+__all__ = [
+    # Config
+    "TriggerConfig",
+    "AutomationConfig",
+    "load_automation_config",
+    # Field watching
+    "YAMLFrontMatterExtractor",
+    "FieldWatcher",
+    "FieldCondition",
+    # Independent Event Handlers (FEAT-0162)
+    "TaskFileHandler",
+    "IssueStageHandler",
+    "MemoThresholdHandler",
+    "PRCreatedHandler",
+    # Convenience functions
+    "start_all_handlers",
+    "stop_all_handlers",
+]

monoco/core/automation/config.py

@@ -0,0 +1,338 @@
+"""
+Automation Configuration - YAML/JSON configuration for triggers.
+
+Part of the Event Automation Framework.
+Provides configuration schema and loading for automation triggers.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+from dataclasses import dataclass, field as dataclass_field
+from pathlib import Path
+from typing import Any, Dict, List, Optional, Union
+
+import yaml
+
+from monoco.core.scheduler import AgentEventType
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class ActionConfig:
+    """Configuration for an action."""
+    type: str
+    params: Dict[str, Any] = dataclass_field(default_factory=dict)
+    
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> "ActionConfig":
+        """Create from dict."""
+        return cls(
+            type=data.get("type", ""),
+            params=data.get("params", {}),
+        )
+
+
+@dataclass
+class TriggerConfig:
+    """
+    Configuration for a trigger.
+    
+    Attributes:
+        name: Unique trigger name
+        watcher: Watcher type (IssueWatcher, MemoWatcher, etc.)
+        event_type: Event type to listen for
+        condition: Optional condition expression
+        field: Optional field to watch (for field-level triggers)
+        actions: List of actions to execute
+        enabled: Whether trigger is enabled
+    """
+    name: str
+    watcher: str
+    event_type: Optional[str] = None
+    condition: Optional[str] = None
+    field: Optional[str] = None
+    actions: List[ActionConfig] = dataclass_field(default_factory=list)
+    enabled: bool = True
+    priority: int = 0
+    
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> "TriggerConfig":
+        """Create from dict."""
+        actions = [
+            ActionConfig.from_dict(a) if isinstance(a, dict) else ActionConfig(type=a)
+            for a in data.get("actions", [])
+        ]
+        
+        return cls(
+            name=data.get("name", "unnamed"),
+            watcher=data.get("watcher", ""),
+            event_type=data.get("event_type"),
+            condition=data.get("condition"),
+            field=data.get("field"),
+            actions=actions,
+            enabled=data.get("enabled", True),
+            priority=data.get("priority", 0),
+        )
+    
+    def to_agent_event_type(self) -> Optional[AgentEventType]:
+        """Convert event_type string to AgentEventType."""
+        if not self.event_type:
+            return None
+        
+        try:
+            return AgentEventType(self.event_type)
+        except ValueError:
+            # Try to map common patterns
+            mapping = {
+                "issue.created": AgentEventType.ISSUE_CREATED,
+                "issue.updated": AgentEventType.ISSUE_UPDATED,
+                "issue.stage_changed": AgentEventType.ISSUE_STAGE_CHANGED,
+                "issue.status_changed": AgentEventType.ISSUE_STATUS_CHANGED,
+                "memo.created": AgentEventType.MEMO_CREATED,
+                "memo.threshold": AgentEventType.MEMO_THRESHOLD,
+                "session.completed": AgentEventType.SESSION_COMPLETED,
+                "session.failed": AgentEventType.SESSION_FAILED,
+                "pr.created": AgentEventType.PR_CREATED,
+            }
+            return mapping.get(self.event_type)
+
+
+@dataclass
+class AutomationConfig:
+    """
+    Complete automation configuration.
+    
+    Attributes:
+        version: Configuration version
+        triggers: List of trigger configurations
+        settings: Global settings
+    """
+    version: str = "1.0"
+    triggers: List[TriggerConfig] = dataclass_field(default_factory=list)
+    settings: Dict[str, Any] = dataclass_field(default_factory=dict)
+    
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> "AutomationConfig":
+        """Create from dict."""
+        triggers = [
+            TriggerConfig.from_dict(t)
+            for t in data.get("triggers", [])
+        ]
+        
+        return cls(
+            version=data.get("version", "1.0"),
+            triggers=triggers,
+            settings=data.get("settings", {}),
+        )
+    
+    @classmethod
+    def from_yaml(cls, yaml_content: str) -> "AutomationConfig":
+        """Load from YAML string."""
+        data = yaml.safe_load(yaml_content)
+        return cls.from_dict(data or {})
+    
+    @classmethod
+    def from_json(cls, json_content: str) -> "AutomationConfig":
+        """Load from JSON string."""
+        data = json.loads(json_content)
+        return cls.from_dict(data)
+    
+    def to_yaml(self) -> str:
+        """Export to YAML string."""
+        data = {
+            "version": self.version,
+            "triggers": [
+                {
+                    "name": t.name,
+                    "watcher": t.watcher,
+                    "event_type": t.event_type,
+                    "condition": t.condition,
+                    "field": t.field,
+                    "actions": [
+                        {"type": a.type, "params": a.params}
+                        for a in t.actions
+                    ],
+                    "enabled": t.enabled,
+                    "priority": t.priority,
+                }
+                for t in self.triggers
+            ],
+            "settings": self.settings,
+        }
+        return yaml.dump(data, default_flow_style=False, sort_keys=False)
+    
+    def to_json(self) -> str:
+        """Export to JSON string."""
+        data = {
+            "version": self.version,
+            "triggers": [
+                {
+                    "name": t.name,
+                    "watcher": t.watcher,
+                    "event_type": t.event_type,
+                    "condition": t.condition,
+                    "field": t.field,
+                    "actions": [
+                        {"type": a.type, "params": a.params}
+                        for a in t.actions
+                    ],
+                    "enabled": t.enabled,
+                    "priority": t.priority,
+                }
+                for t in self.triggers
+            ],
+            "settings": self.settings,
+        }
+        return json.dumps(data, indent=2)
+    
+    def get_enabled_triggers(self) -> List[TriggerConfig]:
+        """Get all enabled triggers."""
+        return [t for t in self.triggers if t.enabled]
+    
+    def get_trigger(self, name: str) -> Optional[TriggerConfig]:
+        """Get trigger by name."""
+        for trigger in self.triggers:
+            if trigger.name == name:
+                return trigger
+        return None
+    
+    def add_trigger(self, trigger: TriggerConfig) -> None:
+        """Add a trigger."""
+        # Remove existing trigger with same name
+        self.triggers = [t for t in self.triggers if t.name != trigger.name]
+        self.triggers.append(trigger)
+    
+    def remove_trigger(self, name: str) -> bool:
+        """Remove a trigger by name."""
+        original_count = len(self.triggers)
+        self.triggers = [t for t in self.triggers if t.name != name]
+        return len(self.triggers) < original_count
+
+
+def load_automation_config(
+    path: Union[str, Path],
+    create_default: bool = False,
+) -> AutomationConfig:
+    """
+    Load automation configuration from file.
+    
+    Supports .yaml, .yml, and .json files.
+    
+    Args:
+        path: Path to configuration file
+        create_default: If True and file doesn't exist, create default config
+        
+    Returns:
+        AutomationConfig instance
+    """
+    path = Path(path)
+    
+    if not path.exists():
+        if create_default:
+            default_config = create_default_config()
+            path.write_text(default_config.to_yaml())
+            logger.info(f"Created default automation config at {path}")
+            return default_config
+        else:
+            logger.warning(f"Config file not found: {path}")
+            return AutomationConfig()
+    
+    content = path.read_text(encoding="utf-8")
+    
+    if path.suffix in (".yaml", ".yml"):
+        return AutomationConfig.from_yaml(content)
+    elif path.suffix == ".json":
+        return AutomationConfig.from_json(content)
+    else:
+        # Try YAML first, then JSON
+        try:
+            return AutomationConfig.from_yaml(content)
+        except yaml.YAMLError:
+            return AutomationConfig.from_json(content)
+
+
+def create_default_config() -> AutomationConfig:
+    """Create a default automation configuration."""
+    return AutomationConfig(
+        version="1.0",
+        triggers=[
+            TriggerConfig(
+                name="memo_threshold",
+                watcher="MemoWatcher",
+                event_type="memo.threshold",
+                condition="pending_count >= 5",
+                actions=[
+                    ActionConfig(
+                        type="SpawnAgentAction",
+                        params={"role": "Architect"},
+                    ),
+                ],
+            ),
+            TriggerConfig(
+                name="issue_doing",
+                watcher="IssueWatcher",
+                event_type="issue.stage_changed",
+                field="stage",
+                condition="value == 'doing'",
+                actions=[
+                    ActionConfig(
+                        type="SpawnAgentAction",
+                        params={"role": "Engineer"},
+                    ),
+                ],
+            ),
+            TriggerConfig(
+                name="issue_completed",
+                watcher="IssueWatcher",
+                event_type="issue.stage_changed",
+                field="stage",
+                condition="value == 'done'",
+                actions=[
+                    ActionConfig(
+                        type="SendIMAction",
+                        params={
+                            "channel": "console",
+                            "message_template": "Issue {issue_id} completed!",
+                        },
+                    ),
+                ],
+            ),
+        ],
+        settings={
+            "default_poll_interval": 5.0,
+            "max_concurrent_actions": 10,
+            "action_timeout": 300,
+        },
+    )
+
+
+def save_automation_config(
+    config: AutomationConfig,
+    path: Union[str, Path],
+    format: str = "yaml",
+) -> None:
+    """
+    Save automation configuration to file.
+    
+    Args:
+        config: Configuration to save
+        path: Path to save to
+        format: "yaml" or "json"
+    """
+    path = Path(path)
+    path.parent.mkdir(parents=True, exist_ok=True)
+    
+    if format == "yaml":
+        content = config.to_yaml()
+        if path.suffix not in (".yaml", ".yml"):
+            path = path.with_suffix(".yaml")
+    else:
+        content = config.to_json()
+        if path.suffix != ".json":
+            path = path.with_suffix(".json")
+    
+    path.write_text(content, encoding="utf-8")
+    logger.info(f"Saved automation config to {path}")

monoco/core/automation/field_watcher.py

@@ -0,0 +1,296 @@
+"""
+Field Watcher - YAML Front Matter field change detection.
+
+Part of the Event Automation Framework.
+Provides field-level change detection for Markdown files with YAML Front Matter.
+"""
+
+from __future__ import annotations
+
+import logging
+import re
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any, Callable, Dict, List, Optional, Union
+
+import yaml
+
+from monoco.core.watcher.base import FieldChange, ChangeType
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class FieldCondition:
+    """
+    Condition for field value matching.
+    
+    Attributes:
+        field: Field name to check
+        operator: Comparison operator (eq, ne, gt, lt, gte, lte, in, contains)
+        value: Expected value
+    """
+    field: str
+    operator: str  # eq, ne, gt, lt, gte, lte, in, contains
+    value: Any
+    
+    OPERATORS = {
+        "eq": lambda a, b: a == b,
+        "ne": lambda a, b: a != b,
+        "gt": lambda a, b: a is not None and b is not None and a > b,
+        "lt": lambda a, b: a is not None and b is not None and a < b,
+        "gte": lambda a, b: a is not None and b is not None and a >= b,
+        "lte": lambda a, b: a is not None and b is not None and a <= b,
+        "in": lambda a, b: a in b if b is not None else False,
+        "contains": lambda a, b: b in a if a is not None else False,
+        "exists": lambda a, b: a is not None,
+    }
+    
+    def evaluate(self, data: Dict[str, Any]) -> bool:
+        """Evaluate condition against data."""
+        actual_value = data.get(self.field)
+        
+        op_func = self.OPERATORS.get(self.operator)
+        if not op_func:
+            logger.warning(f"Unknown operator: {self.operator}")
+            return False
+        
+        try:
+            return op_func(actual_value, self.value)
+        except Exception as e:
+            logger.debug(f"Condition evaluation failed: {e}")
+            return False
+
+
+class YAMLFrontMatterExtractor:
+    """
+    Extracts YAML Front Matter from Markdown files.
+    
+    Provides methods to:
+    - Parse YAML Front Matter from content
+    - Extract specific fields
+    - Detect field changes between versions
+    """
+    
+    FRONTMATTER_PATTERN = re.compile(
+        r'^---\s*\n(.*?)\n---\s*\n',
+        re.MULTILINE | re.DOTALL,
+    )
+    
+    @classmethod
+    def extract(cls, content: str) -> Optional[Dict[str, Any]]:
+        """
+        Extract YAML Front Matter from markdown content.
+        
+        Args:
+            content: Markdown file content
+            
+        Returns:
+            Dict of front matter fields, or None if not found
+        """
+        match = cls.FRONTMATTER_PATTERN.match(content)
+        if not match:
+            return None
+        
+        yaml_content = match.group(1)
+        
+        try:
+            return yaml.safe_load(yaml_content) or {}
+        except yaml.YAMLError as e:
+            logger.warning(f"Failed to parse YAML front matter: {e}")
+            return None
+    
+    @classmethod
+    def extract_from_file(cls, file_path: Path) -> Optional[Dict[str, Any]]:
+        """Extract YAML Front Matter from a file."""
+        try:
+            content = file_path.read_text(encoding="utf-8")
+            return cls.extract(content)
+        except Exception as e:
+            logger.debug(f"Could not read {file_path}: {e}")
+            return None
+    
+    @classmethod
+    def get_field(cls, content: str, field_name: str) -> Any:
+        """Get a specific field from front matter."""
+        frontmatter = cls.extract(content)
+        if frontmatter is None:
+            return None
+        return frontmatter.get(field_name)
+    
+    @classmethod
+    def detect_changes(
+        cls,
+        old_content: str,
+        new_content: str,
+        tracked_fields: Optional[List[str]] = None,
+    ) -> List[FieldChange]:
+        """
+        Detect changes in front matter fields.
+        
+        Args:
+            old_content: Previous file content
+            new_content: Current file content
+            tracked_fields: List of fields to track (None = all)
+            
+        Returns:
+            List of FieldChange objects
+        """
+        old_fm = cls.extract(old_content) or {}
+        new_fm = cls.extract(new_content) or {}
+        
+        changes = []
+        
+        # Determine which fields to check
+        if tracked_fields:
+            fields_to_check = tracked_fields
+        else:
+            fields_to_check = list(set(old_fm.keys()) | set(new_fm.keys()))
+        
+        for field_name in fields_to_check:
+            old_value = old_fm.get(field_name)
+            new_value = new_fm.get(field_name)
+            
+            if old_value != new_value:
+                # Determine change type
+                if old_value is None and new_value is not None:
+                    change_type = ChangeType.CREATED
+                elif old_value is not None and new_value is None:
+                    change_type = ChangeType.DELETED
+                else:
+                    change_type = ChangeType.MODIFIED
+                
+                changes.append(FieldChange(
+                    field_name=field_name,
+                    old_value=old_value,
+                    new_value=new_value,
+                    change_type=change_type,
+                ))
+        
+        return changes
+
+
+class FieldWatcher:
+    """
+    Watches specific fields for changes and triggers conditions.
+    
+    Maintains a cache of field values and emits events when:
+    - Fields change
+    - Conditions are met
+    
+    Example:
+        >>> watcher = FieldWatcher(
+        ...     tracked_fields=["status", "stage"],
+        ... )
+        >>> 
+        >>> # Add a condition
+        >>> watcher.add_condition(FieldCondition(
+        ...     field="stage",
+        ...     operator="eq",
+        ...     value="doing",
+        ... ))
+        >>> 
+        >>> # Check file
+        >>> changes = watcher.check_file(path, content)
+    """
+    
+    def __init__(
+        self,
+        tracked_fields: Optional[List[str]] = None,
+    ):
+        self.tracked_fields = tracked_fields
+        self._field_cache: Dict[str, Dict[str, Any]] = {}  # file_path -> field_values
+        self._conditions: List[FieldCondition] = []
+        self._condition_callbacks: List[Callable[[str, FieldCondition, Dict[str, Any]], None]] = []
+    
+    def add_condition(self, condition: FieldCondition) -> None:
+        """Add a condition to watch for."""
+        self._conditions.append(condition)
+    
+    def add_callback(
+        self,
+        callback: Callable[[str, FieldCondition, Dict[str, Any]], None],
+    ) -> None:
+        """Add a callback for when conditions are met."""
+        self._condition_callbacks.append(callback)
+    
+    def check_file(
+        self,
+        file_path: Union[str, Path],
+        content: str,
+    ) -> List[FieldChange]:
+        """
+        Check a file for field changes.
+        
+        Args:
+            file_path: Path to the file
+            content: Current file content
+            
+        Returns:
+            List of field changes
+        """
+        path_key = str(file_path)
+        
+        # Extract current fields
+        current_fm = YAMLFrontMatterExtractor.extract(content) or {}
+        
+        if self.tracked_fields:
+            current_fields = {
+                f: current_fm.get(f)
+                for f in self.tracked_fields
+            }
+        else:
+            current_fields = current_fm
+        
+        # Get cached fields
+        cached_fields = self._field_cache.get(path_key, {})
+        
+        # Detect changes
+        changes = []
+        for field_name, new_value in current_fields.items():
+            old_value = cached_fields.get(field_name)
+            if old_value != new_value:
+                changes.append(FieldChange(
+                    field_name=field_name,
+                    old_value=old_value,
+                    new_value=new_value,
+                    change_type=ChangeType.MODIFIED if old_value is not None else ChangeType.CREATED,
+                ))
+        
+        # Update cache
+        self._field_cache[path_key] = current_fields
+        
+        # Check conditions
+        if changes:
+            self._check_conditions(path_key, current_fields)
+        
+        return changes
+    
+    def _check_conditions(self, file_path: str, fields: Dict[str, Any]) -> None:
+        """Check if any conditions are met."""
+        for condition in self._conditions:
+            if condition.evaluate(fields):
+                for callback in self._condition_callbacks:
+                    try:
+                        callback(file_path, condition, fields)
+                    except Exception as e:
+                        logger.error(f"Condition callback error: {e}")
+    
+    def get_cached_fields(self, file_path: Union[str, Path]) -> Optional[Dict[str, Any]]:
+        """Get cached fields for a file."""
+        return self._field_cache.get(str(file_path))
+    
+    def clear_cache(self, file_path: Optional[Union[str, Path]] = None) -> None:
+        """Clear the field cache."""
+        if file_path:
+            self._field_cache.pop(str(file_path), None)
+        else:
+            self._field_cache.clear()
+    
+    def get_stats(self) -> Dict[str, Any]:
+        """Get watcher statistics."""
+        return {
+            "tracked_files": len(self._field_cache),
+            "tracked_fields": self.tracked_fields,
+            "conditions": len(self._conditions),
+        }