ml-dash 0.5.4__py3-none-any.whl → 0.5.6__py3-none-any.whl

ml_dash/experiment.py

@@ -460,7 +460,7 @@ class Experiment:
                 timestamp=log_entry["timestamp"]
             )
 
-    def file(self, **kwargs) -> FileBuilder:
+    def files(self, **kwargs) -> FileBuilder:
         """
         Get a FileBuilder for fluent file operations.
 
@@ -472,17 +472,17 @@ class Experiment:
 
         Examples:
             # Upload file
-            experiment.file(file_path="./model.pt", prefix="/models").save()
+            experiment.files(file_path="./model.pt", prefix="/models").save()
 
             # List files
-            files = experiment.file().list()
-            files = experiment.file(prefix="/models").list()
+            files = experiment.files().list()
+            files = experiment.files(prefix="/models").list()
 
             # Download file
-            experiment.file(file_id="123").download()
+            experiment.files(file_id="123").download()
 
             # Delete file
-            experiment.file(file_id="123").delete()
+            experiment.files(file_id="123").delete()
         """
         if not self._is_open:
             raise RuntimeError("Experiment not open. Use experiment.open() or context manager.")

ml_dash/files.py

@@ -6,7 +6,7 @@ Provides fluent API for file upload, download, list, and delete operations.
 
 import hashlib
 import mimetypes
-from typing import Dict, Any, List, Optional, TYPE_CHECKING
+from typing import Dict, Any, List, Optional, Union, TYPE_CHECKING
 from pathlib import Path
 
 if TYPE_CHECKING:
@@ -19,18 +19,18 @@ class FileBuilder:
 
     Usage:
         # Upload file
-        experiment.file(file_path="./model.pt", prefix="/models").save()
+        experiment.files(file_path="./model.pt", prefix="/models").save()
 
         # List files
-        files = experiment.file().list()
-        files = experiment.file(prefix="/models").list()
+        files = experiment.files().list()
+        files = experiment.files(prefix="/models").list()
 
         # Download file
-        experiment.file(file_id="123").download()
-        experiment.file(file_id="123", dest_path="./model.pt").download()
+        experiment.files(file_id="123").download()
+        experiment.files(file_id="123", dest_path="./model.pt").download()
 
         # Delete file
-        experiment.file(file_id="123").delete()
+        experiment.files(file_id="123").delete()
     """
 
     def __init__(self, experiment: 'Experiment', **kwargs):
@@ -72,7 +72,7 @@ class FileBuilder:
             ValueError: If file size exceeds 5GB limit
 
         Examples:
-            result = experiment.file(file_path="./model.pt", prefix="/models").save()
+            result = experiment.files(file_path="./model.pt", prefix="/models").save()
             # Returns: {"id": "123", "path": "/models", "filename": "model.pt", ...}
         """
         if not self._experiment._is_open:
@@ -130,9 +130,9 @@ class FileBuilder:
             RuntimeError: If experiment is not open
 
         Examples:
-            files = experiment.file().list()  # All files
-            files = experiment.file(prefix="/models").list()  # Filter by prefix
-            files = experiment.file(tags=["checkpoint"]).list()  # Filter by tags
+            files = experiment.files().list()  # All files
+            files = experiment.files(prefix="/models").list()  # Filter by prefix
+            files = experiment.files(tags=["checkpoint"]).list()  # Filter by tags
         """
         if not self._experiment._is_open:
             raise RuntimeError("Experiment not open. Use experiment.open() or context manager.")
@@ -158,10 +158,10 @@ class FileBuilder:
 
         Examples:
             # Download to current directory with original filename
-            path = experiment.file(file_id="123").download()
+            path = experiment.files(file_id="123").download()
 
             # Download to custom path
-            path = experiment.file(file_id="123", dest_path="./model.pt").download()
+            path = experiment.files(file_id="123", dest_path="./model.pt").download()
         """
         if not self._experiment._is_open:
             raise RuntimeError("Experiment not open. Use experiment.open() or context manager.")
@@ -186,7 +186,7 @@ class FileBuilder:
             ValueError: If file_id not provided
 
         Examples:
-            result = experiment.file(file_id="123").delete()
+            result = experiment.files(file_id="123").delete()
         """
         if not self._experiment._is_open:
             raise RuntimeError("Experiment not open. Use experiment.open() or context manager.")
@@ -211,7 +211,7 @@ class FileBuilder:
             ValueError: If file_id not provided
 
         Examples:
-            result = experiment.file(
+            result = experiment.files(
                 file_id="123",
                 description="Updated description",
                 tags=["new", "tags"],
@@ -251,7 +251,7 @@ class FileBuilder:
 
         Examples:
             config = {"model": "resnet50", "lr": 0.001}
-            result = experiment.file(prefix="/configs").save_json(config, "config.json")
+            result = experiment.files(prefix="/configs").save_json(config, "config.json")
         """
         import json
         import tempfile
@@ -309,10 +309,10 @@ class FileBuilder:
         Examples:
             import torch
             model = torch.nn.Linear(10, 5)
-            result = experiment.file(prefix="/models").save_torch(model, "model.pt")
+            result = experiment.files(prefix="/models").save_torch(model, "model.pt")
 
             # Or save state dict
-            result = experiment.file(prefix="/models").save_torch(model.state_dict(), "model.pth")
+            result = experiment.files(prefix="/models").save_torch(model.state_dict(), "model.pth")
         """
         import tempfile
         import os
@@ -372,10 +372,10 @@ class FileBuilder:
 
         Examples:
             data = {"model": "resnet50", "weights": np.array([1, 2, 3])}
-            result = experiment.file(prefix="/data").save_pkl(data, "data.pkl")
+            result = experiment.files(prefix="/data").save_pkl(data, "data.pkl")
 
             # Or save any Python object
-            result = experiment.file(prefix="/models").save_pkl(trained_model, "model.pickle")
+            result = experiment.files(prefix="/models").save_pkl(trained_model, "model.pickle")
         """
         import pickle
         import tempfile
@@ -414,6 +414,199 @@ class FileBuilder:
             except Exception:
                 pass
 
+    def save_fig(self, fig: Optional[Any] = None, file_name: str = "figure.png", **kwargs) -> Dict[str, Any]:
+        """
+        Save matplotlib figure to a file.
+
+        Args:
+            fig: Matplotlib figure object. If None, uses plt.gcf() (current figure)
+            file_name: Name of file to create (extension determines format: .png, .pdf, .svg, .jpg)
+            **kwargs: Additional arguments passed to fig.savefig():
+                - dpi: Resolution (int or 'figure')
+                - transparent: Make background transparent (bool)
+                - bbox_inches: 'tight' to auto-crop (str or Bbox)
+                - quality: JPEG quality 0-100 (int)
+                - format: Override format detection (str)
+
+        Returns:
+            File metadata dict with id, path, filename, checksum, etc.
+
+        Raises:
+            RuntimeError: If experiment not open or write-protected
+            ImportError: If matplotlib not installed
+
+        Examples:
+            import matplotlib.pyplot as plt
+
+            # Use current figure
+            plt.plot([1, 2, 3], [1, 4, 9])
+            result = experiment.files(prefix="/plots").save_fig(file_name="plot.png")
+
+            # Specify figure explicitly
+            fig, ax = plt.subplots()
+            ax.plot([1, 2, 3])
+            result = experiment.files(prefix="/plots").save_fig(fig=fig, file_name="plot.pdf", dpi=150)
+        """
+        import tempfile
+        import os
+
+        try:
+            import matplotlib.pyplot as plt
+        except ImportError:
+            raise ImportError("Matplotlib is not installed. Install it with: pip install matplotlib")
+
+        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.")
+
+        # Get figure
+        if fig is None:
+            fig = plt.gcf()
+
+        # Create temporary file with desired filename
+        temp_dir = tempfile.mkdtemp()
+        temp_path = os.path.join(temp_dir, file_name)
+
+        try:
+            # Save figure to temp file
+            fig.savefig(temp_path, **kwargs)
+
+            # Close figure to prevent memory leaks
+            plt.close(fig)
+
+            # Save using existing save() method
+            original_file_path = self._file_path
+            self._file_path = temp_path
+
+            # Upload and get result
+            result = self.save()
+
+            # Restore original file_path
+            self._file_path = original_file_path
+
+            return result
+        finally:
+            # Clean up temp file and directory
+            try:
+                os.unlink(temp_path)
+                os.rmdir(temp_dir)
+            except Exception:
+                pass
+
+    def save_video(
+        self,
+        frame_stack: Union[List, Any],
+        file_name: str,
+        fps: int = 20,
+        **imageio_kwargs
+    ) -> Dict[str, Any]:
+        """
+        Save video frame stack to a file.
+
+        Args:
+            frame_stack: List of numpy arrays or stacked array (shape: [N, H, W] or [N, H, W, C])
+            file_name: Name of file to create (extension determines format: .mp4, .gif, .avi, .webm)
+            fps: Frames per second (default: 20)
+            **imageio_kwargs: Additional arguments passed to imageio.v3.imwrite():
+                - codec: Video codec (e.g., 'libx264', 'h264')
+                - quality: Quality level (int, higher is better)
+                - pixelformat: Pixel format (e.g., 'yuv420p')
+                - macro_block_size: Macro block size for encoding
+
+        Returns:
+            File metadata dict with id, path, filename, checksum, etc.
+
+        Raises:
+            RuntimeError: If experiment not open or write-protected
+            ImportError: If imageio or scikit-image not installed
+            ValueError: If frame_stack is empty or invalid format
+
+        Examples:
+            import numpy as np
+
+            # Grayscale frames (float values 0-1)
+            frames = [np.random.rand(480, 640) for _ in range(30)]
+            result = experiment.files(prefix="/videos").save_video(frames, "output.mp4")
+
+            # RGB frames with custom FPS
+            frames = [np.random.rand(480, 640, 3) for _ in range(60)]
+            result = experiment.files(prefix="/videos").save_video(frames, "output.mp4", fps=30)
+
+            # Save as GIF
+            frames = [np.random.rand(200, 200) for _ in range(20)]
+            result = experiment.files(prefix="/videos").save_video(frames, "animation.gif")
+
+            # With custom codec and quality
+            result = experiment.files(prefix="/videos").save_video(
+                frames, "output.mp4", fps=30, codec='libx264', quality=8
+            )
+        """
+        import tempfile
+        import os
+
+        try:
+            import imageio.v3 as iio
+        except ImportError:
+            raise ImportError("imageio is not installed. Install it with: pip install imageio imageio-ffmpeg")
+
+        try:
+            from skimage import img_as_ubyte
+        except ImportError:
+            raise ImportError("scikit-image is not installed. Install it with: pip install scikit-image")
+
+        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.")
+
+        # Validate frame_stack
+        try:
+            # Handle both list and numpy array
+            if len(frame_stack) == 0:
+                raise ValueError("frame_stack is empty")
+        except TypeError:
+            raise ValueError("frame_stack must be a list or numpy array")
+
+        # Create temporary file with desired filename
+        temp_dir = tempfile.mkdtemp()
+        temp_path = os.path.join(temp_dir, file_name)
+
+        try:
+            # Convert frames to uint8 format (handles float32/64, grayscale, RGB, etc.)
+            # img_as_ubyte automatically scales [0.0, 1.0] floats to [0, 255] uint8
+            frames_ubyte = img_as_ubyte(frame_stack)
+
+            # Encode video to temp file
+            try:
+                iio.imwrite(temp_path, frames_ubyte, fps=fps, **imageio_kwargs)
+            except iio.core.NeedDownloadError:
+                # Auto-download FFmpeg if not available
+                import imageio.plugins.ffmpeg
+                imageio.plugins.ffmpeg.download()
+                iio.imwrite(temp_path, frames_ubyte, fps=fps, **imageio_kwargs)
+
+            # Save using existing save() method
+            original_file_path = self._file_path
+            self._file_path = temp_path
+
+            # Upload and get result
+            result = self.save()
+
+            # Restore original file_path
+            self._file_path = original_file_path
+
+            return result
+        finally:
+            # Clean up temp file and directory
+            try:
+                os.unlink(temp_path)
+                os.rmdir(temp_dir)
+            except Exception:
+                pass
+
 
 def compute_sha256(file_path: str) -> str:
     """

{ml_dash-0.5.4.dist-info → ml_dash-0.5.6.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: ml-dash
-Version: 0.5.4
+Version: 0.5.6
 Summary: ML experiment tracking and data storage
 Keywords: machine-learning,experiment-tracking,mlops,data-storage
 Author: Ge Yang, Tom Tao
@@ -38,6 +38,9 @@ Classifier: Programming Language :: Python :: 3.13
 Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
 Requires-Dist: httpx>=0.27.0
 Requires-Dist: pyjwt>=2.8.0
+Requires-Dist: imageio>=2.31.0
+Requires-Dist: imageio-ffmpeg>=0.4.9
+Requires-Dist: scikit-image>=0.21.0
 Requires-Dist: pytest>=8.0.0 ; extra == 'dev'
 Requires-Dist: pytest-asyncio>=0.23.0 ; extra == 'dev'
 Requires-Dist: sphinx>=7.2.0 ; extra == 'dev'

{ml_dash-0.5.4.dist-info → ml_dash-0.5.6.dist-info}/RECORD

@@ -1,13 +1,13 @@
 ml_dash/__init__.py,sha256=o_LrWVJBY_VkUGhSBs5wdb_NqEsHD1AK9HGsjZGxHxQ,1414
 ml_dash/auto_start.py,sha256=c3XcXFpZdvjtWauEoK5043Gw9k0L_5IDq4fdiB2ha88,959
 ml_dash/client.py,sha256=vhWcS5o2n3o4apEjVeLmu7flCEzxBbBOoLSQNcAx_ew,17267
-ml_dash/experiment.py,sha256=efEdKkA3KBOlC-uNEXVtun1ARiZ_AQG3nOGAUsLLZ5Q,30640
-ml_dash/files.py,sha256=Nx7f0n9zoQ7XqPtiHu_SBEZK0cT2b3F6-EhJBNs3C6k,15824
+ml_dash/experiment.py,sha256=K36HkHJb_O2-vdaPPOCq74_2nZtfiLaS0o7qhTntD8Q,30646
+ml_dash/files.py,sha256=ZY9BwPm_Fym-yg0I3lBtZwi1c7ioKRmhp_86f2u06ww,23014
 ml_dash/log.py,sha256=0yXaNnFwYeBI3tRLHX3kkqWRpg0MbSGwmgjnOfsElCk,5350
 ml_dash/metric.py,sha256=c0Zl0wEufmQuVfwIMvrORLwqe92Iaf0PfKRgmlgQWzQ,10343
 ml_dash/params.py,sha256=xaByDSVar4D1pZqxTANkMPeZTL5-V7ewJe5TXfPLhMQ,5980
 ml_dash/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 ml_dash/storage.py,sha256=8lyT5ZdvhS2nEyrEgMnFAT0LzV5ne1v8tkI3w1PUHJ4,30793
-ml_dash-0.5.4.dist-info/WHEEL,sha256=X16MKk8bp2DRsAuyteHJ-9qOjzmnY0x1aj0P1ftqqWA,78
-ml_dash-0.5.4.dist-info/METADATA,sha256=5qFL8t0ikhtuAIC65zYAZAYt24n937KA5RzJEreBxU0,6043
-ml_dash-0.5.4.dist-info/RECORD,,
+ml_dash-0.5.6.dist-info/WHEEL,sha256=X16MKk8bp2DRsAuyteHJ-9qOjzmnY0x1aj0P1ftqqWA,78
+ml_dash-0.5.6.dist-info/METADATA,sha256=l2nzY_SRqgzZFeS6_KKHtzgsOSdZ40Mc4XAaGkggEaU,6147
+ml_dash-0.5.6.dist-info/RECORD,,