ml-dash 0.6.2rc1__py3-none-any.whl → 0.6.4__py3-none-any.whl

ml_dash/log.py

@@ -69,8 +69,8 @@ class LogBuilder:
     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)
+        exp.logs.info("Training started", epoch=1)
+        exp.logs.error("Failed", error_code=500)
     """
 
     def __init__(self, experiment: 'Experiment', metadata: Optional[Dict[str, Any]] = None):
@@ -93,8 +93,8 @@ class LogBuilder:
             **extra_metadata: Additional metadata as keyword arguments
 
         Example:
-            experiment.log().info("Training started")
-            experiment.log().info("Epoch complete", epoch=1, loss=0.5)
+            exp.log("Training started", level="info")
+            exp.log("Epoch complete", level="info", epoch=1, loss=0.5)
         """
         self._write(LogLevel.INFO.value, message, extra_metadata)
 
@@ -107,7 +107,7 @@ class LogBuilder:
             **extra_metadata: Additional metadata as keyword arguments
 
         Example:
-            experiment.log().warn("High loss detected", loss=1.5)
+            exp.logs.warn("High loss detected", loss=1.5)
         """
         self._write(LogLevel.WARN.value, message, extra_metadata)
 
@@ -120,7 +120,7 @@ class LogBuilder:
             **extra_metadata: Additional metadata as keyword arguments
 
         Example:
-            experiment.log().error("Failed to save", path="/models/checkpoint.pth")
+            exp.logs.error("Failed to save", path="/models/checkpoint.pth")
         """
         self._write(LogLevel.ERROR.value, message, extra_metadata)
 
@@ -133,7 +133,7 @@ class LogBuilder:
             **extra_metadata: Additional metadata as keyword arguments
 
         Example:
-            experiment.log().debug("Memory usage", memory_mb=2500)
+            exp.logs.debug("Memory usage", memory_mb=2500)
         """
         self._write(LogLevel.DEBUG.value, message, extra_metadata)
 

ml_dash/metric.py

@@ -1,5 +1,5 @@
 """
-Metric API - Time-series data metricing for ML experiments.
+Metric API - Time-series data logging for ML experiments.
 
 Metrics are used for storing continuous data series like training metrics,
 validation losses, system measurements, etc.
@@ -13,6 +13,203 @@ if TYPE_CHECKING:
     from .experiment import Experiment
 
 
+class BufferManager:
+    """
+    Global buffer manager for collecting metric values across prefixes.
+
+    Accumulates values via metrics("prefix").buffer(...) and computes
+    statistics when log_summary() is called.
+
+    Usage:
+        # Accumulate with prefix
+        metrics("train").buffer(loss=0.5, accuracy=0.81)
+        metrics("val").buffer(loss=0.6, accuracy=0.78)
+
+        # Log summaries (all buffered prefixes)
+        metrics.buffer.log_summary()                    # default: "mean"
+        metrics.buffer.log_summary("mean", "std", "p95")
+
+        # Log non-buffered values directly
+        metrics.log(epoch=epoch, lr=lr)
+
+        # Final flush to storage
+        metrics.flush()
+    """
+
+    # Supported aggregation functions
+    SUPPORTED_AGGS = {
+        "mean", "std", "min", "max", "count",
+        "median", "sum",
+        "p50", "p90", "p95", "p99",
+        "last", "first"
+    }
+
+    def __init__(self, metrics_manager: 'MetricsManager'):
+        """
+        Initialize BufferManager.
+
+        Args:
+            metrics_manager: Parent MetricsManager instance
+        """
+        self._metrics_manager = metrics_manager
+        # Buffers per prefix: {prefix: {key: [values]}}
+        self._buffers: Dict[Optional[str], Dict[str, List[float]]] = defaultdict(lambda: defaultdict(list))
+
+    def _store(self, prefix: Optional[str], **kwargs) -> None:
+        """
+        Store values in buffer for a specific prefix.
+
+        Args:
+            prefix: Metric prefix (e.g., "train", "val")
+            **kwargs: Metric values to buffer (e.g., loss=0.5, accuracy=0.9)
+        """
+        for key, value in kwargs.items():
+            # Handle None values gracefully
+            if value is None:
+                value = float('nan')
+            try:
+                self._buffers[prefix][key].append(float(value))
+            except (TypeError, ValueError):
+                # Skip non-numeric values silently
+                continue
+
+    def _compute_stats(self, values: List[float], aggs: tuple) -> Dict[str, float]:
+        """
+        Compute statistics for a list of values.
+
+        Args:
+            values: List of numeric values
+            aggs: Tuple of aggregation names
+
+        Returns:
+            Dict with computed statistics
+        """
+        # Filter out NaN values
+        clean_values = [v for v in values if not (isinstance(v, float) and v != v)]
+
+        if not clean_values:
+            return {}
+
+        stats = {}
+        for agg in aggs:
+            if agg == "mean":
+                stats["mean"] = statistics.mean(clean_values)
+            elif agg == "std":
+                if len(clean_values) >= 2:
+                    stats["std"] = statistics.stdev(clean_values)
+                else:
+                    stats["std"] = 0.0
+            elif agg == "min":
+                stats["min"] = min(clean_values)
+            elif agg == "max":
+                stats["max"] = max(clean_values)
+            elif agg == "count":
+                stats["count"] = len(clean_values)
+            elif agg == "median" or agg == "p50":
+                stats[agg] = statistics.median(clean_values)
+            elif agg == "sum":
+                stats["sum"] = sum(clean_values)
+            elif agg == "p90":
+                stats["p90"] = self._percentile(clean_values, 90)
+            elif agg == "p95":
+                stats["p95"] = self._percentile(clean_values, 95)
+            elif agg == "p99":
+                stats["p99"] = self._percentile(clean_values, 99)
+            elif agg == "last":
+                stats["last"] = clean_values[-1]
+            elif agg == "first":
+                stats["first"] = clean_values[0]
+
+        return stats
+
+    def _percentile(self, values: List[float], p: int) -> float:
+        """Compute percentile of values."""
+        sorted_vals = sorted(values)
+        k = (len(sorted_vals) - 1) * p / 100
+        f = int(k)
+        c = f + 1 if f + 1 < len(sorted_vals) else f
+        return sorted_vals[f] + (k - f) * (sorted_vals[c] - sorted_vals[f])
+
+    def log_summary(self, *aggs: str) -> None:
+        """
+        Compute statistics from buffered values and log them.
+
+        Args:
+            *aggs: Aggregation functions to compute. Defaults to ("mean",).
+                   Supported: "mean", "std", "min", "max", "count",
+                             "median", "sum", "p50", "p90", "p95", "p99",
+                             "last", "first"
+
+        Example:
+            metrics.buffer.log_summary()                    # default: mean
+            metrics.buffer.log_summary("mean", "std")       # mean and std
+            metrics.buffer.log_summary("mean", "p95")       # mean and 95th percentile
+        """
+        # Default to mean
+        if not aggs:
+            aggs = ("mean",)
+
+        # Validate aggregations
+        for agg in aggs:
+            if agg not in self.SUPPORTED_AGGS:
+                raise ValueError(f"Unsupported aggregation: {agg}. Supported: {self.SUPPORTED_AGGS}")
+
+        # Process each prefix's buffer
+        for prefix, buffer in list(self._buffers.items()):
+            if not buffer:
+                continue
+
+            output_data = {}
+
+            for key, values in buffer.items():
+                if not values:
+                    continue
+
+                stats = self._compute_stats(values, aggs)
+
+                # Add stats with hierarchical naming (key.agg)
+                for stat_name, stat_value in stats.items():
+                    output_data[f"{key}.{stat_name}"] = stat_value
+
+            if output_data:
+                # Log to the appropriate metric
+                self._metrics_manager(prefix).log(**output_data)
+
+        # Clear all buffers
+        self._buffers.clear()
+
+    def peek(self, prefix: Optional[str] = None, *keys: str, limit: int = 5) -> Dict[str, List[float]]:
+        """
+        Non-destructive inspection of buffered values.
+
+        Args:
+            prefix: Specific prefix to peek at (None for all)
+            *keys: Optional specific keys to peek at. If empty, shows all.
+            limit: Number of most recent values to show (default 5)
+
+        Returns:
+            Dict of buffered values (truncated to last `limit` items)
+        """
+        if prefix is not None:
+            buffer = self._buffers.get(prefix, {})
+            keys_to_show = keys if keys else buffer.keys()
+            return {
+                k: buffer[k][-limit:] if limit else buffer[k]
+                for k in keys_to_show
+                if k in buffer and buffer[k]
+            }
+        else:
+            # Return all buffers
+            result = {}
+            for p, buffer in self._buffers.items():
+                prefix_str = p if p else "(default)"
+                keys_to_show = keys if keys else buffer.keys()
+                for k in keys_to_show:
+                    if k in buffer and buffer[k]:
+                        result[f"{prefix_str}/{k}"] = buffer[k][-limit:] if limit else buffer[k]
+            return result
+
+
 class SummaryCache:
     """
     Buffer for collecting metric values and computing statistics periodically.
@@ -135,8 +332,8 @@ class SummaryCache:
         if not output_data:
             return
 
-        # Append combined data as a single metric data point
-        self._metric_builder.append(**output_data)
+        # Log combined data as a single metric data point
+        self._metric_builder.log(**output_data)
 
         # Clear buffer if requested (default behavior for "tiled" mode)
         if clear:
@@ -169,20 +366,23 @@ 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
+    Supports two usage patterns:
+    1. Named via call: experiment.metrics("train").log(loss=0.5, accuracy=0.9)
+    2. Unnamed: experiment.metrics.log(epoch=1).flush()
 
     Usage:
         # With explicit metric name (via call)
-        experiment.metrics("train_loss").append(value=0.5, step=100)
+        experiment.metrics("train").log(loss=0.5, accuracy=0.9)
 
-        # With explicit metric name (via argument)
-        experiment.metrics.append(name="train_loss", value=0.5, step=100)
+        # With epoch context (unnamed metric)
+        experiment.metrics.log(epoch=epoch).flush()
 
-        # Without name (uses None as metric name)
-        experiment.metrics.append(value=0.5, step=100)
+        # Nested dict pattern (single call for all metrics)
+        experiment.metrics.log(
+            epoch=100,
+            train=dict(loss=0.142, accuracy=0.80),
+            eval=dict(loss=0.201, accuracy=0.76)
+        )
     """
 
     def __init__(self, experiment: 'Experiment'):
@@ -194,6 +394,31 @@ class MetricsManager:
         """
         self._experiment = experiment
         self._metric_builders: Dict[str, 'MetricBuilder'] = {}  # Cache for MetricBuilder instances
+        self._buffer_manager: Optional[BufferManager] = None  # Lazy initialization
+
+    @property
+    def buffer(self) -> BufferManager:
+        """
+        Get the global BufferManager for buffered metric operations.
+
+        The buffer manager collects values across prefixes and computes
+        statistics when log_summary() is called.
+
+        Returns:
+            BufferManager instance
+
+        Example:
+            # Accumulate values
+            metrics("train").buffer(loss=0.5, accuracy=0.81)
+            metrics("val").buffer(loss=0.6, accuracy=0.78)
+
+            # Log summaries
+            metrics.buffer.log_summary()                    # default: mean
+            metrics.buffer.log_summary("mean", "std", "p95")
+        """
+        if self._buffer_manager is None:
+            self._buffer_manager = BufferManager(self)
+        return self._buffer_manager
 
     def __call__(self, name: str, description: Optional[str] = None,
                  tags: Optional[List[str]] = None, metadata: Optional[Dict[str, Any]] = None) -> 'MetricBuilder':
@@ -210,7 +435,7 @@ class MetricsManager:
             MetricBuilder instance for the named metric (same instance on repeated calls)
 
         Examples:
-            experiment.metrics("loss").append(value=0.5, step=1)
+            experiment.metrics("train").log(loss=0.5, accuracy=0.9)
 
         Note:
             MetricBuilder instances are cached by name, so repeated calls with the
@@ -219,92 +444,110 @@ class MetricsManager:
         """
         # Cache key includes name only (description/tags/metadata are set once on first call)
         if name not in self._metric_builders:
-            self._metric_builders[name] = MetricBuilder(self._experiment, name, description, tags, metadata)
+            self._metric_builders[name] = MetricBuilder(
+                self._experiment, name, description, tags, metadata,
+                metrics_manager=self
+            )
         return self._metric_builders[name]
 
-    def append(self, name: Optional[str] = None, data: Optional[Dict[str, Any]] = None, **kwargs) -> Dict[str, Any]:
+    def log(self, _flush: bool = False, **kwargs) -> 'MetricsManager':
         """
-        Append a data point to a metric (name can be optional).
+        Log a data point to the unnamed (root) metric.
+
+        Supports two patterns:
+
+        1. Simple key-value pairs:
+            experiment.metrics.log(epoch=epoch).flush()
+
+        2. Nested dict pattern (logs to multiple prefixed metrics):
+            experiment.metrics.log(
+                epoch=100,
+                train=dict(loss=0.142, accuracy=0.80),
+                eval=dict(loss=0.201, accuracy=0.76)
+            )
 
         Args:
-            name: Metric name (optional, can be None for unnamed metrics)
-            data: Data dict (alternative to kwargs)
-            **kwargs: Data as keyword arguments
+            _flush: If True, flush after logging (equivalent to calling .flush())
+            **kwargs: Data point fields. Dict values are expanded to prefixed metrics.
 
         Returns:
-            Response dict with metric metadata
+            Self for method chaining
 
         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})
+            # Log epoch context and flush
+            experiment.metrics.log(epoch=epoch).flush()
+
+            # Log with nested dicts (single call for all metrics)
+            experiment.metrics.log(
+                epoch=100,
+                train=dict(loss=0.142, accuracy=0.80),
+                eval=dict(loss=0.201, accuracy=0.76)
+            )
+
+            # Equivalent to _flush=True
+            experiment.metrics.log(epoch=100, _flush=True)
         """
-        if data is None:
-            data = kwargs
-        return self._experiment._append_to_metric(name, data, None, None, None)
+        # Separate nested dicts from scalar values
+        scalar_data = {}
+        nested_data = {}
+
+        for key, value in kwargs.items():
+            if isinstance(value, dict):
+                nested_data[key] = value
+            else:
+                scalar_data[key] = value
+
+        # Log scalar data to unnamed metric
+        if scalar_data:
+            self._experiment._append_to_metric(None, scalar_data, None, None, None)
+
+        # Log nested dicts to their respective prefixed metrics
+        for prefix, data in nested_data.items():
+            # Include scalar data (like epoch) with each nested metric
+            combined_data = {**scalar_data, **data}
+            self(prefix).log(**combined_data)
+
+        if _flush:
+            self.flush()
 
-    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]:
+        return self
+
+    def flush(self) -> 'MetricsManager':
         """
-        Append multiple data points to a metric.
+        Flush buffered data (for method chaining).
 
-        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
+        Currently a no-op as data is written immediately, but supports
+        the fluent API pattern:
+            experiment.metrics.log(epoch=epoch).flush()
 
         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
+            Self for method chaining
         """
-        if data_points is None:
-            data_points = []
-        return self._experiment._append_batch_to_metric(name, data_points, description, tags, metadata)
+        # Data is written immediately, so nothing to flush
+        # This method exists for API consistency and chaining
+        return self
 
 
 class MetricBuilder:
     """
     Builder for metric operations.
 
-    Provides fluent API for appending, reading, and querying metric data.
+    Provides fluent API for logging, 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}
-        ])
+        # Log single data point
+        experiment.metrics("train").log(loss=0.5, accuracy=0.9)
 
         # Read data
-        data = experiment.metric(name="train_loss").read(start_index=0, limit=100)
+        data = experiment.metrics("train").read(start_index=0, limit=100)
 
         # Get statistics
-        stats = experiment.metric(name="train_loss").stats()
+        stats = experiment.metrics("train").stats()
     """
 
     def __init__(self, experiment: 'Experiment', name: str, description: Optional[str] = None,
-                 tags: Optional[List[str]] = None, metadata: Optional[Dict[str, Any]] = None):
+                 tags: Optional[List[str]] = None, metadata: Optional[Dict[str, Any]] = None,
+                 metrics_manager: Optional['MetricsManager'] = None):
         """
         Initialize MetricBuilder.
 
@@ -314,71 +557,87 @@ class MetricBuilder:
             description: Optional metric description
             tags: Optional tags for categorization
             metadata: Optional structured metadata (units, type, etc.)
+            metrics_manager: Parent MetricsManager (for buffer access)
         """
         self._experiment = experiment
         self._name = name
         self._description = description
         self._tags = tags
         self._metadata = metadata
+        self._metrics_manager = metrics_manager
         self._summary_cache = None  # Lazy initialization
 
-    def append(self, **kwargs) -> 'MetricBuilder':
+    def buffer(self, **kwargs) -> 'MetricBuilder':
+        """
+        Buffer values for later aggregation via metrics.buffer.log_summary().
+
+        Values are accumulated and statistics are computed when log_summary() is called.
+
+        Args:
+            **kwargs: Metric values to buffer (e.g., loss=0.5, accuracy=0.9)
+
+        Returns:
+            Self for method chaining
+
+        Example:
+            # Accumulate values during training
+            for batch in dataloader:
+                metrics("train").buffer(loss=loss, acc=acc)
+
+            # Log summary at end of epoch
+            metrics.buffer.log_summary()        # logs loss.mean, acc.mean
+            metrics.buffer.log_summary("mean", "std")  # logs loss.mean, loss.std, etc.
+        """
+        if self._metrics_manager is None:
+            raise RuntimeError("buffer() requires MetricsManager reference")
+        self._metrics_manager.buffer._store(self._name, **kwargs)
+        return self
+
+    def log(self, **kwargs) -> 'MetricBuilder':
         """
-        Append a single data point to the metric.
+        Log a single data point to the metric.
 
         The data point can have any structure - common patterns:
+        - {loss: 0.3, accuracy: 0.92}
         - {value: 0.5, step: 100}
-        - {loss: 0.3, accuracy: 0.92, epoch: 5}
         - {timestamp: "...", temperature: 25.5, humidity: 60}
 
+        Supports method chaining for fluent API:
+            experiment.metrics("train").log(loss=0.5, accuracy=0.9)
+
         Args:
             **kwargs: Data point fields (flexible schema)
 
         Returns:
-            Dict with metricId, index, bufferedDataPoints, chunkSize
+            Self for method chaining
 
         Example:
-            result = experiment.metric(name="train_loss").append(value=0.5, step=100, epoch=1)
-            print(f"Appended at index {result['index']}")
+            experiment.metrics("train").log(loss=0.5, accuracy=0.9)
+            experiment.metrics.log(epoch=epoch).flush()
         """
-        result = self._experiment._append_to_metric(
+        self._experiment._append_to_metric(
             name=self._name,
             data=kwargs,
             description=self._description,
             tags=self._tags,
             metadata=self._metadata
         )
-        return result
+        return self
 
-    def append_batch(self, data_points: List[Dict[str, Any]]) -> Dict[str, Any]:
+    def flush(self) -> 'MetricBuilder':
         """
-        Append multiple data points in batch (more efficient than multiple append calls).
+        Flush buffered data (for method chaining).
 
-        Args:
-            data_points: List of data point dicts
+        Currently a no-op as data is written immediately, but supports
+        the fluent API pattern:
+            experiment.metrics.log(epoch=epoch).flush()
 
         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")
+            Self for method chaining
         """
-        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
+        # Data is written immediately, so nothing to flush
+        # This method exists for API consistency and chaining
+        return self
 
     def read(self, start_index: int = 0, limit: int = 1000) -> Dict[str, Any]:
         """

ml_dash/params.py

@@ -17,9 +17,9 @@ 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)
+        exp.params.set(model={"lr": 0.001}, optimizer="adam")
+        params = exp.params.get()
+        params_nested = exp.params.get(flatten=False)
     """
 
     def __init__(self, experiment: 'Experiment'):
@@ -51,16 +51,16 @@ class ParametersBuilder:
 
         Examples:
             # Set nested parameters
-            experiment.parameters().set(
+            exp.params.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
+            exp.params.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})
+            exp.params.set(**{"model.lr": 0.001, "model.batch_size": 32})
         """
         if not self._experiment._is_open:
             raise RuntimeError(