ml-dash 0.6.14__tar.gz → 0.6.16__tar.gz

{ml_dash-0.6.14 → ml_dash-0.6.16}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: ml-dash
-Version: 0.6.14
+Version: 0.6.16
 Summary: ML experiment tracking and data storage
 Keywords: machine-learning,experiment-tracking,mlops,data-storage
 Author: Ge Yang, Tom Tao

{ml_dash-0.6.14 → ml_dash-0.6.16}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "ml-dash"
-version = "0.6.14"
+version = "0.6.16"
 description = "ML experiment tracking and data storage"
 readme = "README.md"
 requires-python = ">=3.9"

ml_dash-0.6.16/src/ml_dash/__init__.py

@@ -0,0 +1,121 @@
+"""
+ML-Dash Python SDK
+
+A simple and flexible SDK for ML experiment metricing and data storage.
+
+Prefix format: {owner}/{project}/path.../[name]
+  - owner: First segment (e.g., your username)
+  - project: Second segment (e.g., project name)
+  - path: Remaining segments form the folder structure
+  - name: Derived from last segment (may be a seed/id)
+
+Usage:
+
+    from ml_dash import Experiment
+
+    # Local mode - explicit configuration
+    with Experiment(
+        prefix="ge/my-project/experiments/exp1",
+        dash_root=".dash"
+    ).run as exp:
+        exp.log("Training started")
+        exp.params.set(lr=0.001)
+        exp.metrics("train").log(loss=0.5, step=0)
+
+    # Default: Remote mode (defaults to https://api.dash.ml)
+    with Experiment(prefix="ge/my-project/experiments/exp1").run as exp:
+        exp.log("Training started")
+        exp.params.set(lr=0.001)
+        exp.metrics("train").log(loss=0.5, step=0)
+
+    # Decorator style
+    from ml_dash import ml_dash_experiment
+
+    @ml_dash_experiment(prefix="ge/my-project/experiments/exp1")
+    def train_model(exp):
+        exp.log("Training started")
+"""
+
+from .client import RemoteClient, userinfo
+from .experiment import Experiment, OperationMode, ml_dash_experiment
+from .log import LogBuilder, LogLevel
+from .params import ParametersBuilder
+from .run import RUN
+from .storage import LocalStorage
+
+__version__ = "0.6.16"
+
+
+def _check_version_compatibility():
+    """
+    Enforce strict version requirement by checking against PyPI.
+
+    Raises ImportError if installed version is older than the latest on PyPI.
+    This ensures all users are on the latest version with newest features and bug fixes.
+    """
+    try:
+        from packaging import version
+        import httpx
+    except ImportError:
+        # If packaging or httpx not available, skip check
+        return
+
+    try:
+        # Check PyPI for latest version (with short timeout)
+        response = httpx.get(
+            "https://pypi.org/pypi/ml-dash/json",
+            timeout=2.0,
+            follow_redirects=True
+        )
+
+        if response.status_code == 200:
+            latest_version = response.json()["info"]["version"]
+            current = version.parse(__version__)
+            latest = version.parse(latest_version)
+
+            if current < latest:
+                raise ImportError(
+                    f"\n"
+                    f"{'=' * 80}\n"
+                    f"ERROR: ml-dash version {__version__} is outdated!\n"
+                    f"{'=' * 80}\n"
+                    f"\n"
+                    f"Your installed version ({__version__}) is no longer supported.\n"
+                    f"Latest version on PyPI: {latest_version}\n"
+                    f"\n"
+                    f"Please upgrade to the latest version:\n"
+                    f"\n"
+                    f"  pip install --upgrade ml-dash\n"
+                    f"\n"
+                    f"Or with uv:\n"
+                    f"\n"
+                    f"  uv pip install --upgrade ml-dash\n"
+                    f"  uv sync --upgrade-package ml-dash\n"
+                    f"\n"
+                    f"{'=' * 80}\n"
+                )
+    except (httpx.TimeoutException, httpx.ConnectError, KeyError):
+        # Silently skip check if PyPI is unreachable or response is malformed
+        # Don't block users due to network issues
+        pass
+    except Exception:
+        # Catch any other errors and silently continue
+        # Better to let users work than block on unexpected errors
+        pass
+
+
+# Enforce version check on import
+_check_version_compatibility()
+
+__all__ = [
+  "Experiment",
+  "ml_dash_experiment",
+  "OperationMode",
+  "RemoteClient",
+  "LocalStorage",
+  "LogLevel",
+  "LogBuilder",
+  "ParametersBuilder",
+  "RUN",
+  "userinfo",
+]

{ml_dash-0.6.14 → ml_dash-0.6.16}/src/ml_dash/buffer.py

@@ -57,6 +57,11 @@ def _serialize_value(value: Any) -> Any:
 class BufferConfig:
     """Configuration for buffering behavior."""
 
+    # Internal constants for queue management (not exposed to users)
+    _MAX_QUEUE_SIZE = 100000  # Maximum items before blocking
+    _WARNING_THRESHOLD = 80000  # Warn at 80% capacity
+    _AGGRESSIVE_FLUSH_THRESHOLD = 50000  # Trigger immediate flush at 50% capacity
+
     def __init__(
         self,
         flush_interval: float = 5.0,
@@ -114,17 +119,20 @@ class BackgroundBufferManager:
         self._experiment = experiment
         self._config = config
 
-        # Resource-specific queues
-        self._log_queue: Queue = Queue()
+        # Resource-specific queues with bounded size to prevent OOM
+        self._log_queue: Queue = Queue(maxsize=config._MAX_QUEUE_SIZE)
         self._metric_queues: Dict[Optional[str], Queue] = {}  # Per-metric queues
         self._track_buffers: Dict[str, Dict[float, Dict[str, Any]]] = {}  # Per-topic: {timestamp: merged_data}
-        self._file_queue: Queue = Queue()
+        self._file_queue: Queue = Queue(maxsize=config._MAX_QUEUE_SIZE)
 
         # Track last flush times per resource type
         self._last_log_flush = time.time()
         self._last_metric_flush: Dict[Optional[str], float] = {}
         self._last_track_flush: Dict[str, float] = {}  # Per-topic flush times
 
+        # Track warnings to avoid spamming
+        self._warned_queues: set = set()
+
         # Background thread control
         self._thread: Optional[threading.Thread] = None
         self._stop_event = threading.Event()
@@ -184,6 +192,34 @@ class BackgroundBufferManager:
 
         self._thread = None
 
+    def _check_queue_pressure(self, queue: Queue, queue_name: str) -> None:
+        """
+        Check queue size and trigger aggressive flushing if needed.
+
+        This prevents OOM by flushing immediately when queue fills up.
+
+        Args:
+            queue: The queue to check
+            queue_name: Name for warning messages
+        """
+        qsize = queue.qsize()
+
+        # Trigger immediate flush if queue is getting full
+        if qsize >= self._config._AGGRESSIVE_FLUSH_THRESHOLD:
+            self._flush_event.set()
+
+        # Warn once if queue is filling up (80% capacity)
+        if qsize >= self._config._WARNING_THRESHOLD:
+            if queue_name not in self._warned_queues:
+                warnings.warn(
+                    f"[ML-Dash] {queue_name} queue is {qsize}/{self._config._MAX_QUEUE_SIZE} full. "
+                    f"Data is being generated faster than it can be flushed. "
+                    f"Consider reducing logging frequency or the background flush will block to prevent OOM.",
+                    RuntimeWarning,
+                    stacklevel=3
+                )
+                self._warned_queues.add(queue_name)
+
     def buffer_log(
         self,
         message: str,
@@ -192,7 +228,10 @@ class BackgroundBufferManager:
         timestamp: Optional[datetime],
     ) -> None:
         """
-        Add log to buffer (non-blocking).
+        Add log to buffer with automatic backpressure.
+
+        If queue is full, this will block until space is available.
+        This prevents OOM when logs are generated faster than they can be flushed.
 
         Args:
             message: Log message
@@ -200,6 +239,9 @@ class BackgroundBufferManager:
             metadata: Optional metadata
             timestamp: Optional timestamp
         """
+        # Check queue pressure and trigger aggressive flushing if needed
+        self._check_queue_pressure(self._log_queue, "Log")
+
         log_entry = {
             "timestamp": (timestamp or datetime.utcnow()).isoformat() + "Z",
             "level": level,
@@ -209,6 +251,7 @@ class BackgroundBufferManager:
         if metadata:
             log_entry["metadata"] = metadata
 
+        # Will block if queue is full (backpressure to prevent OOM)
         self._log_queue.put(log_entry)
 
     def buffer_metric(
@@ -220,7 +263,10 @@ class BackgroundBufferManager:
         metadata: Optional[Dict[str, Any]],
     ) -> None:
         """
-        Add metric datapoint to buffer (non-blocking).
+        Add metric datapoint to buffer with automatic backpressure.
+
+        If queue is full, this will block until space is available.
+        This prevents OOM when metrics are generated faster than they can be flushed.
 
         Args:
             metric_name: Metric name (can be None for unnamed metrics)
@@ -229,11 +275,18 @@ class BackgroundBufferManager:
             tags: Optional tags
             metadata: Optional metadata
         """
-        # Get or create queue for this metric
+        # Get or create queue for this metric (with bounded size)
         if metric_name not in self._metric_queues:
-            self._metric_queues[metric_name] = Queue()
+            self._metric_queues[metric_name] = Queue(maxsize=self._config._MAX_QUEUE_SIZE)
             self._last_metric_flush[metric_name] = time.time()
 
+        # Check queue pressure and trigger aggressive flushing if needed
+        metric_display = f"'{metric_name}'" if metric_name else "unnamed"
+        self._check_queue_pressure(
+            self._metric_queues[metric_name],
+            f"Metric {metric_display}"
+        )
+
         metric_entry = {
             "data": data,
             "description": description,
@@ -241,6 +294,7 @@ class BackgroundBufferManager:
             "metadata": metadata,
         }
 
+        # Will block if queue is full (backpressure to prevent OOM)
         self._metric_queues[metric_name].put(metric_entry)
 
     def buffer_track(
@@ -286,7 +340,9 @@ class BackgroundBufferManager:
         size_bytes: int,
     ) -> None:
         """
-        Add file upload to queue (non-blocking).
+        Add file upload to queue with automatic backpressure.
+
+        If queue is full, this will block until space is available.
 
         Args:
             file_path: Local file path
@@ -299,6 +355,9 @@ class BackgroundBufferManager:
             content_type: MIME type
             size_bytes: File size in bytes
         """
+        # Check queue pressure and trigger aggressive flushing if needed
+        self._check_queue_pressure(self._file_queue, "File")
+
         file_entry = {
             "file_path": file_path,
             "prefix": prefix,
@@ -311,6 +370,7 @@ class BackgroundBufferManager:
             "size_bytes": size_bytes,
         }
 
+        # Will block if queue is full (backpressure to prevent OOM)
         self._file_queue.put(file_entry)
 
     def flush_all(self) -> None:
@@ -425,13 +485,73 @@ class BackgroundBufferManager:
             if triggered:
                 self._flush_event.clear()
 
-        # Final flush on shutdown
-        self._flush_logs()
+        # Final flush on shutdown - loop until all queues are empty
+        # This ensures no data is lost when shutting down with large queues
+        # Show progress bar for large flushes
+        initial_counts = {
+            'logs': self._log_queue.qsize(),
+            'metrics': {name: q.qsize() for name, q in self._metric_queues.items()},
+            'tracks': {topic: len(entries) for topic, entries in self._track_buffers.items()},
+            'files': self._file_queue.qsize(),
+        }
+
+        total_items = (
+            initial_counts['logs'] +
+            sum(initial_counts['metrics'].values()) +
+            sum(initial_counts['tracks'].values()) +
+            initial_counts['files']
+        )
+
+        # Show progress bar if there are many items to flush
+        show_progress = total_items > 200
+        items_flushed = 0
+
+        def update_progress():
+            nonlocal items_flushed
+            if show_progress:
+                progress = items_flushed / total_items
+                bar_length = 40
+                filled = int(bar_length * progress)
+                bar = '█' * filled + '░' * (bar_length - filled)
+                percent = progress * 100
+                print(f'\r[ML-Dash] Flushing: |{bar}| {percent:.1f}% ({items_flushed}/{total_items})', end='', flush=True)
+
+        # Flush logs
+        log_batch_size = self._config.log_batch_size
+        while not self._log_queue.empty():
+            before = self._log_queue.qsize()
+            self._flush_logs()
+            after = self._log_queue.qsize()
+            items_flushed += before - after
+            update_progress()
+
+        # Flush metrics
+        metric_batch_size = self._config.metric_batch_size
         for metric_name in list(self._metric_queues.keys()):
-            self._flush_metric(metric_name)
+            while not self._metric_queues[metric_name].empty():
+                before = self._metric_queues[metric_name].qsize()
+                self._flush_metric(metric_name)
+                after = self._metric_queues[metric_name].qsize()
+                items_flushed += before - after
+                update_progress()
+
+        # Flush tracks
         for topic in list(self._track_buffers.keys()):
+            track_count = len(self._track_buffers.get(topic, {}))
             self._flush_track(topic)
-        self._flush_files()
+            items_flushed += track_count
+            update_progress()
+
+        # Flush files
+        while not self._file_queue.empty():
+            before = self._file_queue.qsize()
+            self._flush_files()
+            after = self._file_queue.qsize()
+            items_flushed += before - after
+            update_progress()
+
+        if show_progress:
+            print()  # New line after progress bar
 
     def _flush_logs(self) -> None:
         """Batch flush logs using client.create_log_entries()."""

{ml_dash-0.6.14 → ml_dash-0.6.16}/src/ml_dash/experiment.py

@@ -381,6 +381,7 @@ class Experiment:
 
         try:
           from rich.console import Console
+          from ml_dash import __version__
 
           console = Console()
           experiment_url = f"https://dash.ml/{self.run.prefix}"
@@ -388,15 +389,19 @@ class Experiment:
             f"[{status_color}]{status_emoji} Experiment {status.lower()}: "
             f"[bold]{self.run.name}[/bold] (project: {self.run.project})[/{status_color}]\n"
             f"[dim]View results, statistics, and plots online at:[/dim] "
-            f"[link={experiment_url}]{experiment_url}[/link]"
+            f"[link={experiment_url}]{experiment_url}[/link]\n"
+            f"[dim]ml-dash version: {__version__}[/dim]"
           )
         except ImportError:
           # Fallback if rich is not available
+          from ml_dash import __version__
+
           experiment_url = f"https://dash.ml/{self.run.prefix}"
           print(
             f"{status_emoji} Experiment {status.lower()}: {self.run.name} (project: {self.run.project})"
           )
           print(f"View results at: {experiment_url}")
+          print(f"ml-dash version: {__version__}")
 
       except Exception as e:
         # Raise on status update failure

ml_dash-0.6.14/src/ml_dash/__init__.py

@@ -1,107 +0,0 @@
-"""
-ML-Dash Python SDK
-
-A simple and flexible SDK for ML experiment metricing and data storage.
-
-Prefix format: {owner}/{project}/path.../[name]
-  - owner: First segment (e.g., your username)
-  - project: Second segment (e.g., project name)
-  - path: Remaining segments form the folder structure
-  - name: Derived from last segment (may be a seed/id)
-
-Usage:
-
-    from ml_dash import Experiment
-
-    # Local mode - explicit configuration
-    with Experiment(
-        prefix="ge/my-project/experiments/exp1",
-        dash_root=".dash"
-    ).run as exp:
-        exp.log("Training started")
-        exp.params.set(lr=0.001)
-        exp.metrics("train").log(loss=0.5, step=0)
-
-    # Default: Remote mode (defaults to https://api.dash.ml)
-    with Experiment(prefix="ge/my-project/experiments/exp1").run as exp:
-        exp.log("Training started")
-        exp.params.set(lr=0.001)
-        exp.metrics("train").log(loss=0.5, step=0)
-
-    # Decorator style
-    from ml_dash import ml_dash_experiment
-
-    @ml_dash_experiment(prefix="ge/my-project/experiments/exp1")
-    def train_model(exp):
-        exp.log("Training started")
-"""
-
-from .client import RemoteClient, userinfo
-from .experiment import Experiment, OperationMode, ml_dash_experiment
-from .log import LogBuilder, LogLevel
-from .params import ParametersBuilder
-from .run import RUN
-from .storage import LocalStorage
-
-__version__ = "0.6.14"
-
-# Required version - MUST match exactly (blocks all older versions)
-# Update this with EVERY release to force users to upgrade
-REQUIRED_VERSION = "0.6.14"
-
-
-def _check_version_compatibility():
-    """
-    Enforce strict version requirement.
-
-    Raises ImportError if installed version doesn't match the required version.
-    This ensures all users are on the latest version with newest features and bug fixes.
-    """
-    try:
-        from packaging import version
-    except ImportError:
-        # If packaging is not available, skip check
-        # (unlikely since it's a common dependency)
-        return
-
-    current = version.parse(__version__)
-    required = version.parse(REQUIRED_VERSION)
-
-    if current < required:
-        raise ImportError(
-            f"\n"
-            f"{'=' * 80}\n"
-            f"ERROR: ml-dash version {__version__} is outdated!\n"
-            f"{'=' * 80}\n"
-            f"\n"
-            f"Your installed version ({__version__}) is no longer supported.\n"
-            f"Required version: {REQUIRED_VERSION}\n"
-            f"\n"
-            f"Please upgrade to the latest version:\n"
-            f"\n"
-            f"  pip install --upgrade ml-dash\n"
-            f"\n"
-            f"Or with uv:\n"
-            f"\n"
-            f"  uv pip install --upgrade ml-dash\n"
-            f"  uv sync --upgrade-package ml-dash\n"
-            f"\n"
-            f"{'=' * 80}\n"
-        )
-
-
-# Enforce version check on import
-_check_version_compatibility()
-
-__all__ = [
-  "Experiment",
-  "ml_dash_experiment",
-  "OperationMode",
-  "RemoteClient",
-  "LocalStorage",
-  "LogLevel",
-  "LogBuilder",
-  "ParametersBuilder",
-  "RUN",
-  "userinfo",
-]