ml-dash 0.6.2__py3-none-any.whl → 0.6.2rc1__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:
-        exp.logs.info("Training started", epoch=1)
-        exp.logs.error("Failed", error_code=500)
+        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):
@@ -93,8 +93,8 @@ class LogBuilder:
             **extra_metadata: Additional metadata as keyword arguments
 
         Example:
-            exp.log("Training started", level="info")
-            exp.log("Epoch complete", level="info", epoch=1, loss=0.5)
+            experiment.log().info("Training started")
+            experiment.log().info("Epoch complete", 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:
-            exp.logs.warn("High loss detected", loss=1.5)
+            experiment.log().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:
-            exp.logs.error("Failed to save", path="/models/checkpoint.pth")
+            experiment.log().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:
-            exp.logs.debug("Memory usage", memory_mb=2500)
+            experiment.log().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 logging for ML experiments.
+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.
@@ -13,203 +13,6 @@ 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.
@@ -332,8 +135,8 @@ class SummaryCache:
         if not output_data:
             return
 
-        # Log combined data as a single metric data point
-        self._metric_builder.log(**output_data)
+        # Append combined data as a single metric data point
+        self._metric_builder.append(**output_data)
 
         # Clear buffer if requested (default behavior for "tiled" mode)
         if clear:
@@ -366,23 +169,20 @@ class MetricsManager:
     """
     Manager for metric operations that supports both named and unnamed usage.
 
-    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()
+    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").log(loss=0.5, accuracy=0.9)
+        experiment.metrics("train_loss").append(value=0.5, step=100)
 
-        # With epoch context (unnamed metric)
-        experiment.metrics.log(epoch=epoch).flush()
+        # With explicit metric name (via argument)
+        experiment.metrics.append(name="train_loss", 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)
-        )
+        # Without name (uses None as metric name)
+        experiment.metrics.append(value=0.5, step=100)
     """
 
     def __init__(self, experiment: 'Experiment'):
@@ -394,31 +194,6 @@ 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':
@@ -435,7 +210,7 @@ class MetricsManager:
             MetricBuilder instance for the named metric (same instance on repeated calls)
 
         Examples:
-            experiment.metrics("train").log(loss=0.5, accuracy=0.9)
+            experiment.metrics("loss").append(value=0.5, step=1)
 
         Note:
             MetricBuilder instances are cached by name, so repeated calls with the
@@ -444,110 +219,92 @@ 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,
-                metrics_manager=self
-            )
+            self._metric_builders[name] = MetricBuilder(self._experiment, name, description, tags, metadata)
         return self._metric_builders[name]
 
-    def log(self, _flush: bool = False, **kwargs) -> 'MetricsManager':
+    def append(self, name: Optional[str] = None, data: Optional[Dict[str, Any]] = None, **kwargs) -> Dict[str, Any]:
         """
-        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)
-            )
+        Append a data point to a metric (name can be optional).
 
         Args:
-            _flush: If True, flush after logging (equivalent to calling .flush())
-            **kwargs: Data point fields. Dict values are expanded to prefixed metrics.
+            name: Metric name (optional, can be None for unnamed metrics)
+            data: Data dict (alternative to kwargs)
+            **kwargs: Data as keyword arguments
 
         Returns:
-            Self for method chaining
+            Response dict with metric metadata
 
         Examples:
-            # 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)
+            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})
         """
-        # 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()
+        if data is None:
+            data = kwargs
+        return self._experiment._append_to_metric(name, data, None, None, None)
 
-        return self
-
-    def flush(self) -> 'MetricsManager':
+    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]:
         """
-        Flush buffered data (for method chaining).
+        Append multiple data points to a metric.
 
-        Currently a no-op as data is written immediately, but supports
-        the fluent API pattern:
-            experiment.metrics.log(epoch=epoch).flush()
+        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:
-            Self for method chaining
+            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
         """
-        # Data is written immediately, so nothing to flush
-        # This method exists for API consistency and chaining
-        return self
+        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 logging, reading, and querying metric data.
+    Provides fluent API for appending, reading, and querying metric data.
 
     Usage:
-        # Log single data point
-        experiment.metrics("train").log(loss=0.5, accuracy=0.9)
+        # 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.metrics("train").read(start_index=0, limit=100)
+        data = experiment.metric(name="train_loss").read(start_index=0, limit=100)
 
         # Get statistics
-        stats = experiment.metrics("train").stats()
+        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,
-                 metrics_manager: Optional['MetricsManager'] = None):
+                 tags: Optional[List[str]] = None, metadata: Optional[Dict[str, Any]] = None):
         """
         Initialize MetricBuilder.
 
@@ -557,87 +314,71 @@ 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 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':
+    def append(self, **kwargs) -> 'MetricBuilder':
         """
-        Log a single data point to the metric.
+        Append 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:
-            Self for method chaining
+            Dict with metricId, index, bufferedDataPoints, chunkSize
 
         Example:
-            experiment.metrics("train").log(loss=0.5, accuracy=0.9)
-            experiment.metrics.log(epoch=epoch).flush()
+            result = experiment.metric(name="train_loss").append(value=0.5, step=100, epoch=1)
+            print(f"Appended at index {result['index']}")
         """
-        self._experiment._append_to_metric(
+        result = self._experiment._append_to_metric(
             name=self._name,
             data=kwargs,
             description=self._description,
             tags=self._tags,
             metadata=self._metadata
         )
-        return self
+        return result
 
-    def flush(self) -> 'MetricBuilder':
+    def append_batch(self, data_points: List[Dict[str, Any]]) -> Dict[str, Any]:
         """
-        Flush buffered data (for method chaining).
+        Append multiple data points in batch (more efficient than multiple append calls).
 
-        Currently a no-op as data is written immediately, but supports
-        the fluent API pattern:
-            experiment.metrics.log(epoch=epoch).flush()
+        Args:
+            data_points: List of data point dicts
 
         Returns:
-            Self for method chaining
+            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")
         """
-        # Data is written immediately, so nothing to flush
-        # This method exists for API consistency and chaining
-        return self
+        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]:
         """

ml_dash/params.py

@@ -17,9 +17,9 @@ class ParametersBuilder:
     Fluent interface for parameter operations.
 
     Usage:
-        exp.params.set(model={"lr": 0.001}, optimizer="adam")
-        params = exp.params.get()
-        params_nested = exp.params.get(flatten=False)
+        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'):
@@ -51,16 +51,16 @@ class ParametersBuilder:
 
         Examples:
             # Set nested parameters
-            exp.params.set(
+            experiment.parameters().set(
                 model={"lr": 0.001, "batch_size": 32},
                 optimizer="adam"
             )
 
             # Merge/update specific parameters
-            exp.params.set(model={"lr": 0.0001})  # Only updates model.lr
+            experiment.parameters().set(model={"lr": 0.0001})  # Only updates model.lr
 
             # Set flat parameters with dot notation
-            exp.params.set(**{"model.lr": 0.001, "model.batch_size": 32})
+            experiment.parameters().set(**{"model.lr": 0.001, "model.batch_size": 32})
         """
         if not self._experiment._is_open:
             raise RuntimeError(