spatelier 0.3.0__py3-none-any.whl

core/analytics_dashboard.py

@@ -0,0 +1,368 @@
+"""
+Analytics dashboard for Spatelier.
+
+This module provides a web-based analytics dashboard for viewing
+processing statistics, usage metrics, and system health.
+"""
+
+import json
+import time
+from dataclasses import asdict, dataclass
+from datetime import datetime, timedelta
+from pathlib import Path
+from typing import Any, Dict, List, Optional
+
+from rich.console import Console
+from rich.layout import Layout
+from rich.live import Live
+from rich.panel import Panel
+from rich.table import Table
+from rich.text import Text
+
+from core.config import Config
+from core.logger import get_logger
+
+
+@dataclass
+class ProcessingStats:
+    """Processing statistics data class."""
+
+    total_videos: int = 0
+    total_audio: int = 0
+    total_playlists: int = 0
+    total_duration: float = 0.0
+    total_size: int = 0
+    success_rate: float = 0.0
+    avg_processing_time: float = 0.0
+    last_24h_videos: int = 0
+    last_24h_audio: int = 0
+    last_24h_playlists: int = 0
+
+
+@dataclass
+class SystemHealth:
+    """System health metrics."""
+
+    cpu_usage: float = 0.0
+    memory_usage: float = 0.0
+    disk_usage: float = 0.0
+    active_jobs: int = 0
+    queue_size: int = 0
+    last_activity: Optional[datetime] = None
+    uptime: float = 0.0
+
+
+class AnalyticsDashboard:
+    """Analytics dashboard for Spatelier."""
+
+    def __init__(self, config: Config, verbose: bool = False):
+        """
+        Initialize analytics dashboard.
+
+        Args:
+            config: Configuration instance
+            verbose: Enable verbose logging
+        """
+        self.config = config
+        self.verbose = verbose
+        self.logger = get_logger("AnalyticsDashboard", verbose=verbose)
+        self.console = Console()
+
+    def get_processing_stats(self) -> ProcessingStats:
+        """Get current processing statistics."""
+        try:
+            # This would typically query the database
+            # For now, return mock data
+            return ProcessingStats(
+                total_videos=1250,
+                total_audio=890,
+                total_playlists=45,
+                total_duration=125000.0,  # seconds
+                total_size=2.5 * 1024**3,  # 2.5 GB
+                success_rate=94.5,
+                avg_processing_time=45.2,
+                last_24h_videos=23,
+                last_24h_audio=15,
+                last_24h_playlists=3,
+            )
+        except Exception as e:
+            self.logger.error(f"Failed to get processing stats: {e}")
+            return ProcessingStats()
+
+    def get_system_health(self) -> SystemHealth:
+        """Get current system health metrics."""
+        try:
+            import psutil
+
+            return SystemHealth(
+                cpu_usage=psutil.cpu_percent(),
+                memory_usage=psutil.virtual_memory().percent,
+                disk_usage=psutil.disk_usage("/").percent,
+                active_jobs=5,
+                queue_size=12,
+                last_activity=datetime.now() - timedelta(minutes=5),
+                uptime=time.time() - psutil.boot_time(),
+            )
+        except ImportError:
+            self.logger.warning("psutil not available, using mock health data")
+            return SystemHealth(
+                cpu_usage=25.5,
+                memory_usage=68.2,
+                disk_usage=45.8,
+                active_jobs=3,
+                queue_size=8,
+                last_activity=datetime.now() - timedelta(minutes=2),
+                uptime=86400.0,  # 1 day
+            )
+        except Exception as e:
+            self.logger.error(f"Failed to get system health: {e}")
+            return SystemHealth()
+
+    def create_stats_table(self, stats: ProcessingStats) -> Table:
+        """Create processing statistics table."""
+        table = Table(
+            title="📊 Processing Statistics",
+            show_header=True,
+            header_style="bold magenta",
+        )
+
+        table.add_column("Metric", style="cyan", no_wrap=True)
+        table.add_column("Value", style="green")
+        table.add_column("Last 24h", style="yellow")
+
+        # Format file sizes
+        def format_size(size_bytes):
+            if size_bytes < 1024**2:
+                return f"{size_bytes / 1024:.1f} KB"
+            elif size_bytes < 1024**3:
+                return f"{size_bytes / (1024**2):.1f} MB"
+            else:
+                return f"{size_bytes / (1024**3):.1f} GB"
+
+        def format_duration(seconds):
+            hours = int(seconds // 3600)
+            minutes = int((seconds % 3600) // 60)
+            return f"{hours}h {minutes}m"
+
+        table.add_row(
+            "Videos Processed", str(stats.total_videos), str(stats.last_24h_videos)
+        )
+        table.add_row("Audio Files", str(stats.total_audio), str(stats.last_24h_audio))
+        table.add_row(
+            "Playlists", str(stats.total_playlists), str(stats.last_24h_playlists)
+        )
+        table.add_row("Total Duration", format_duration(stats.total_duration), "")
+        table.add_row("Total Size", format_size(stats.total_size), "")
+        table.add_row("Success Rate", f"{stats.success_rate:.1f}%", "")
+        table.add_row("Avg Processing Time", f"{stats.avg_processing_time:.1f}s", "")
+
+        return table
+
+    def create_health_table(self, health: SystemHealth) -> Table:
+        """Create system health table."""
+        table = Table(
+            title="🏥 System Health", show_header=True, header_style="bold red"
+        )
+
+        table.add_column("Metric", style="cyan", no_wrap=True)
+        table.add_column("Value", style="green")
+        table.add_column("Status", style="yellow")
+
+        def get_status_color(value, thresholds):
+            if value < thresholds[0]:
+                return "green"
+            elif value < thresholds[1]:
+                return "yellow"
+            else:
+                return "red"
+
+        def get_status_text(value, thresholds, labels):
+            if value < thresholds[0]:
+                return labels[0]
+            elif value < thresholds[1]:
+                return labels[1]
+            else:
+                return labels[2]
+
+        # CPU usage
+        cpu_status = get_status_text(
+            health.cpu_usage, [50, 80], ["Good", "Warning", "Critical"]
+        )
+        table.add_row("CPU Usage", f"{health.cpu_usage:.1f}%", cpu_status)
+
+        # Memory usage
+        memory_status = get_status_text(
+            health.memory_usage, [70, 90], ["Good", "Warning", "Critical"]
+        )
+        table.add_row("Memory Usage", f"{health.memory_usage:.1f}%", memory_status)
+
+        # Disk usage
+        disk_status = get_status_text(
+            health.disk_usage, [80, 95], ["Good", "Warning", "Critical"]
+        )
+        table.add_row("Disk Usage", f"{health.disk_usage:.1f}%", disk_status)
+
+        # Active jobs
+        table.add_row(
+            "Active Jobs",
+            str(health.active_jobs),
+            "Running" if health.active_jobs > 0 else "Idle",
+        )
+
+        # Queue size
+        queue_status = get_status_text(
+            health.queue_size, [5, 20], ["Good", "Busy", "Overloaded"]
+        )
+        table.add_row("Queue Size", str(health.queue_size), queue_status)
+
+        # Last activity
+        if health.last_activity:
+            time_ago = datetime.now() - health.last_activity
+            minutes_ago = int(time_ago.total_seconds() / 60)
+            table.add_row(
+                "Last Activity",
+                f"{minutes_ago}m ago",
+                "Active" if minutes_ago < 10 else "Idle",
+            )
+
+        # Uptime
+        uptime_hours = health.uptime / 3600
+        table.add_row(
+            "Uptime",
+            f"{uptime_hours:.1f}h",
+            "Stable" if uptime_hours > 24 else "Recent",
+        )
+
+        return table
+
+    def create_dashboard_layout(self) -> Layout:
+        """Create the main dashboard layout."""
+        layout = Layout()
+
+        # Split into main and sidebar
+        layout.split_column(
+            Layout(name="header", size=3),
+            Layout(name="main"),
+            Layout(name="footer", size=3),
+        )
+
+        # Split main into stats and health
+        layout["main"].split_row(Layout(name="stats"), Layout(name="health"))
+
+        return layout
+
+    def render_dashboard(self):
+        """Render the complete analytics dashboard."""
+        stats = self.get_processing_stats()
+        health = self.get_system_health()
+
+        layout = self.create_dashboard_layout()
+
+        # Header
+        header_text = Text("🚀 Spatelier Analytics Dashboard", style="bold blue")
+        layout["header"].update(Panel(header_text, border_style="blue"))
+
+        # Stats section
+        stats_table = self.create_stats_table(stats)
+        layout["stats"].update(
+            Panel(stats_table, title="Processing Overview", border_style="green")
+        )
+
+        # Health section
+        health_table = self.create_health_table(health)
+        layout["health"].update(
+            Panel(health_table, title="System Status", border_style="red")
+        )
+
+        # Footer
+        footer_text = Text(
+            f"Last updated: {datetime.now().strftime('%Y-%m-%d %H:%M:%S')}", style="dim"
+        )
+        layout["footer"].update(Panel(footer_text, border_style="dim"))
+
+        return layout
+
+    def show_dashboard(self, refresh_interval: int = 5):
+        """
+        Show live updating dashboard.
+
+        Args:
+            refresh_interval: Refresh interval in seconds
+        """
+        try:
+            with Live(
+                self.render_dashboard(),
+                refresh_per_second=1 / refresh_interval,
+                screen=True,
+            ) as live:
+                while True:
+                    time.sleep(refresh_interval)
+                    live.update(self.render_dashboard())
+
+        except KeyboardInterrupt:
+            self.logger.info("Dashboard closed by user")
+        except Exception as e:
+            self.logger.error(f"Dashboard error: {e}")
+
+    def export_stats(self, output_path: Path) -> bool:
+        """
+        Export statistics to JSON file.
+
+        Args:
+            output_path: Path to output JSON file
+
+        Returns:
+            True if successful, False otherwise
+        """
+        try:
+            stats = self.get_processing_stats()
+            health = self.get_system_health()
+
+            data = {
+                "timestamp": datetime.now().isoformat(),
+                "processing_stats": asdict(stats),
+                "system_health": asdict(health),
+            }
+
+            with open(output_path, "w") as f:
+                json.dump(data, f, indent=2, default=str)
+
+            self.logger.info(f"Statistics exported to {output_path}")
+            return True
+
+        except Exception as e:
+            self.logger.error(f"Failed to export stats: {e}")
+            return False
+
+
+def show_analytics_dashboard(
+    config: Config, verbose: bool = False, refresh_interval: int = 5
+):
+    """
+    Show the analytics dashboard.
+
+    Args:
+        config: Configuration instance
+        verbose: Enable verbose logging
+        refresh_interval: Refresh interval in seconds
+    """
+    dashboard = AnalyticsDashboard(config, verbose)
+    dashboard.show_dashboard(refresh_interval)
+
+
+def export_analytics_data(
+    config: Config, output_path: Path, verbose: bool = False
+) -> bool:
+    """
+    Export analytics data to file.
+
+    Args:
+        config: Configuration instance
+        output_path: Path to output file
+        verbose: Enable verbose logging
+
+    Returns:
+        True if successful, False otherwise
+    """
+    dashboard = AnalyticsDashboard(config, verbose)
+    return dashboard.export_stats(output_path)

core/base.py

@@ -0,0 +1,303 @@
+"""
+Base classes for Spatelier modules.
+
+This module provides base classes that all processing modules should inherit from.
+"""
+
+from abc import ABC, abstractmethod
+from pathlib import Path
+from typing import Any, Dict, List, Optional, Union
+
+from pydantic import BaseModel, Field
+
+from core.config import Config
+from core.logger import get_logger
+
+
+class ProcessingResult(BaseModel):
+    """Base class for processing results with enhanced error handling."""
+
+    success: bool = Field(description="Whether the operation was successful")
+    message: str = Field(description="Human-readable message about the operation")
+    output_path: Optional[Path] = Field(default=None, description="Path to output file")
+    metadata: Dict[str, Any] = Field(
+        default_factory=dict, description="Additional metadata"
+    )
+    errors: List[str] = Field(
+        default_factory=list, description="List of errors encountered"
+    )
+    warnings: List[str] = Field(
+        default_factory=list, description="List of warnings encountered"
+    )
+    temp_dir: Optional[Path] = Field(
+        default=None, description="Temporary directory used for processing"
+    )
+    duration_seconds: Optional[float] = Field(
+        default=None, description="Processing duration in seconds"
+    )
+
+    @classmethod
+    def success_result(
+        cls,
+        message: str,
+        output_path: Optional[Union[str, Path]] = None,
+        metadata: Optional[Dict[str, Any]] = None,
+        warnings: Optional[List[str]] = None,
+    ) -> "ProcessingResult":
+        """Create a successful processing result."""
+        return cls(
+            success=True,
+            message=message,
+            output_path=Path(output_path) if output_path else None,
+            metadata=metadata or {},
+            warnings=warnings or [],
+        )
+
+    @classmethod
+    def error_result(
+        cls,
+        message: str,
+        errors: Optional[List[str]] = None,
+        warnings: Optional[List[str]] = None,
+    ) -> "ProcessingResult":
+        """Create an error processing result."""
+        return cls(
+            success=False, message=message, errors=errors or [], warnings=warnings or []
+        )
+
+    @classmethod
+    def warning_result(
+        cls,
+        message: str,
+        warnings: List[str],
+        output_path: Optional[Union[str, Path]] = None,
+        metadata: Optional[Dict[str, Any]] = None,
+    ) -> "ProcessingResult":
+        """Create a result with warnings but still successful."""
+        return cls(
+            success=True,
+            message=message,
+            output_path=Path(output_path) if output_path else None,
+            metadata=metadata or {},
+            warnings=warnings,
+        )
+
+    def add_error(self, error: str):
+        """Add an error to the result."""
+        self.errors.append(error)
+        self.success = False
+
+    def add_warning(self, warning: str):
+        """Add a warning to the result."""
+        self.warnings.append(warning)
+
+    def add_metadata(self, key: str, value: Any):
+        """Add metadata to the result."""
+        self.metadata[key] = value
+
+    def has_errors(self) -> bool:
+        """Check if result has errors."""
+        return len(self.errors) > 0
+
+    def has_warnings(self) -> bool:
+        """Check if result has warnings."""
+        return len(self.warnings) > 0
+
+    def is_successful(self) -> bool:
+        """Check if result is successful (no errors)."""
+        return self.success and not self.has_errors()
+
+    def get_summary(self) -> str:
+        """Get a summary of the result."""
+        summary = f"Success: {self.success}, Message: {self.message}"
+        if self.has_errors():
+            summary += f", Errors: {len(self.errors)}"
+        if self.has_warnings():
+            summary += f", Warnings: {len(self.warnings)}"
+        if self.duration_seconds:
+            summary += f", Duration: {self.duration_seconds:.2f}s"
+        return summary
+
+
+class BaseProcessor(ABC):
+    """
+    Base class for all processors.
+
+    This class provides common functionality that all processors should have,
+    including configuration management, logging, and error handling.
+    """
+
+    def __init__(self, config: Config, verbose: bool = False):
+        """
+        Initialize the processor.
+
+        Args:
+            config: Configuration instance
+            verbose: Enable verbose logging
+        """
+        self.config = config
+        self.verbose = verbose
+        self.logger = get_logger(self.__class__.__name__, verbose=verbose)
+
+    @abstractmethod
+    def process(self, input_path: Union[str, Path], **kwargs) -> ProcessingResult:
+        """
+        Process the input and return a result.
+
+        Args:
+            input_path: Path to input file
+            **kwargs: Additional processing options
+
+        Returns:
+            ProcessingResult with operation details
+        """
+        pass
+
+    def validate_input(self, input_path: Union[str, Path]) -> bool:
+        """
+        Validate that the input file exists and is accessible.
+
+        Args:
+            input_path: Path to input file
+
+        Returns:
+            True if valid, False otherwise
+        """
+        path = Path(input_path)
+
+        if not path.exists():
+            self.logger.error(f"Input file does not exist: {path}")
+            return False
+
+        if not path.is_file():
+            self.logger.error(f"Input path is not a file: {path}")
+            return False
+
+        return True
+
+    def ensure_output_dir(self, output_path: Union[str, Path]) -> bool:
+        """
+        Ensure the output directory exists.
+
+        Args:
+            output_path: Path to output file
+
+        Returns:
+            True if directory exists or was created, False otherwise
+        """
+        output_dir = Path(output_path).parent
+
+        try:
+            output_dir.mkdir(parents=True, exist_ok=True)
+            return True
+        except Exception as e:
+            self.logger.error(f"Failed to create output directory {output_dir}: {e}")
+            return False
+
+
+class BaseDownloader(BaseProcessor):
+    """
+    Base class for download processors.
+
+    Extends BaseProcessor with download-specific functionality.
+    """
+
+    def __init__(self, config: Config, verbose: bool = False):
+        """Initialize the downloader."""
+        super().__init__(config, verbose)
+        self.supported_sites = []
+
+    @abstractmethod
+    def download(
+        self, url: str, output_path: Optional[Union[str, Path]] = None, **kwargs
+    ) -> ProcessingResult:
+        """
+        Download content from URL.
+
+        Args:
+            url: URL to download from
+            output_path: Optional output path
+            **kwargs: Additional download options
+
+        Returns:
+            ProcessingResult with download details
+        """
+        pass
+
+    def process(self, input_data: Any, **kwargs) -> ProcessingResult:
+        """Process method implementation for downloaders."""
+        if isinstance(input_data, str):
+            return self.download(input_data, **kwargs)
+        else:
+            raise ValueError("Downloaders expect URL strings as input")
+
+    def is_supported(self, url: str) -> bool:
+        """
+        Check if the URL is supported by this downloader.
+
+        Args:
+            url: URL to check
+
+        Returns:
+            True if supported, False otherwise
+        """
+        # Basic implementation - subclasses should override
+        return any(site in url.lower() for site in self.supported_sites)
+
+
+class BaseConverter(BaseProcessor):
+    """
+    Base class for format converters.
+
+    Extends BaseProcessor with conversion-specific functionality.
+    """
+
+    def __init__(self, config: Config, verbose: bool = False):
+        """Initialize the converter."""
+        super().__init__(config, verbose)
+        self.supported_input_formats = []
+        self.supported_output_formats = []
+
+    @abstractmethod
+    def convert(
+        self, input_path: Union[str, Path], output_path: Union[str, Path], **kwargs
+    ) -> ProcessingResult:
+        """
+        Convert file from one format to another.
+
+        Args:
+            input_path: Path to input file
+            output_path: Path to output file
+            **kwargs: Additional conversion options
+
+        Returns:
+            ProcessingResult with conversion details
+        """
+        pass
+
+    def process(self, input_path: Union[str, Path], **kwargs) -> ProcessingResult:
+        """Process method implementation for converters."""
+        output_path = kwargs.pop("output_path", None)
+        if not output_path:
+            raise ValueError("Converters require output_path in kwargs")
+        return self.convert(input_path, output_path, **kwargs)
+
+    def is_supported_format(
+        self, file_path: Union[str, Path], is_input: bool = True
+    ) -> bool:
+        """
+        Check if the file format is supported.
+
+        Args:
+            file_path: Path to file
+            is_input: Whether this is an input file (True) or output file (False)
+
+        Returns:
+            True if format is supported, False otherwise
+        """
+        suffix = Path(file_path).suffix.lower().lstrip(".")
+
+        if is_input:
+            return suffix in self.supported_input_formats
+        else:
+            return suffix in self.supported_output_formats