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

monoco/core/router/__init__.py

@@ -0,0 +1,17 @@
+"""
+Router Module - Layer 2 of the Event Automation Framework.
+
+This module provides Action ABC and ActionResult for handlers.
+"""
+
+from .action import (
+    Action,
+    ActionResult,
+    ActionStatus,
+)
+
+__all__ = [
+    "Action",
+    "ActionResult",
+    "ActionStatus",
+]

monoco/core/router/action.py

@@ -0,0 +1,202 @@
+"""
+Action Abstractions - Layer 2 & 3 of the Event Automation Framework.
+
+This module defines the Action ABC and ActionResult for handler return types.
+"""
+
+from __future__ import annotations
+
+import logging
+from abc import ABC, abstractmethod
+from dataclasses import dataclass, field
+from datetime import datetime
+from enum import Enum
+from typing import Any, Dict, Optional
+
+from monoco.core.scheduler import AgentEvent, AgentEventType
+
+logger = logging.getLogger(__name__)
+
+
+class ActionStatus(Enum):
+    """Status of an Action execution."""
+    PENDING = "pending"
+    RUNNING = "running"
+    SUCCESS = "success"
+    FAILED = "failed"
+    SKIPPED = "skipped"
+    CANCELLED = "cancelled"
+
+
+@dataclass
+class ActionResult:
+    """
+    Result of an Action execution.
+    
+    Attributes:
+        success: Whether the action succeeded
+        status: Detailed status
+        output: Output data from the action
+        error: Error message if failed
+        metadata: Additional metadata
+        started_at: Execution start time
+        completed_at: Execution completion time
+    """
+    success: bool
+    status: ActionStatus
+    output: Any = None
+    error: Optional[str] = None
+    metadata: Dict[str, Any] = field(default_factory=dict)
+    started_at: Optional[datetime] = None
+    completed_at: Optional[datetime] = None
+    
+    @classmethod
+    def success_result(
+        cls,
+        output: Any = None,
+        metadata: Optional[Dict[str, Any]] = None,
+    ) -> "ActionResult":
+        """Create a success result."""
+        return cls(
+            success=True,
+            status=ActionStatus.SUCCESS,
+            output=output,
+            metadata=metadata or {},
+            completed_at=datetime.now(),
+        )
+    
+    @classmethod
+    def failure_result(
+        cls,
+        error: str,
+        metadata: Optional[Dict[str, Any]] = None,
+    ) -> "ActionResult":
+        """Create a failure result."""
+        return cls(
+            success=False,
+            status=ActionStatus.FAILED,
+            error=error,
+            metadata=metadata or {},
+            completed_at=datetime.now(),
+        )
+    
+    @classmethod
+    def skipped_result(
+        cls,
+        reason: str = "",
+        metadata: Optional[Dict[str, Any]] = None,
+    ) -> "ActionResult":
+        """Create a skipped result."""
+        return cls(
+            success=True,
+            status=ActionStatus.SKIPPED,
+            metadata={"reason": reason, **(metadata or {})},
+            completed_at=datetime.now(),
+        )
+
+
+class Action(ABC):
+    """
+    Abstract base class for Actions (Layer 3).
+    
+    Actions are the units of work that respond to events.
+    They are executed by handlers when events match their conditions.
+    
+    Responsibilities:
+    - Define execution conditions (can_execute)
+    - Implement execution logic (execute)
+    - Return execution results
+    
+    Example:
+        >>> class MyAction(Action):
+        ...     @property
+        ...     def name(self) -> str:
+        ...         return "MyAction"
+        ...     
+        ...     async def can_execute(self, event: AgentEvent) -> bool:
+        ...         return event.type == AgentEventType.ISSUE_CREATED
+        ...     
+        ...     async def execute(self, event: AgentEvent) -> ActionResult:
+        ...         # Do something
+        ...         return ActionResult.success_result()
+    """
+    
+    def __init__(self, config: Optional[Dict[str, Any]] = None):
+        self.config = config or {}
+        self._execution_count = 0
+        self._last_execution: Optional[datetime] = None
+    
+    @property
+    @abstractmethod
+    def name(self) -> str:
+        """Return the unique name of this action."""
+        pass
+    
+    @abstractmethod
+    async def can_execute(self, event: AgentEvent) -> bool:
+        """
+        Check if this action should execute for the given event.
+        
+        Args:
+            event: The event to check
+            
+        Returns:
+            True if the action should execute, False otherwise
+        """
+        pass
+    
+    @abstractmethod
+    async def execute(self, event: AgentEvent) -> ActionResult:
+        """
+        Execute the action.
+        
+        Args:
+            event: The event that triggered this action
+            
+        Returns:
+            ActionResult indicating success/failure
+        """
+        pass
+    
+    async def __call__(self, event: AgentEvent) -> ActionResult:
+        """
+        Make action callable - checks conditions then executes.
+        
+        Args:
+            event: The event to process
+            
+        Returns:
+            ActionResult
+        """
+        self._last_execution = datetime.now()
+        
+        try:
+            if not await self.can_execute(event):
+                return ActionResult.skipped_result(
+                    reason="Conditions not met",
+                    metadata={"action": self.name, "event_type": event.type.value},
+                )
+            
+            self._execution_count += 1
+            result = await self.execute(event)
+            
+            # Ensure result has timestamps
+            if result.started_at is None:
+                result.started_at = self._last_execution
+            
+            return result
+        
+        except Exception as e:
+            logger.error(f"Action {self.name} failed: {e}", exc_info=True)
+            return ActionResult.failure_result(
+                error=str(e),
+                metadata={"action": self.name, "event_type": event.type.value},
+            )
+    
+    def get_stats(self) -> Dict[str, Any]:
+        """Get action statistics."""
+        return {
+            "name": self.name,
+            "execution_count": self._execution_count,
+            "last_execution": self._last_execution.isoformat() if self._last_execution else None,
+        }

monoco/core/scheduler/__init__.py

@@ -0,0 +1,63 @@
+"""
+AgentScheduler - Core scheduling abstraction layer for Monoco.
+
+This module provides the high-level AgentScheduler abstraction that decouples
+scheduling policies from specific Agent Provider implementations.
+
+Architecture:
+    - AgentScheduler: Abstract base class for all schedulers
+    - AgentTask: Data class representing a task to be scheduled
+    - AgentStatus: Enum for task lifecycle states
+    - EngineAdapter: Abstract base for agent engine adapters
+    - EngineFactory: Factory for creating engine adapters
+    - EventBus: Central event system for agent scheduling
+    - AgentEventType: Event types for agent lifecycle
+
+Implementations:
+    - LocalProcessScheduler: Local process-based scheduler (default)
+    - Future: DockerScheduler, RemoteScheduler, etc.
+"""
+
+from .base import (
+    AgentStatus,
+    AgentTask,
+    AgentScheduler,
+)
+from .engines import (
+    EngineAdapter,
+    EngineFactory,
+    GeminiAdapter,
+    ClaudeAdapter,
+    QwenAdapter,
+    KimiAdapter,
+)
+from .events import (
+    AgentEventType,
+    AgentEvent,
+    EventBus,
+    EventHandler,
+    event_bus,
+)
+from .local import LocalProcessScheduler
+
+__all__ = [
+    # Base abstractions
+    "AgentStatus",
+    "AgentTask",
+    "AgentScheduler",
+    # Engine adapters
+    "EngineAdapter",
+    "EngineFactory",
+    "GeminiAdapter",
+    "ClaudeAdapter",
+    "QwenAdapter",
+    "KimiAdapter",
+    # Events
+    "AgentEventType",
+    "AgentEvent",
+    "EventBus",
+    "EventHandler",
+    "event_bus",
+    # Implementations
+    "LocalProcessScheduler",
+]

monoco/core/scheduler/base.py

@@ -0,0 +1,152 @@
+"""
+Base abstractions for AgentScheduler.
+
+Defines the core AgentScheduler ABC, AgentTask dataclass, and AgentStatus enum.
+"""
+
+from abc import ABC, abstractmethod
+from dataclasses import dataclass, field
+from datetime import datetime
+from enum import Enum
+from typing import Dict, Any, Optional
+
+
+class AgentStatus(Enum):
+    """
+    Lifecycle states for an agent task.
+    
+    States:
+        PENDING: Task is queued, waiting for resources
+        RUNNING: Task is actively executing
+        COMPLETED: Task finished successfully
+        FAILED: Task failed with an error
+        TERMINATED: Task was manually terminated
+        TIMEOUT: Task exceeded its time limit
+    """
+    PENDING = "pending"
+    RUNNING = "running"
+    COMPLETED = "completed"
+    FAILED = "failed"
+    TERMINATED = "terminated"
+    TIMEOUT = "timeout"
+
+
+@dataclass
+class AgentTask:
+    """
+    Data class representing a task to be scheduled.
+    
+    Attributes:
+        task_id: Unique identifier for the task
+        role_name: Name of the agent role (e.g., "Engineer", "Architect")
+        issue_id: Associated issue ID
+        prompt: The instruction/context to send to the agent
+        engine: Agent engine to use (e.g., "gemini", "claude")
+        timeout: Maximum execution time in seconds
+        metadata: Additional task metadata
+        created_at: Task creation timestamp
+    """
+    task_id: str
+    role_name: str
+    issue_id: str
+    prompt: str
+    engine: str = "gemini"
+    timeout: int = 900
+    metadata: Dict[str, Any] = field(default_factory=dict)
+    created_at: datetime = field(default_factory=datetime.now)
+    
+    def __post_init__(self):
+        """Ensure created_at is set."""
+        if self.created_at is None:
+            self.created_at = datetime.now()
+
+
+class AgentScheduler(ABC):
+    """
+    High-level scheduling abstraction that decouples scheduling policies
+    from specific Agent Provider implementations.
+    
+    Responsibilities:
+        - Task scheduling and lifecycle management
+        - Resource quota control (concurrency limits)
+        - Status monitoring and event publishing
+    
+    Implementations:
+        - LocalProcessScheduler: Local process mode (current)
+        - DockerScheduler: Container mode (future)
+        - RemoteScheduler: Remote service mode (future)
+    
+    Example:
+        >>> scheduler = LocalProcessScheduler(max_concurrent=5)
+        >>> task = AgentTask(
+        ...     task_id="uuid-123",
+        ...     role_name="Engineer",
+        ...     issue_id="FEAT-123",
+        ...     prompt="Implement feature X",
+        ...     engine="gemini"
+        ... )
+        >>> session_id = await scheduler.schedule(task)
+        >>> status = scheduler.get_status(session_id)
+    """
+    
+    @abstractmethod
+    async def schedule(self, task: AgentTask) -> str:
+        """
+        Schedule a task for execution.
+        
+        Args:
+            task: The task to schedule
+            
+        Returns:
+            session_id: Unique identifier for the scheduled session
+            
+        Raises:
+            RuntimeError: If scheduling fails
+        """
+        pass
+    
+    @abstractmethod
+    async def terminate(self, session_id: str) -> bool:
+        """
+        Terminate a running or pending task.
+        
+        Args:
+            session_id: The session ID to terminate
+            
+        Returns:
+            True if termination was successful, False otherwise
+        """
+        pass
+    
+    @abstractmethod
+    def get_status(self, session_id: str) -> Optional[AgentStatus]:
+        """
+        Get the current status of a task.
+        
+        Args:
+            session_id: The session ID to query
+            
+        Returns:
+            The current AgentStatus, or None if session not found
+        """
+        pass
+    
+    @abstractmethod
+    def list_active(self) -> Dict[str, AgentStatus]:
+        """
+        List all active (pending or running) tasks.
+        
+        Returns:
+            Dictionary mapping session_id to AgentStatus
+        """
+        pass
+    
+    @abstractmethod
+    def get_stats(self) -> Dict[str, Any]:
+        """
+        Get scheduler statistics.
+        
+        Returns:
+            Dictionary containing scheduler metrics
+        """
+        pass

monoco/core/scheduler/engines.py

@@ -0,0 +1,175 @@
+"""
+Agent Engine Adapters for Monoco Scheduler.
+
+This module provides a unified interface for different AI agent execution engines,
+allowing the Worker to seamlessly switch between Gemini, Claude, and future engines.
+"""
+
+from abc import ABC, abstractmethod
+from typing import List
+
+
+class EngineAdapter(ABC):
+    """
+    Abstract base class for agent engine adapters.
+
+    Each adapter is responsible for:
+    1. Constructing the correct CLI command for its engine
+    2. Handling engine-specific error scenarios
+    3. Providing metadata about the engine's capabilities
+    """
+
+    @abstractmethod
+    def build_command(self, prompt: str) -> List[str]:
+        """
+        Build the CLI command to execute the agent with the given prompt.
+
+        Args:
+            prompt: The instruction/context to send to the agent
+
+        Returns:
+            List of command arguments (e.g., ["gemini", "-y", "prompt text"])
+        """
+        pass
+
+    @property
+    @abstractmethod
+    def name(self) -> str:
+        """Return the canonical name of this engine."""
+        pass
+
+    @property
+    def supports_yolo_mode(self) -> bool:
+        """Whether this engine supports auto-approval mode."""
+        return False
+
+
+class GeminiAdapter(EngineAdapter):
+    """
+    Adapter for Google Gemini CLI.
+
+    Command format: gemini -p <prompt> -y
+    The -y flag enables "YOLO mode" (auto-approval of actions).
+    """
+
+    def build_command(self, prompt: str) -> List[str]:
+        # Based on Gemini CLI help: -p <prompt> for non-interactive
+        return ["gemini", "-p", prompt, "-y"]
+
+    @property
+    def name(self) -> str:
+        return "gemini"
+
+    @property
+    def supports_yolo_mode(self) -> bool:
+        return True
+
+
+class ClaudeAdapter(EngineAdapter):
+    """
+    Adapter for Anthropic Claude CLI.
+
+    Command format: claude -p <prompt>
+    The -p/--print flag enables non-interactive mode.
+    """
+
+    def build_command(self, prompt: str) -> List[str]:
+        # Based on Claude CLI help: -p <prompt> is NOT standard, usually -p means print/non-interactive.
+        # But for one-shot execution, we do passing prompt as argument with -p flag.
+        return ["claude", "-p", prompt]
+
+    @property
+    def name(self) -> str:
+        return "claude"
+
+    @property
+    def supports_yolo_mode(self) -> bool:
+        # Claude uses -p for non-interactive mode, similar concept
+        return True
+
+
+class QwenAdapter(EngineAdapter):
+    """
+    Adapter for Qwen Code CLI.
+
+    Command format: qwen -p <prompt> -y
+    """
+
+    def build_command(self, prompt: str) -> List[str]:
+        # Assuming Qwen follows similar patterns (based on user feedback)
+        return ["qwen", "-p", prompt, "-y"]
+
+    @property
+    def name(self) -> str:
+        return "qwen"
+
+    @property
+    def supports_yolo_mode(self) -> bool:
+        return True
+
+
+class KimiAdapter(EngineAdapter):
+    """
+    Adapter for Kimi CLI (Moonshot AI).
+
+    Command format: kimi -p <prompt> --print
+    Note: --print implicitly adds --yolo.
+    """
+
+    def build_command(self, prompt: str) -> List[str]:
+        # Based on Kimi CLI help: -p, --prompt TEXT.
+        # Also using --print for non-interactive mode (which enables yolo).
+        return ["kimi", "-p", prompt, "--print"]
+
+    @property
+    def name(self) -> str:
+        return "kimi"
+
+    @property
+    def supports_yolo_mode(self) -> bool:
+        return True
+
+
+class EngineFactory:
+    """
+    Factory for creating engine adapter instances.
+
+    Usage:
+        adapter = EngineFactory.create("gemini")
+        command = adapter.build_command("Write a test")
+    """
+
+    _adapters = {
+        "gemini": GeminiAdapter,
+        "claude": ClaudeAdapter,
+        "qwen": QwenAdapter,
+        "kimi": KimiAdapter,
+    }
+
+    @classmethod
+    def create(cls, engine_name: str) -> EngineAdapter:
+        """
+        Create an adapter instance for the specified engine.
+
+        Args:
+            engine_name: Name of the engine (e.g., "gemini", "claude")
+
+        Returns:
+            An instance of the appropriate EngineAdapter
+
+        Raises:
+            ValueError: If the engine is not supported
+        """
+        adapter_class = cls._adapters.get(engine_name.lower())
+        if not adapter_class:
+            supported = ", ".join(cls._adapters.keys())
+            raise ValueError(
+                f"Unsupported engine: '{engine_name}'. "
+                f"Supported engines: {supported}"
+            )
+        return adapter_class()
+
+    @classmethod
+    def supported_engines(cls) -> List[str]:
+        """Return a list of all supported engine names."""
+        return list(cls._adapters.keys())