ml4t-diagnostic 0.1.0a1__py3-none-any.whl

ml4t/diagnostic/logging/logger.py

@@ -0,0 +1,245 @@
+"""
+Structured Logging for ML4T Diagnostic
+
+Provides configurable logging with levels, JSON output, and context preservation.
+"""
+
+import json
+import logging
+import sys
+from datetime import datetime
+from enum import Enum
+
+
+class LogLevel(str, Enum):
+    """Log level enumeration."""
+
+    DEBUG = "DEBUG"
+    INFO = "INFO"
+    WARNING = "WARNING"
+    ERROR = "ERROR"
+
+
+class QEvalLogger:
+    """
+    Structured logger for ML4T Diagnostic operations.
+
+    Provides:
+    - Configurable log levels
+    - JSON-structured output
+    - Context preservation
+    - Performance timing
+    - Debug mode support
+
+    Example:
+        >>> logger = QEvalLogger("mlquant.evaluation.metrics")
+        >>> logger.info("Computing metric", metric="sharpe_ratio", n_samples=100)
+        >>> logger.debug("Intermediate result", value=0.5)
+        >>> logger.error("Computation failed", error="division by zero")
+    """
+
+    def __init__(self, name: str, level: LogLevel = LogLevel.INFO, output_json: bool = False):
+        """
+        Initialize logger.
+
+        Args:
+            name: Logger name (usually module name)
+            level: Minimum log level to display
+            output_json: Whether to output JSON format
+        """
+        self.name = name
+        self.level = level
+        self.output_json = output_json
+        self._python_logger = logging.getLogger(name)
+        self._configure_python_logger()
+
+    def _configure_python_logger(self):
+        """Configure underlying Python logger."""
+        # Map our levels to Python logging levels
+        level_map = {
+            LogLevel.DEBUG: logging.DEBUG,
+            LogLevel.INFO: logging.INFO,
+            LogLevel.WARNING: logging.WARNING,
+            LogLevel.ERROR: logging.ERROR,
+        }
+        self._python_logger.setLevel(level_map[self.level])
+
+        # Add handler if none exists
+        if not self._python_logger.handlers:
+            handler = logging.StreamHandler(sys.stderr)
+            handler.setFormatter(
+                logging.Formatter("%(asctime)s - %(name)s - %(levelname)s - %(message)s")
+            )
+            self._python_logger.addHandler(handler)
+
+    def _format_message(self, level: str, message: str, **context) -> str:
+        """
+        Format log message.
+
+        Args:
+            level: Log level
+            message: Log message
+            **context: Additional context fields
+
+        Returns:
+            Formatted message string
+        """
+        if self.output_json:
+            log_entry = {
+                "timestamp": datetime.now().isoformat(),
+                "logger": self.name,
+                "level": level,
+                "message": message,
+                **context,
+            }
+            return json.dumps(log_entry)
+        else:
+            # Human-readable format
+            context_str = " ".join(f"{k}={v}" for k, v in context.items())
+            if context_str:
+                return f"{message} ({context_str})"
+            return message
+
+    def debug(self, message: str, **context):
+        """
+        Log debug message.
+
+        Args:
+            message: Debug message
+            **context: Additional context
+        """
+        if self._should_log(LogLevel.DEBUG):
+            formatted = self._format_message("DEBUG", message, **context)
+            self._python_logger.debug(formatted)
+
+    def info(self, message: str, **context):
+        """
+        Log info message.
+
+        Args:
+            message: Info message
+            **context: Additional context
+        """
+        if self._should_log(LogLevel.INFO):
+            formatted = self._format_message("INFO", message, **context)
+            self._python_logger.info(formatted)
+
+    def warning(self, message: str, **context):
+        """
+        Log warning message.
+
+        Args:
+            message: Warning message
+            **context: Additional context
+        """
+        if self._should_log(LogLevel.WARNING):
+            formatted = self._format_message("WARNING", message, **context)
+            self._python_logger.warning(formatted)
+
+    def error(self, message: str, **context):
+        """
+        Log error message.
+
+        Args:
+            message: Error message
+            **context: Additional context
+        """
+        if self._should_log(LogLevel.ERROR):
+            formatted = self._format_message("ERROR", message, **context)
+            self._python_logger.error(formatted)
+
+    def _should_log(self, level: LogLevel) -> bool:
+        """Check if message should be logged at given level."""
+        level_order = [LogLevel.DEBUG, LogLevel.INFO, LogLevel.WARNING, LogLevel.ERROR]
+        return level_order.index(level) >= level_order.index(self.level)
+
+    def timed(self, operation: str):
+        """
+        Context manager for timing operations.
+
+        Args:
+            operation: Operation name
+
+        Example:
+            >>> with logger.timed("compute_sharpe"):
+            ...     result = compute_sharpe_ratio(returns)
+        """
+        from .performance import PerformanceTracker
+
+        return PerformanceTracker(operation, logger=self)
+
+
+# Global logger registry
+_loggers: dict[str, QEvalLogger] = {}
+_global_level: LogLevel = LogLevel.INFO
+_global_json_output: bool = False
+
+
+def get_logger(name: str) -> QEvalLogger:
+    """
+    Get or create logger for module.
+
+    Args:
+        name: Logger name (usually __name__)
+
+    Returns:
+        QEvalLogger instance
+
+    Example:
+        >>> logger = get_logger(__name__)
+        >>> logger.info("Processing data")
+    """
+    if name not in _loggers:
+        _loggers[name] = QEvalLogger(name, level=_global_level, output_json=_global_json_output)
+    return _loggers[name]
+
+
+def set_log_level(level: LogLevel):
+    """
+    Set global log level.
+
+    Args:
+        level: Minimum log level
+
+    Example:
+        >>> set_log_level(LogLevel.DEBUG)
+    """
+    global _global_level
+    _global_level = level
+
+    # Update existing loggers
+    for logger in _loggers.values():
+        logger.level = level
+        logger._configure_python_logger()
+
+
+def get_log_level() -> LogLevel:
+    """
+    Get current global log level.
+
+    Returns:
+        Current log level
+    """
+    return _global_level
+
+
+def configure_logging(level: LogLevel = LogLevel.INFO, output_json: bool = False):
+    """
+    Configure global logging settings.
+
+    Args:
+        level: Minimum log level
+        output_json: Whether to output JSON format
+
+    Example:
+        >>> configure_logging(LogLevel.DEBUG, output_json=True)
+    """
+    global _global_level, _global_json_output
+    _global_level = level
+    _global_json_output = output_json
+
+    # Update existing loggers
+    for logger in _loggers.values():
+        logger.level = level
+        logger.output_json = output_json
+        logger._configure_python_logger()

ml4t/diagnostic/logging/performance.py

@@ -0,0 +1,234 @@
+"""
+Performance Metrics Tracking
+
+Provides timing and performance measurement utilities.
+"""
+
+import time
+from contextlib import contextmanager
+from functools import wraps
+from typing import Any
+
+
+class PerformanceTracker:
+    """
+    Context manager for timing operations.
+
+    Example:
+        >>> with PerformanceTracker("sharpe_computation") as tracker:
+        ...     result = compute_sharpe_ratio(returns)
+        >>> print(f"Elapsed: {tracker.elapsed:.3f}s")
+    """
+
+    def __init__(self, operation: str, logger: Any | None = None):
+        """
+        Initialize performance tracker.
+
+        Args:
+            operation: Operation name
+            logger: Optional logger to record timing
+        """
+        self.operation = operation
+        self.logger = logger
+        self.start_time: float | None = None
+        self.end_time: float | None = None
+
+    def __enter__(self):
+        """Start timing."""
+        self.start_time = time.time()
+        if self.logger:
+            self.logger.debug(f"Starting {self.operation}")
+        return self
+
+    def __exit__(self, exc_type, exc_val, exc_tb):
+        """Stop timing and log result."""
+        self.end_time = time.time()
+
+        if self.logger:
+            if exc_type is None:
+                self.logger.info(f"Completed {self.operation}", elapsed_seconds=self.elapsed)
+            else:
+                self.logger.error(
+                    f"Failed {self.operation}", elapsed_seconds=self.elapsed, error=str(exc_val)
+                )
+
+    @property
+    def elapsed(self) -> float:
+        """
+        Get elapsed time in seconds.
+
+        Returns:
+            Elapsed time (0 if not complete)
+        """
+        if self.start_time is None:
+            return 0.0
+
+        end = self.end_time if self.end_time else time.time()
+        return end - self.start_time
+
+
+def timed(func):
+    """
+    Decorator to time function execution.
+
+    Args:
+        func: Function to time
+
+    Returns:
+        Wrapped function that logs execution time
+
+    Example:
+        >>> @timed
+        ... def compute_sharpe(returns):
+        ...     return returns.mean() / returns.std()
+    """
+
+    @wraps(func)
+    def wrapper(*args, **kwargs):
+        start = time.time()
+        try:
+            result = func(*args, **kwargs)
+            elapsed = time.time() - start
+            print(f"{func.__name__}: {elapsed:.3f}s", flush=True)
+            return result
+        except Exception as e:
+            elapsed = time.time() - start
+            print(f"{func.__name__} failed after {elapsed:.3f}s: {e}", flush=True)
+            raise
+
+    return wrapper
+
+
+class PerformanceMonitor:
+    """
+    Monitor and aggregate performance metrics.
+
+    Example:
+        >>> monitor = PerformanceMonitor()
+        >>> with monitor.track("operation1"):
+        ...     do_work()
+        >>> with monitor.track("operation2"):
+        ...     do_more_work()
+        >>> print(monitor.summary())
+    """
+
+    def __init__(self):
+        """Initialize performance monitor."""
+        self.metrics: dict[str, list[float]] = {}
+
+    def track(self, operation: str):
+        """
+        Track operation timing.
+
+        Args:
+            operation: Operation name
+
+        Returns:
+            Context manager for timing
+
+        Example:
+            >>> with monitor.track("compute"):
+            ...     result = expensive_computation()
+        """
+        return _MonitoredOperation(self, operation)
+
+    def record(self, operation: str, elapsed: float):
+        """
+        Record timing for operation.
+
+        Args:
+            operation: Operation name
+            elapsed: Elapsed time in seconds
+        """
+        if operation not in self.metrics:
+            self.metrics[operation] = []
+        self.metrics[operation].append(elapsed)
+
+    def summary(self) -> dict[str, dict[str, float]]:
+        """
+        Get summary statistics for all operations.
+
+        Returns:
+            Dict mapping operation name to statistics
+                (count, total, mean, min, max)
+
+        Example:
+            >>> stats = monitor.summary()
+            >>> print(stats["compute"]["mean"])
+            0.523
+        """
+        summary = {}
+
+        for operation, timings in self.metrics.items():
+            if timings:
+                summary[operation] = {
+                    "count": len(timings),
+                    "total": sum(timings),
+                    "mean": sum(timings) / len(timings),
+                    "min": min(timings),
+                    "max": max(timings),
+                }
+
+        return summary
+
+    def reset(self):
+        """Clear all metrics."""
+        self.metrics.clear()
+
+
+class _MonitoredOperation:
+    """Internal context manager for PerformanceMonitor."""
+
+    def __init__(self, monitor: PerformanceMonitor, operation: str):
+        self.monitor = monitor
+        self.operation = operation
+        self.start_time: float | None = None
+
+    def __enter__(self):
+        self.start_time = time.time()
+        return self
+
+    def __exit__(self, exc_type, exc_val, exc_tb):
+        if self.start_time:
+            elapsed = time.time() - self.start_time
+            self.monitor.record(self.operation, elapsed)
+
+
+# Global performance monitor instance
+_global_monitor = PerformanceMonitor()
+
+
+def get_performance_monitor() -> PerformanceMonitor:
+    """
+    Get global performance monitor.
+
+    Returns:
+        Global PerformanceMonitor instance
+
+    Example:
+        >>> monitor = get_performance_monitor()
+        >>> with monitor.track("operation"):
+        ...     do_work()
+    """
+    return _global_monitor
+
+
+@contextmanager
+def measure_time(operation: str):
+    """
+    Context manager to measure and print operation time.
+
+    Args:
+        operation: Operation name
+
+    Example:
+        >>> with measure_time("data_loading"):
+        ...     data = load_large_dataset()
+        data_loading: 2.345s
+    """
+    start = time.time()
+    try:
+        yield
+    finally:
+        elapsed = time.time() - start
+        print(f"{operation}: {elapsed:.3f}s", flush=True)

ml4t/diagnostic/logging/progress.py

@@ -0,0 +1,234 @@
+"""
+Progress Indicators for Long-Running Operations
+
+Provides progress bars and indicators for batch operations.
+"""
+
+import sys
+import time
+from collections.abc import Iterable, Sized
+from contextlib import contextmanager
+from typing import Any, cast
+
+
+class ProgressBar:
+    """
+    Simple progress bar for terminal output.
+
+    Example:
+        >>> progress = ProgressBar(total=100, description="Processing")
+        >>> for i in range(100):
+        ...     progress.update(1)
+        >>> progress.close()
+    """
+
+    def __init__(
+        self,
+        total: int,
+        description: str = "",
+        width: int = 50,
+        show_percentage: bool = True,
+        show_count: bool = True,
+    ):
+        """
+        Initialize progress bar.
+
+        Args:
+            total: Total number of items
+            description: Progress description
+            width: Width of progress bar in characters
+            show_percentage: Show percentage complete
+            show_count: Show current/total count
+        """
+        self.total = total
+        self.description = description
+        self.width = width
+        self.show_percentage = show_percentage
+        self.show_count = show_count
+        self.current = 0
+        self.start_time = time.time()
+
+    def update(self, n: int = 1):
+        """
+        Update progress by n items.
+
+        Args:
+            n: Number of items processed
+        """
+        self.current += n
+        self._render()
+
+    def _render(self):
+        """Render progress bar to terminal."""
+        # Calculate percentage
+        percentage = self.current / self.total if self.total > 0 else 0
+
+        # Build progress bar
+        filled = int(self.width * percentage)
+        bar = "█" * filled + "░" * (self.width - filled)
+
+        # Build status text
+        parts = []
+        if self.description:
+            parts.append(self.description)
+
+        parts.append(f"[{bar}]")
+
+        if self.show_percentage:
+            parts.append(f"{percentage * 100:.1f}%")
+
+        if self.show_count:
+            parts.append(f"({self.current}/{self.total})")
+
+        # Add elapsed time
+        elapsed = time.time() - self.start_time
+        if elapsed > 1:
+            parts.append(f"{elapsed:.1f}s")
+
+        # Write to stderr (doesn't interfere with stdout)
+        sys.stderr.write("\r" + " ".join(parts))
+        sys.stderr.flush()
+
+    def close(self):
+        """Close progress bar and move to next line."""
+        sys.stderr.write("\n")
+        sys.stderr.flush()
+
+    def __enter__(self):
+        """Context manager entry."""
+        return self
+
+    def __exit__(self, exc_type, exc_val, exc_tb):
+        """Context manager exit."""
+        self.close()
+
+
+@contextmanager
+def progress_indicator(iterable: Iterable[Any], total: int | None = None, description: str = ""):
+    """
+    Context manager for iterating with progress indicator.
+
+    Args:
+        iterable: Items to iterate over
+        total: Total number of items (or len(iterable))
+        description: Progress description
+
+    Yields:
+        Items from iterable with progress updates
+
+    Example:
+        >>> items = range(100)
+        >>> with progress_indicator(items, description="Processing") as progress:
+        ...     for item in progress:
+        ...         process(item)
+    """
+    # Try to get length if not provided
+    if total is None:
+        if hasattr(iterable, "__len__"):
+            total = len(cast(Sized, iterable))
+        else:
+            total = 0  # Unknown length
+
+    progress = ProgressBar(total=total, description=description)
+
+    try:
+        for item in iterable:
+            yield item
+            progress.update(1)
+    finally:
+        progress.close()
+
+
+def spinner(description: str = "Working"):
+    """
+    Simple spinner for indefinite operations.
+
+    Args:
+        description: Operation description
+
+    Example:
+        >>> spin = spinner("Computing")
+        >>> next(spin)  # Show next frame
+        >>> next(spin)
+        >>> # When done, just stop calling next()
+    """
+    frames = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"]
+    i = 0
+
+    while True:
+        frame = frames[i % len(frames)]
+        sys.stderr.write(f"\r{frame} {description}")
+        sys.stderr.flush()
+        i += 1
+        yield
+
+
+class ProgressTracker:
+    """
+    Track progress across multiple stages.
+
+    Example:
+        >>> tracker = ProgressTracker(["load", "process", "save"])
+        >>> tracker.start("load")
+        >>> # ... loading ...
+        >>> tracker.complete("load")
+        >>> tracker.start("process")
+        >>> # ... processing ...
+        >>> tracker.complete("process")
+    """
+
+    def __init__(self, stages: list[str]):
+        """
+        Initialize progress tracker.
+
+        Args:
+            stages: List of stage names
+        """
+        self.stages = stages
+        self.current_stage: str | None = None
+        self.completed_stages: set[str] = set()
+        self.start_times: dict[str, float] = {}
+
+    def start(self, stage: str):
+        """
+        Start a stage.
+
+        Args:
+            stage: Stage name
+        """
+        if stage not in self.stages:
+            raise ValueError(f"Unknown stage: {stage}")
+
+        self.current_stage = stage
+        self.start_times[stage] = time.time()
+
+        # Display progress
+        current_idx = self.stages.index(stage)
+        total = len(self.stages)
+        print(f"[{current_idx + 1}/{total}] Starting: {stage}", file=sys.stderr)
+
+    def complete(self, stage: str):
+        """
+        Mark stage as complete.
+
+        Args:
+            stage: Stage name
+        """
+        self.completed_stages.add(stage)
+        self.current_stage = None
+
+        # Display completion
+        if stage in self.start_times:
+            elapsed = time.time() - self.start_times[stage]
+            print(f"✓ Completed: {stage} ({elapsed:.2f}s)", file=sys.stderr)
+
+    def progress(self) -> float:
+        """
+        Get overall progress (0.0 to 1.0).
+
+        Returns:
+            Progress fraction
+        """
+        if not self.stages:
+            return 1.0
+        return len(self.completed_stages) / len(self.stages)