ml-dash 0.0.11__py3-none-any.whl → 0.5.9__py3-none-any.whl

ml_dash/log.py

@@ -0,0 +1,181 @@
+"""
+Log API for ML-Dash SDK.
+
+Provides fluent interface for structured logging with validation.
+"""
+
+from typing import Optional, Dict, Any, TYPE_CHECKING
+from datetime import datetime
+from enum import Enum
+
+if TYPE_CHECKING:
+    from .experiment import Experiment
+
+
+class LogLevel(Enum):
+    """
+    Standard log levels for ML-Dash.
+
+    Supported levels:
+    - INFO: Informational messages
+    - WARN: Warning messages
+    - ERROR: Error messages
+    - DEBUG: Debug messages
+    - FATAL: Fatal error messages
+    """
+    INFO = "info"
+    WARN = "warn"
+    ERROR = "error"
+    DEBUG = "debug"
+    FATAL = "fatal"
+
+    @classmethod
+    def validate(cls, level: str) -> str:
+        """
+        Validate and normalize log level.
+
+        Args:
+            level: Log level string (case-insensitive)
+
+        Returns:
+            Normalized log level string (lowercase)
+
+        Raises:
+            ValueError: If level is not one of the 5 standard levels
+
+        Example:
+            >>> LogLevel.validate("INFO")
+            "info"
+            >>> LogLevel.validate("invalid")
+            ValueError: Invalid log level: 'invalid'. Must be one of: info, warn, error, debug, fatal
+        """
+        level_lower = level.lower()
+        try:
+            return cls[level_lower.upper()].value
+        except KeyError:
+            valid_levels = ", ".join([l.value for l in cls])
+            raise ValueError(
+                f"Invalid log level: '{level}'. "
+                f"Must be one of: {valid_levels}"
+            )
+
+
+class LogBuilder:
+    """
+    Fluent builder for creating log entries.
+
+    This class is returned by Experiment.log() when no message is provided.
+    It allows for a fluent API style where metadata is set first, then
+    the log level method is called to write the log.
+
+    Example:
+        experiment.log(metadata={"epoch": 1}).info("Training started")
+        experiment.log().error("Failed", error_code=500)
+    """
+
+    def __init__(self, experiment: 'Experiment', metadata: Optional[Dict[str, Any]] = None):
+        """
+        Initialize LogBuilder.
+
+        Args:
+            experiment: Parent Experiment instance
+            metadata: Optional metadata dict from log() call
+        """
+        self._experiment = experiment
+        self._metadata = metadata
+
+    def info(self, message: str, **extra_metadata) -> None:
+        """
+        Write info level log.
+
+        Args:
+            message: Log message
+            **extra_metadata: Additional metadata as keyword arguments
+
+        Example:
+            experiment.log().info("Training started")
+            experiment.log().info("Epoch complete", epoch=1, loss=0.5)
+        """
+        self._write(LogLevel.INFO.value, message, extra_metadata)
+
+    def warn(self, message: str, **extra_metadata) -> None:
+        """
+        Write warning level log.
+
+        Args:
+            message: Log message
+            **extra_metadata: Additional metadata as keyword arguments
+
+        Example:
+            experiment.log().warn("High loss detected", loss=1.5)
+        """
+        self._write(LogLevel.WARN.value, message, extra_metadata)
+
+    def error(self, message: str, **extra_metadata) -> None:
+        """
+        Write error level log.
+
+        Args:
+            message: Log message
+            **extra_metadata: Additional metadata as keyword arguments
+
+        Example:
+            experiment.log().error("Failed to save", path="/models/checkpoint.pth")
+        """
+        self._write(LogLevel.ERROR.value, message, extra_metadata)
+
+    def debug(self, message: str, **extra_metadata) -> None:
+        """
+        Write debug level log.
+
+        Args:
+            message: Log message
+            **extra_metadata: Additional metadata as keyword arguments
+
+        Example:
+            experiment.log().debug("Memory usage", memory_mb=2500)
+        """
+        self._write(LogLevel.DEBUG.value, message, extra_metadata)
+
+    def fatal(self, message: str, **extra_metadata) -> None:
+        """
+        Write fatal level log.
+
+        Args:
+            message: Log message
+            **extra_metadata: Additional metadata as keyword arguments
+
+        Example:
+            experiment.log().fatal("Unrecoverable error", exit_code=1)
+        """
+        self._write(LogLevel.FATAL.value, message, extra_metadata)
+
+    def _write(self, level: str, message: str, extra_metadata: Dict[str, Any]) -> None:
+        """
+        Internal: Execute the actual log write.
+
+        Merges metadata from log() call with metadata from level method,
+        then writes immediately (no buffering).
+
+        Args:
+            level: Log level (already validated)
+            message: Log message
+            extra_metadata: Additional metadata from level method kwargs
+        """
+        # Merge metadata from log() call with metadata from level method
+        if self._metadata and extra_metadata:
+            final_metadata = {**self._metadata, **extra_metadata}
+        elif self._metadata:
+            final_metadata = self._metadata
+        elif extra_metadata:
+            final_metadata = extra_metadata
+        else:
+            final_metadata = None
+
+        # Write immediately (no buffering)
+        self._experiment._write_log(
+            message=message,
+            level=level,
+            metadata=final_metadata,
+            timestamp=None
+        )

ml_dash/metric.py

@@ -0,0 +1,292 @@
+"""
+Metric API - Time-series data metricing for ML experiments.
+
+Metrics are used for storing continuous data series like training metrics,
+validation losses, system measurements, etc.
+"""
+
+from typing import Dict, Any, List, Optional, TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from .experiment import Experiment
+
+
+class MetricsManager:
+    """
+    Manager for metric operations that supports both named and unnamed usage.
+
+    Supports three usage patterns:
+    1. Named via call: experiment.metrics("loss").append(value=0.5, step=1)
+    2. Named via argument: experiment.metrics.append(name="loss", value=0.5, step=1)
+    3. Unnamed: experiment.metrics.append(value=0.5, step=1)  # name=None
+
+    Usage:
+        # With explicit metric name (via call)
+        experiment.metrics("train_loss").append(value=0.5, step=100)
+
+        # With explicit metric name (via argument)
+        experiment.metrics.append(name="train_loss", value=0.5, step=100)
+
+        # Without name (uses None as metric name)
+        experiment.metrics.append(value=0.5, step=100)
+    """
+
+    def __init__(self, experiment: 'Experiment'):
+        """
+        Initialize MetricsManager.
+
+        Args:
+            experiment: Parent Experiment instance
+        """
+        self._experiment = experiment
+
+    def __call__(self, name: str, description: Optional[str] = None,
+                 tags: Optional[List[str]] = None, metadata: Optional[Dict[str, Any]] = None) -> 'MetricBuilder':
+        """
+        Get a MetricBuilder for a specific metric name.
+
+        Args:
+            name: Metric name (unique within experiment)
+            description: Optional metric description
+            tags: Optional tags for categorization
+            metadata: Optional structured metadata
+
+        Returns:
+            MetricBuilder instance for the named metric
+
+        Examples:
+            experiment.metrics("loss").append(value=0.5, step=1)
+        """
+        return MetricBuilder(self._experiment, name, description, tags, metadata)
+
+    def append(self, name: Optional[str] = None, data: Optional[Dict[str, Any]] = None, **kwargs) -> Dict[str, Any]:
+        """
+        Append a data point to a metric (name can be optional).
+
+        Args:
+            name: Metric name (optional, can be None for unnamed metrics)
+            data: Data dict (alternative to kwargs)
+            **kwargs: Data as keyword arguments
+
+        Returns:
+            Response dict with metric metadata
+
+        Examples:
+            experiment.metrics.append(name="loss", value=0.5, step=1)
+            experiment.metrics.append(value=0.5, step=1)  # name=None
+            experiment.metrics.append(name="loss", data={"value": 0.5, "step": 1})
+        """
+        if data is None:
+            data = kwargs
+        return self._experiment._append_to_metric(name, data, None, None, None)
+
+    def append_batch(self, name: Optional[str] = None, data_points: Optional[List[Dict[str, Any]]] = None,
+                     description: Optional[str] = None,
+                     tags: Optional[List[str]] = None,
+                     metadata: Optional[Dict[str, Any]] = None) -> Dict[str, Any]:
+        """
+        Append multiple data points to a metric.
+
+        Args:
+            name: Metric name (optional, can be None for unnamed metrics)
+            data_points: List of data point dicts
+            description: Optional metric description
+            tags: Optional tags for categorization
+            metadata: Optional structured metadata
+
+        Returns:
+            Response dict with metric metadata
+
+        Examples:
+            experiment.metrics.append_batch(
+                name="loss",
+                data_points=[
+                    {"value": 0.5, "step": 1},
+                    {"value": 0.4, "step": 2}
+                ]
+            )
+            experiment.metrics.append_batch(
+                data_points=[
+                    {"value": 0.5, "step": 1},
+                    {"value": 0.4, "step": 2}
+                ]
+            )  # name=None
+        """
+        if data_points is None:
+            data_points = []
+        return self._experiment._append_batch_to_metric(name, data_points, description, tags, metadata)
+
+
+class MetricBuilder:
+    """
+    Builder for metric operations.
+
+    Provides fluent API for appending, reading, and querying metric data.
+
+    Usage:
+        # Append single data point
+        experiment.metric(name="train_loss").append(value=0.5, step=100)
+
+        # Append batch
+        experiment.metric(name="train_loss").append_batch([
+            {"value": 0.5, "step": 100},
+            {"value": 0.45, "step": 101}
+        ])
+
+        # Read data
+        data = experiment.metric(name="train_loss").read(start_index=0, limit=100)
+
+        # Get statistics
+        stats = experiment.metric(name="train_loss").stats()
+    """
+
+    def __init__(self, experiment: 'Experiment', name: str, description: Optional[str] = None,
+                 tags: Optional[List[str]] = None, metadata: Optional[Dict[str, Any]] = None):
+        """
+        Initialize MetricBuilder.
+
+        Args:
+            experiment: Parent Experiment instance
+            name: Metric name (unique within experiment)
+            description: Optional metric description
+            tags: Optional tags for categorization
+            metadata: Optional structured metadata (units, type, etc.)
+        """
+        self._experiment = experiment
+        self._name = name
+        self._description = description
+        self._tags = tags
+        self._metadata = metadata
+
+    def append(self, **kwargs) -> 'MetricBuilder':
+        """
+        Append a single data point to the metric.
+
+        The data point can have any structure - common patterns:
+        - {value: 0.5, step: 100}
+        - {loss: 0.3, accuracy: 0.92, epoch: 5}
+        - {timestamp: "...", temperature: 25.5, humidity: 60}
+
+        Args:
+            **kwargs: Data point fields (flexible schema)
+
+        Returns:
+            Dict with metricId, index, bufferedDataPoints, chunkSize
+
+        Example:
+            result = experiment.metric(name="train_loss").append(value=0.5, step=100, epoch=1)
+            print(f"Appended at index {result['index']}")
+        """
+        result = self._experiment._append_to_metric(
+            name=self._name,
+            data=kwargs,
+            description=self._description,
+            tags=self._tags,
+            metadata=self._metadata
+        )
+        return result
+
+    def append_batch(self, data_points: List[Dict[str, Any]]) -> Dict[str, Any]:
+        """
+        Append multiple data points in batch (more efficient than multiple append calls).
+
+        Args:
+            data_points: List of data point dicts
+
+        Returns:
+            Dict with metricId, startIndex, endIndex, count, bufferedDataPoints, chunkSize
+
+        Example:
+            result = experiment.metric(name="metrics").append_batch([
+                {"loss": 0.5, "acc": 0.8, "step": 1},
+                {"loss": 0.4, "acc": 0.85, "step": 2},
+                {"loss": 0.3, "acc": 0.9, "step": 3}
+            ])
+            print(f"Appended {result['count']} points")
+        """
+        if not data_points:
+            raise ValueError("data_points cannot be empty")
+
+        result = self._experiment._append_batch_to_metric(
+            name=self._name,
+            data_points=data_points,
+            description=self._description,
+            tags=self._tags,
+            metadata=self._metadata
+        )
+        return result
+
+    def read(self, start_index: int = 0, limit: int = 1000) -> Dict[str, Any]:
+        """
+        Read data points from the metric by index range.
+
+        Args:
+            start_index: Starting index (inclusive, default 0)
+            limit: Maximum number of points to read (default 1000, max 10000)
+
+        Returns:
+            Dict with keys:
+            - data: List of {index: str, data: dict, createdAt: str}
+            - startIndex: Starting index
+            - endIndex: Ending index
+            - total: Number of points returned
+            - hasMore: Whether more data exists beyond this range
+
+        Example:
+            result = experiment.metric(name="train_loss").read(start_index=0, limit=100)
+            for point in result['data']:
+                print(f"Index {point['index']}: {point['data']}")
+        """
+        return self._experiment._read_metric_data(
+            name=self._name,
+            start_index=start_index,
+            limit=limit
+        )
+
+    def stats(self) -> Dict[str, Any]:
+        """
+        Get metric statistics and metadata.
+
+        Returns:
+            Dict with metric info:
+            - metricId: Unique metric ID
+            - name: Metric name
+            - description: Metric description (if set)
+            - tags: Tags list
+            - metadata: User metadata
+            - totalDataPoints: Total points (buffered + chunked)
+            - bufferedDataPoints: Points in MongoDB (hot storage)
+            - chunkedDataPoints: Points in S3 (cold storage)
+            - totalChunks: Number of chunks in S3
+            - chunkSize: Chunking threshold
+            - firstDataAt: Timestamp of first point (if data has timestamp)
+            - lastDataAt: Timestamp of last point (if data has timestamp)
+            - createdAt: Metric creation time
+            - updatedAt: Last update time
+
+        Example:
+            stats = experiment.metric(name="train_loss").stats()
+            print(f"Total points: {stats['totalDataPoints']}")
+            print(f"Buffered: {stats['bufferedDataPoints']}, Chunked: {stats['chunkedDataPoints']}")
+        """
+        return self._experiment._get_metric_stats(name=self._name)
+
+    def list_all(self) -> List[Dict[str, Any]]:
+        """
+        List all metrics in the experiment.
+
+        Returns:
+            List of metric summaries with keys:
+            - metricId: Unique metric ID
+            - name: Metric name
+            - description: Metric description
+            - tags: Tags list
+            - totalDataPoints: Total data points
+            - createdAt: Creation timestamp
+
+        Example:
+            metrics = experiment.metric().list_all()
+            for metric in metrics:
+                print(f"{metric['name']}: {metric['totalDataPoints']} points")
+        """
+        return self._experiment._list_metrics()

ml_dash/params.py

@@ -0,0 +1,188 @@
+"""
+Parameters module for ML-Dash SDK.
+
+Provides fluent API for parameter management with automatic dict flattening.
+Nested dicts are flattened to dot-notation: {"model": {"lr": 0.001}} → {"model.lr": 0.001}
+"""
+
+from typing import Dict, Any, Optional, TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from .experiment import Experiment
+
+
+class ParametersBuilder:
+    """
+    Fluent interface for parameter operations.
+
+    Usage:
+        experiment.parameters().set(model={"lr": 0.001}, optimizer="adam")
+        params = experiment.parameters().get()
+        params_nested = experiment.parameters().get(flatten=False)
+    """
+
+    def __init__(self, experiment: 'Experiment'):
+        """
+        Initialize parameters builder.
+
+        Args:
+            experiment: Parent experiment instance
+        """
+        self._experiment = experiment
+
+    def set(self, **kwargs) -> 'ParametersBuilder':
+        """
+        Set/merge parameters. Always merges with existing parameters (upsert behavior).
+
+        Nested dicts are automatically flattened:
+            set(model={"lr": 0.001, "batch_size": 32})
+            → {"model.lr": 0.001, "model.batch_size": 32}
+
+        Args:
+            **kwargs: Parameters to set (can be nested dicts)
+
+        Returns:
+            Self for potential chaining
+
+        Raises:
+            RuntimeError: If experiment is not open
+            RuntimeError: If experiment is write-protected
+
+        Examples:
+            # Set nested parameters
+            experiment.parameters().set(
+                model={"lr": 0.001, "batch_size": 32},
+                optimizer="adam"
+            )
+
+            # Merge/update specific parameters
+            experiment.parameters().set(model={"lr": 0.0001})  # Only updates model.lr
+
+            # Set flat parameters with dot notation
+            experiment.parameters().set(**{"model.lr": 0.001, "model.batch_size": 32})
+        """
+        if not self._experiment._is_open:
+            raise RuntimeError("Experiment not open. Use experiment.run.start() or context manager.")
+
+        if self._experiment._write_protected:
+            raise RuntimeError("Experiment is write-protected and cannot be modified.")
+
+        # Flatten the kwargs
+        flattened = self.flatten_dict(kwargs)
+
+        if not flattened:
+            # No parameters to set, just return
+            return self
+
+        # Write parameters through experiment
+        self._experiment._write_params(flattened)
+
+        return self
+
+    def get(self, flatten: bool = True) -> Dict[str, Any]:
+        """
+        Get parameters from the experiment.
+
+        Args:
+            flatten: If True, returns flattened dict with dot notation.
+                    If False, returns nested dict structure.
+
+        Returns:
+            Parameters dict (flattened or nested based on flatten arg)
+
+        Raises:
+            RuntimeError: If experiment is not open
+
+        Examples:
+            # Get flattened parameters
+            params = experiment.parameters().get()
+            # → {"model.lr": 0.001, "model.batch_size": 32, "optimizer": "adam"}
+
+            # Get nested parameters
+            params = experiment.parameters().get(flatten=False)
+            # → {"model": {"lr": 0.001, "batch_size": 32}, "optimizer": "adam"}
+        """
+        if not self._experiment._is_open:
+            raise RuntimeError("Experiment not open. Use experiment.open() or context manager.")
+
+        # Read parameters through experiment
+        params = self._experiment._read_params()
+
+        if params is None:
+            return {}
+
+        # Return as-is if flatten=True (stored flattened), or unflatten if needed
+        if flatten:
+            return params
+        else:
+            return self.unflatten_dict(params)
+
+    @staticmethod
+    def flatten_dict(d: Dict[str, Any], parent_key: str = '', sep: str = '.') -> Dict[str, Any]:
+        """
+        Flatten a nested dictionary into dot-notation keys.
+
+        Args:
+            d: Dictionary to flatten (can contain nested dicts)
+            parent_key: Prefix for keys (used in recursion)
+            sep: Separator character (default: '.')
+
+        Returns:
+            Flattened dictionary with dot-notation keys
+
+        Examples:
+            >>> flatten_dict({"a": {"b": 1, "c": 2}, "d": 3})
+            {"a.b": 1, "a.c": 2, "d": 3}
+
+            >>> flatten_dict({"model": {"lr": 0.001, "layers": {"hidden": 128}}})
+            {"model.lr": 0.001, "model.layers.hidden": 128}
+        """
+        items = []
+
+        for k, v in d.items():
+            new_key = f"{parent_key}{sep}{k}" if parent_key else k
+
+            if isinstance(v, dict):
+                # Recursively flatten nested dicts
+                items.extend(ParametersBuilder.flatten_dict(v, new_key, sep=sep).items())
+            else:
+                # Keep non-dict values as-is
+                items.append((new_key, v))
+
+        return dict(items)
+
+    @staticmethod
+    def unflatten_dict(d: Dict[str, Any], sep: str = '.') -> Dict[str, Any]:
+        """
+        Unflatten a dot-notation dictionary into nested structure.
+
+        Args:
+            d: Flattened dictionary with dot-notation keys
+            sep: Separator character (default: '.')
+
+        Returns:
+            Nested dictionary structure
+
+        Examples:
+            >>> unflatten_dict({"a.b": 1, "a.c": 2, "d": 3})
+            {"a": {"b": 1, "c": 2}, "d": 3}
+
+            >>> unflatten_dict({"model.lr": 0.001, "model.layers.hidden": 128})
+            {"model": {"lr": 0.001, "layers": {"hidden": 128}}}
+        """
+        result = {}
+
+        for key, value in d.items():
+            parts = key.split(sep)
+            current = result
+
+            # Navigate/create nested structure
+            for part in parts[:-1]:
+                if part not in current:
+                    current[part] = {}
+                current = current[part]
+
+            # Set the final value
+            current[parts[-1]] = value
+
+        return result