mcli-framework 7.0.0__py3-none-any.whl

mcli/workflow/scheduler/cron_parser.py

@@ -0,0 +1,238 @@
+"""
+Cron expression parser for the MCLI scheduler
+
+Supports standard cron expressions with some extensions:
+- Standard: minute hour day month weekday
+- Extensions: @yearly, @monthly, @weekly, @daily, @hourly
+- Special: @reboot (run at scheduler start)
+"""
+
+import re
+from datetime import datetime, timedelta
+from typing import List, Optional, Set
+
+from mcli.lib.logger.logger import get_logger
+
+logger = get_logger(__name__)
+
+
+class CronParseError(Exception):
+    """Exception raised when cron expression cannot be parsed"""
+
+    pass
+
+
+class CronExpression:
+    """Parser and calculator for cron expressions"""
+
+    # Predefined cron shortcuts
+    SHORTCUTS = {
+        "@yearly": "0 0 1 1 *",
+        "@annually": "0 0 1 1 *",
+        "@monthly": "0 0 1 * *",
+        "@weekly": "0 0 * * 0",
+        "@daily": "0 0 * * *",
+        "@midnight": "0 0 * * *",
+        "@hourly": "0 * * * *",
+        "@reboot": "@reboot",  # Special case
+    }
+
+    def __init__(self, expression: str):
+        self.original_expression = expression.strip()
+        self.expression = self._normalize_expression(expression)
+        self.is_reboot = self.expression == "@reboot"
+
+        if not self.is_reboot:
+            self.fields = self._parse_expression()
+            self._validate_fields()
+
+    def _normalize_expression(self, expression: str) -> str:
+        """Convert shortcuts to standard cron format"""
+        expression = expression.strip().lower()
+
+        if expression in self.SHORTCUTS:
+            return self.SHORTCUTS[expression]
+
+        return expression
+
+    def _parse_expression(self) -> List[Set[int]]:
+        """Parse cron expression into field sets"""
+        if self.is_reboot:
+            return []
+
+        parts = self.expression.split()
+        if len(parts) != 5:
+            raise CronParseError(f"Invalid cron expression: expected 5 fields, got {len(parts)}")
+
+        fields = []
+        ranges = [
+            (0, 59),  # minute
+            (0, 23),  # hour
+            (1, 31),  # day
+            (1, 12),  # month
+            (0, 6),  # weekday (0=Sunday)
+        ]
+
+        for i, (part, (min_val, max_val)) in enumerate(zip(parts, ranges)):
+            field_values = self._parse_field(part, min_val, max_val)
+            fields.append(field_values)
+
+        return fields
+
+    def _parse_field(self, field: str, min_val: int, max_val: int) -> Set[int]:
+        """Parse a single cron field"""
+        if field == "*":
+            return set(range(min_val, max_val + 1))
+
+        values = set()
+
+        # Handle comma-separated values
+        for part in field.split(","):
+            part = part.strip()
+
+            if "/" in part:
+                # Handle step values (e.g., */5, 10-20/2)
+                range_part, step_part = part.split("/", 1)
+                step = int(step_part)
+
+                if range_part == "*":
+                    start, end = min_val, max_val
+                elif "-" in range_part:
+                    start, end = map(int, range_part.split("-", 1))
+                else:
+                    start = end = int(range_part)
+
+                values.update(range(start, end + 1, step))
+
+            elif "-" in part:
+                # Handle ranges (e.g., 1-5)
+                start, end = map(int, part.split("-", 1))
+                values.update(range(start, end + 1))
+
+            else:
+                # Handle single values
+                values.add(int(part))
+
+        # Validate values are within range
+        for value in values:
+            if not (min_val <= value <= max_val):
+                raise CronParseError(f"Value {value} out of range [{min_val}, {max_val}]")
+
+        return values
+
+    def _validate_fields(self):
+        """Validate parsed cron fields"""
+        if len(self.fields) != 5:
+            raise CronParseError("Invalid number of parsed fields")
+
+    def get_next_run_time(self, from_time: Optional[datetime] = None) -> Optional[datetime]:
+        """Calculate the next time this cron expression should run"""
+        if self.is_reboot:
+            return None  # @reboot jobs run only at scheduler start
+
+        if from_time is None:
+            from_time = datetime.now()
+
+        # Start from the next minute to avoid immediate execution
+        next_time = from_time.replace(second=0, microsecond=0) + timedelta(minutes=1)
+
+        # Search for the next valid time (with safety limit)
+        max_iterations = 366 * 24 * 60  # One year worth of minutes
+        iterations = 0
+
+        while iterations < max_iterations:
+            if self._matches_time(next_time):
+                return next_time
+
+            next_time += timedelta(minutes=1)
+            iterations += 1
+
+        logger.warning(f"Could not find next run time for cron expression: {self.expression}")
+        return None
+
+    def _matches_time(self, dt: datetime) -> bool:
+        """Check if datetime matches this cron expression"""
+        if self.is_reboot:
+            return False
+
+        minute, hour, day, month, weekday = self.fields
+
+        return (
+            dt.minute in minute
+            and dt.hour in hour
+            and dt.day in day
+            and dt.month in month
+            and dt.weekday() + 1 % 7 in weekday  # Convert Python weekday to cron weekday
+        )
+
+    def matches_now(self) -> bool:
+        """Check if cron expression matches current time"""
+        return self._matches_time(datetime.now())
+
+    def get_description(self) -> str:
+        """Get human-readable description of cron expression"""
+        if self.is_reboot:
+            return "Run at scheduler startup"
+
+        # Basic descriptions for common patterns
+        if self.expression == "0 0 * * *":
+            return "Run daily at midnight"
+        elif self.expression == "0 * * * *":
+            return "Run every hour"
+        elif self.expression == "*/5 * * * *":
+            return "Run every 5 minutes"
+        elif self.expression == "0 0 * * 0":
+            return "Run weekly on Sunday at midnight"
+        elif self.expression == "0 0 1 * *":
+            return "Run monthly on the 1st at midnight"
+        elif self.expression == "0 0 1 1 *":
+            return "Run yearly on January 1st at midnight"
+        else:
+            return f"Custom schedule: {self.original_expression}"
+
+    def is_valid(self) -> bool:
+        """Check if cron expression is valid"""
+        try:
+            if self.is_reboot:
+                return True
+            return len(self.fields) == 5
+        except:
+            return False
+
+    def __str__(self) -> str:
+        return self.original_expression
+
+    def __repr__(self) -> str:
+        return f"CronExpression('{self.original_expression}')"
+
+
+def validate_cron_expression(expression: str) -> bool:
+    """Validate a cron expression without creating a full object"""
+    try:
+        cron = CronExpression(expression)
+        return cron.is_valid()
+    except:
+        return False
+
+
+def get_next_run_times(expression: str, count: int = 5) -> List[datetime]:
+    """Get the next N run times for a cron expression"""
+    try:
+        cron = CronExpression(expression)
+        if cron.is_reboot:
+            return []
+
+        times = []
+        current_time = datetime.now()
+
+        for _ in range(count):
+            next_time = cron.get_next_run_time(current_time)
+            if next_time is None:
+                break
+            times.append(next_time)
+            current_time = next_time
+
+        return times
+    except Exception as e:
+        logger.error(f"Error getting next run times: {e}")
+        return []

mcli/workflow/scheduler/job.py

@@ -0,0 +1,182 @@
+"""
+Job definitions and status tracking for the MCLI scheduler
+"""
+
+import json
+import uuid
+from datetime import datetime, timedelta
+from enum import Enum
+from typing import Any, Dict, List, Optional
+
+from mcli.lib.logger.logger import get_logger
+
+logger = get_logger(__name__)
+
+
+class JobStatus(Enum):
+    """Job execution status"""
+
+    PENDING = "pending"
+    RUNNING = "running"
+    COMPLETED = "completed"
+    FAILED = "failed"
+    CANCELLED = "cancelled"
+    SKIPPED = "skipped"
+
+
+class JobType(Enum):
+    """Types of jobs that can be scheduled"""
+
+    COMMAND = "command"  # Execute shell commands
+    PYTHON = "python"  # Execute Python code
+    CLEANUP = "cleanup"  # File system cleanup tasks
+    SYSTEM = "system"  # System maintenance tasks
+    API_CALL = "api_call"  # HTTP API calls
+    CUSTOM = "custom"  # Custom user-defined jobs
+
+
+class ScheduledJob:
+    """Represents a scheduled job with all its metadata"""
+
+    def __init__(
+        self,
+        name: str,
+        cron_expression: str,
+        job_type: JobType,
+        command: str,
+        description: str = "",
+        enabled: bool = True,
+        max_runtime: int = 3600,  # 1 hour default
+        retry_count: int = 0,
+        retry_delay: int = 60,  # 1 minute default
+        environment: Optional[Dict[str, str]] = None,
+        working_directory: Optional[str] = None,
+        output_format: str = "json",
+        notifications: Optional[Dict[str, Any]] = None,
+        job_id: Optional[str] = None,
+    ):
+        self.id = job_id or str(uuid.uuid4())
+        self.name = name
+        self.cron_expression = cron_expression
+        self.job_type = job_type
+        self.command = command
+        self.description = description
+        self.enabled = enabled
+        self.max_runtime = max_runtime
+        self.retry_count = retry_count
+        self.retry_delay = retry_delay
+        self.environment = environment or {}
+        self.working_directory = working_directory
+        self.output_format = output_format
+        self.notifications = notifications or {}
+
+        # Runtime tracking
+        self.status = JobStatus.PENDING
+        self.created_at = datetime.now()
+        self.last_run = None
+        self.next_run = None
+        self.run_count = 0
+        self.success_count = 0
+        self.failure_count = 0
+        self.last_output = ""
+        self.last_error = ""
+        self.runtime_seconds = 0
+        self.current_retry = 0
+
+    def to_dict(self) -> Dict[str, Any]:
+        """Convert job to dictionary for serialization"""
+        return {
+            "id": self.id,
+            "name": self.name,
+            "cron_expression": self.cron_expression,
+            "job_type": self.job_type.value,
+            "command": self.command,
+            "description": self.description,
+            "enabled": self.enabled,
+            "max_runtime": self.max_runtime,
+            "retry_count": self.retry_count,
+            "retry_delay": self.retry_delay,
+            "environment": self.environment,
+            "working_directory": self.working_directory,
+            "output_format": self.output_format,
+            "notifications": self.notifications,
+            "status": self.status.value,
+            "created_at": self.created_at.isoformat(),
+            "last_run": self.last_run.isoformat() if self.last_run else None,
+            "next_run": self.next_run.isoformat() if self.next_run else None,
+            "run_count": self.run_count,
+            "success_count": self.success_count,
+            "failure_count": self.failure_count,
+            "last_output": self.last_output,
+            "last_error": self.last_error,
+            "runtime_seconds": self.runtime_seconds,
+            "current_retry": self.current_retry,
+        }
+
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> "ScheduledJob":
+        """Create job from dictionary"""
+        job = cls(
+            name=data["name"],
+            cron_expression=data["cron_expression"],
+            job_type=JobType(data["job_type"]),
+            command=data["command"],
+            description=data.get("description", ""),
+            enabled=data.get("enabled", True),
+            max_runtime=data.get("max_runtime", 3600),
+            retry_count=data.get("retry_count", 0),
+            retry_delay=data.get("retry_delay", 60),
+            environment=data.get("environment", {}),
+            working_directory=data.get("working_directory"),
+            output_format=data.get("output_format", "json"),
+            notifications=data.get("notifications", {}),
+            job_id=data.get("id"),
+        )
+
+        # Restore runtime state
+        job.status = JobStatus(data.get("status", "pending"))
+        job.created_at = datetime.fromisoformat(data["created_at"])
+        job.last_run = datetime.fromisoformat(data["last_run"]) if data.get("last_run") else None
+        job.next_run = datetime.fromisoformat(data["next_run"]) if data.get("next_run") else None
+        job.run_count = data.get("run_count", 0)
+        job.success_count = data.get("success_count", 0)
+        job.failure_count = data.get("failure_count", 0)
+        job.last_output = data.get("last_output", "")
+        job.last_error = data.get("last_error", "")
+        job.runtime_seconds = data.get("runtime_seconds", 0)
+        job.current_retry = data.get("current_retry", 0)
+
+        return job
+
+    def update_status(self, status: JobStatus, output: str = "", error: str = ""):
+        """Update job status and related metadata"""
+        self.status = status
+        self.last_output = output
+        self.last_error = error
+
+        if status == JobStatus.RUNNING:
+            self.last_run = datetime.now()
+            self.run_count += 1
+        elif status == JobStatus.COMPLETED:
+            self.success_count += 1
+            self.current_retry = 0
+        elif status == JobStatus.FAILED:
+            self.failure_count += 1
+
+    def should_retry(self) -> bool:
+        """Check if job should be retried after failure"""
+        return self.status == JobStatus.FAILED and self.current_retry < self.retry_count
+
+    def get_next_retry_time(self) -> datetime:
+        """Calculate next retry time"""
+        return datetime.now() + timedelta(seconds=self.retry_delay)
+
+    def to_json(self) -> str:
+        """Convert job to JSON string"""
+        return json.dumps(self.to_dict(), indent=2)
+
+    def __str__(self) -> str:
+        return f"Job(id={self.id[:8]}, name={self.name}, status={self.status.value})"
+
+    def __repr__(self) -> str:
+        return f"ScheduledJob(id='{self.id}', name='{self.name}', cron='{self.cron_expression}')"

mcli/workflow/scheduler/monitor.py

@@ -0,0 +1,139 @@
+"""
+Job monitoring and execution tracking for the MCLI scheduler
+"""
+
+import threading
+import time
+from datetime import datetime, timedelta
+from typing import Callable, Dict, List, Optional
+
+from mcli.lib.logger.logger import get_logger
+
+from .job import JobStatus, ScheduledJob
+
+logger = get_logger(__name__)
+
+
+class JobMonitor:
+    """Monitors running jobs and handles timeouts, retries, and status updates"""
+
+    def __init__(self, status_callback: Optional[Callable] = None):
+        self.running_jobs: Dict[str, threading.Thread] = {}
+        self.job_start_times: Dict[str, datetime] = {}
+        self.status_callback = status_callback
+        self.monitor_thread: Optional[threading.Thread] = None
+        self.monitoring = False
+        self.lock = threading.Lock()
+
+    def start_monitoring(self):
+        """Start the monitoring thread"""
+        if self.monitoring:
+            return
+
+        self.monitoring = True
+        self.monitor_thread = threading.Thread(target=self._monitor_loop, daemon=True)
+        self.monitor_thread.start()
+        logger.info("Job monitor started")
+
+    def stop_monitoring(self):
+        """Stop the monitoring thread"""
+        self.monitoring = False
+        if self.monitor_thread:
+            self.monitor_thread.join(timeout=5)
+        logger.info("Job monitor stopped")
+
+    def _monitor_loop(self):
+        """Main monitoring loop"""
+        while self.monitoring:
+            try:
+                self._check_running_jobs()
+                time.sleep(10)  # Check every 10 seconds
+            except Exception as e:
+                logger.error(f"Error in monitor loop: {e}")
+
+    def _check_running_jobs(self):
+        """Check status of running jobs"""
+        with self.lock:
+            current_time = datetime.now()
+            jobs_to_remove = []
+
+            for job_id, thread in self.running_jobs.items():
+                start_time = self.job_start_times.get(job_id)
+
+                if start_time:
+                    runtime = (current_time - start_time).total_seconds()
+
+                    # Check if thread is still alive
+                    if not thread.is_alive():
+                        jobs_to_remove.append(job_id)
+                        logger.debug(f"Job {job_id} completed, removing from monitor")
+
+                    # Note: Timeout handling would need job reference for max_runtime
+                    # This is a simplified implementation
+
+            # Clean up completed jobs
+            for job_id in jobs_to_remove:
+                self._remove_job(job_id)
+
+    def add_job(self, job: ScheduledJob, thread: threading.Thread):
+        """Add a job to monitoring"""
+        with self.lock:
+            self.running_jobs[job.id] = thread
+            self.job_start_times[job.id] = datetime.now()
+            logger.debug(f"Added job {job.id} to monitor")
+
+    def _remove_job(self, job_id: str):
+        """Remove a job from monitoring"""
+        self.running_jobs.pop(job_id, None)
+        self.job_start_times.pop(job_id, None)
+
+    def get_running_jobs(self) -> List[str]:
+        """Get list of currently running job IDs"""
+        with self.lock:
+            return list(self.running_jobs.keys())
+
+    def is_job_running(self, job_id: str) -> bool:
+        """Check if a specific job is currently running"""
+        with self.lock:
+            return job_id in self.running_jobs
+
+    def get_job_runtime(self, job_id: str) -> Optional[int]:
+        """Get runtime in seconds for a running job"""
+        with self.lock:
+            start_time = self.job_start_times.get(job_id)
+            if start_time:
+                return int((datetime.now() - start_time).total_seconds())
+        return None
+
+    def kill_job(self, job_id: str) -> bool:
+        """Attempt to kill a running job"""
+        with self.lock:
+            thread = self.running_jobs.get(job_id)
+            if thread and thread.is_alive():
+                # Note: Python threads cannot be forcibly killed
+                # This would need process-based execution for true killing
+                logger.warning(f"Cannot forcibly kill job {job_id} - Python thread limitation")
+                return False
+        return True
+
+    def get_monitor_stats(self) -> dict:
+        """Get monitoring statistics"""
+        with self.lock:
+            stats = {
+                "monitoring": self.monitoring,
+                "running_jobs_count": len(self.running_jobs),
+                "running_job_ids": list(self.running_jobs.keys()),
+                "monitor_thread_alive": (
+                    self.monitor_thread.is_alive() if self.monitor_thread else False
+                ),
+            }
+
+            # Add runtime info for each job
+            current_time = datetime.now()
+            job_runtimes = {}
+            for job_id, start_time in self.job_start_times.items():
+                runtime = (current_time - start_time).total_seconds()
+                job_runtimes[job_id] = int(runtime)
+
+            stats["job_runtimes"] = job_runtimes
+            return stats