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

ml_dash/run.py

@@ -0,0 +1,85 @@
+"""
+RUN - Global run configuration object for ML-Dash.
+
+This module provides a global RUN object that serves as the single source
+of truth for run/experiment metadata. Uses params-proto for configuration.
+
+Usage:
+    from ml_dash import RUN
+
+    # Configure the run
+    RUN.name = "my-experiment"
+    RUN.project = "my-project"
+
+    # Use in templates
+    folder = "/experiments/{RUN.name}".format(RUN=RUN)
+
+    # With dxp singleton (RUN is auto-populated)
+    from ml_dash import dxp
+    with dxp.run:
+        # RUN.name, RUN.project, RUN.id, RUN.timestamp are set
+        dxp.log().info(f"Running {RUN.name}")
+"""
+
+from datetime import datetime
+from params_proto import proto
+
+
+@proto.prefix
+class RUN:
+    """
+    Global run configuration.
+
+    This class is the single source of truth for run metadata.
+    Configure it before starting an experiment, or let dxp auto-configure.
+    """
+    # Core identifiers
+    name: str = "untitled"  # Run/experiment name
+    project: str = "scratch"  # Project name
+
+    # Auto-generated identifiers (populated at run.start())
+    id: str = None  # Unique run ID (auto-generated)
+    timestamp: str = None  # Run timestamp (same as id)
+
+    # Optional configuration
+    folder: str = None  # Folder path with optional templates
+    description: str = None  # Run description
+
+    @classmethod
+    def _generate_id(cls) -> str:
+        """Generate a unique run ID based on current timestamp."""
+        return datetime.utcnow().strftime("%Y%m%d_%H%M%S")
+
+    @classmethod
+    def _init_run(cls) -> None:
+        """Initialize run ID and timestamp if not already set."""
+        if cls.id is None:
+            cls.id = cls._generate_id()
+            cls.timestamp = cls.id
+
+    @classmethod
+    def _format(cls, template: str) -> str:
+        """
+        Format a template string with RUN values.
+
+        Args:
+            template: String with {RUN.attr} placeholders
+
+        Returns:
+            Formatted string with placeholders replaced
+
+        Example:
+            RUN._format("/experiments/{RUN.name}_{RUN.id}")
+            # -> "/experiments/my-exp_20241219_143022"
+        """
+        return template.format(RUN=cls)
+
+    @classmethod
+    def _reset(cls) -> None:
+        """Reset RUN to defaults (for testing or new runs)."""
+        cls.name = "untitled"
+        cls.project = "scratch"
+        cls.id = None
+        cls.timestamp = None
+        cls.folder = None
+        cls.description = None

ml_dash/storage.py

@@ -627,7 +627,8 @@ class LocalStorage:
             FileNotFoundError: If file not found
         """
         experiment_dir = self._get_experiment_dir(project, experiment)
-        metadata_file = experiment_dir / "files" / ".files_metadata.json"
+        files_dir = experiment_dir / "files"
+        metadata_file = files_dir / ".files_metadata.json"
 
         if not metadata_file.exists():
             raise FileNotFoundError(f"File {file_id} not found")
@@ -689,7 +690,8 @@ class LocalStorage:
             FileNotFoundError: If file not found
         """
         experiment_dir = self._get_experiment_dir(project, experiment)
-        metadata_file = experiment_dir / "files" / ".files_metadata.json"
+        files_dir = experiment_dir / "files"
+        metadata_file = files_dir / ".files_metadata.json"
 
         if not metadata_file.exists():
             raise FileNotFoundError(f"File {file_id} not found")

{ml_dash-0.6.1.dist-info → ml_dash-0.6.2rc1.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: ml-dash
-Version: 0.6.1
+Version: 0.6.2rc1
 Summary: ML experiment tracking and data storage
 Keywords: machine-learning,experiment-tracking,mlops,data-storage
 Author: Ge Yang, Tom Tao
@@ -43,6 +43,7 @@ Requires-Dist: imageio-ffmpeg>=0.4.9
 Requires-Dist: scikit-image>=0.21.0
 Requires-Dist: rich>=13.0.0
 Requires-Dist: cryptography>=42.0.0
+Requires-Dist: params-proto>=3.0.0rc12
 Requires-Dist: keyring>=25.0.0 ; extra == 'auth'
 Requires-Dist: qrcode>=8.0.0 ; extra == 'auth'
 Requires-Dist: pytest>=8.0.0 ; extra == 'dev'
@@ -67,12 +68,13 @@ Description-Content-Type: text/markdown
 
 # ML-Dash
 
-A simple and flexible SDK for ML experiment metricing and data storage.
+A simple and flexible SDK for ML experiment tracking and data storage.
 
 ## Features
 
-- **Three Usage Styles**: Decorator, context manager, or direct instantiation
+- **Three Usage Styles**: Pre-configured singleton (dxp), context manager, or direct instantiation
 - **Dual Operation Modes**: Remote (API server) or local (filesystem)
+- **OAuth2 Authentication**: Secure device flow authentication for CLI and SDK
 - **Auto-creation**: Automatically creates namespace, project, and folder hierarchy
 - **Upsert Behavior**: Updates existing experiments or creates new ones
 - **Experiment Lifecycle**: Automatic status tracking (RUNNING, COMPLETED, FAILED, CANCELLED)
@@ -91,23 +93,48 @@ A simple and flexible SDK for ML experiment metricing and data storage.
 <td>
 
 ```bash
-uv add ml-dash
+uv add ml-dash==0.6.2rc1
 ```
 
 </td>
 <td>
 
 ```bash
-pip install ml-dash
+pip install ml-dash==0.6.2rc1
 ```
 
 </td>
 </tr>
 </table>
 
-## Getting Started
+## Quick Start
 
-### Remote Mode (with API Server)
+### 1. Authenticate (Required for Remote Mode)
+
+```bash
+ml-dash login
+```
+
+This opens your browser for secure OAuth2 authentication. Your credentials are stored securely in your system keychain.
+
+### 2. Start Tracking Experiments
+
+#### Option A: Use the Pre-configured Singleton (Easiest)
+
+```python
+from ml_dash import dxp
+
+# Start experiment (uploads to https://api.dash.ml by default)
+with dxp.run:
+    dxp.log().info("Training started")
+    dxp.params.set(learning_rate=0.001, batch_size=32)
+
+    for epoch in range(10):
+        loss = train_one_epoch()
+        dxp.metrics("loss").append(value=loss, epoch=epoch)
+```
+
+#### Option B: Create Your Own Experiment
 
 ```python
 from ml_dash import Experiment
@@ -115,13 +142,13 @@ from ml_dash import Experiment
 with Experiment(
     name="my-experiment",
     project="my-project",
-    remote="https://api.dash.ml",
-    api_key="your-jwt-token"
-) as experiment:
-    print(f"Experiment ID: {experiment.id}")
+    remote="https://api.dash.ml"  # token auto-loaded
+).run as experiment:
+    experiment.log().info("Hello!")
+    experiment.params.set(lr=0.001)
 ```
 
-### Local Mode (Filesystem)
+#### Option C: Local Mode (No Authentication Required)
 
 ```python
 from ml_dash import Experiment
@@ -130,11 +157,11 @@ with Experiment(
     name="my-experiment",
     project="my-project",
     local_path=".ml-dash"
-) as experiment:
-    pass  # Your code here
+).run as experiment:
+    experiment.log().info("Running locally")
 ```
 
-See [examples/](examples/) for more complete examples.
+See [docs/getting-started.md](docs/getting-started.md) for more examples.
 
 ## Development Setup
 

{ml_dash-0.6.1.dist-info → ml_dash-0.6.2rc1.dist-info}/RECORD

@@ -1,4 +1,4 @@
-ml_dash/__init__.py,sha256=eO526uX_T_Y5tySTVw2ZN-QCR46120gYPD6DWhenMUw,2228
+ml_dash/__init__.py,sha256=JJlSut9U_nixMsZxaqj9QQK0J3WUckGis7ouOQegWmw,2260
 ml_dash/auth/__init__.py,sha256=3lwM-Y8UBHPU1gFW2JNpmXlPVTnkGudWLKNFFKulQfo,1200
 ml_dash/auth/constants.py,sha256=ku4QzQUMNjvyJwjy7AUdywMAZd59jXSxNHZxDiagUWU,280
 ml_dash/auth/device_flow.py,sha256=DQOdPNlZCuU1umZOA_A6WXdRM3zWphnyo9IntToBl_A,7921
@@ -15,15 +15,16 @@ ml_dash/cli_commands/logout.py,sha256=lTUUNyRXqvo61qNkCd4KBrPUujDAHnNqsHkU6bHie0
 ml_dash/cli_commands/upload.py,sha256=4O9iZOQDOiiBBsoDG1Cr8BqeBGSZZSfc3i-5FERjFtU,46439
 ml_dash/client.py,sha256=0jM3HzNyFy-QBN7ZLXQTuiIuiTuh4K1Zdldb4Eny0NY,29531
 ml_dash/config.py,sha256=aNqX_HT2Yo-BzjFexQ97gQK9xOiBUwuJJ65dKM3oJjs,3481
-ml_dash/experiment.py,sha256=qEwPq8U6YXw-bmEBOZX0yL-4Y8TTZYuFsKtMarq8duA,33913
-ml_dash/files.py,sha256=p9s15eqgGAf-6bZntXkd_YicS6GjSGzEKAN_YoMuAXQ,26541
+ml_dash/experiment.py,sha256=4mbJ6nul-k5Il1z0zjX2mmw56TbhWkeW4KyUa5DHvcU,35410
+ml_dash/files.py,sha256=OCcGI2RHV5iO5BSWObCpz-GVJ2-wGFAgTqGGhDSesbQ,45168
 ml_dash/log.py,sha256=0yXaNnFwYeBI3tRLHX3kkqWRpg0MbSGwmgjnOfsElCk,5350
 ml_dash/metric.py,sha256=vz3YwO1YBWZ797l7TzD5m9WwNBBXlrATyRRzSti8QS0,17194
 ml_dash/params.py,sha256=S4wHQfv0EQRXRrFbKLuEKTQOLp5eqnALcIk1pZNroBM,9124
 ml_dash/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 ml_dash/remote_auto_start.py,sha256=BAsTu41e9SboeSCn9N2vn4ftoYeUVklcAcNM45HJVGA,1610
-ml_dash/storage.py,sha256=OTMMHSLYHk_MBfo8PyMQBHD8AZ2TFTS8KSMhVhpG-hg,39493
-ml_dash-0.6.1.dist-info/WHEEL,sha256=z-mOpxbJHqy3cq6SvUThBZdaLGFZzdZPtgWLcP2NKjQ,79
-ml_dash-0.6.1.dist-info/entry_points.txt,sha256=dYs2EHX1uRNO7AQGNnVaJJpgiy0Z9q7tiy4fHSyaf3Q,46
-ml_dash-0.6.1.dist-info/METADATA,sha256=0hRUQtm5iwiniAfYZJu9mnkJVUFnPQUPow7Va8VFqLI,6328
-ml_dash-0.6.1.dist-info/RECORD,,
+ml_dash/run.py,sha256=JwLigo2trdkwVrv-eCP4q9enSxLzla8jXeHXd6ZvNFk,2449
+ml_dash/storage.py,sha256=iaFpH-2eK-Vd_b1lPpOQHxJI9GGkehB9g7pT7-r3nu4,39553
+ml_dash-0.6.2rc1.dist-info/WHEEL,sha256=ELhySV62sOro8I5wRaLaF3TWxhBpkcDkdZUdAYLy_Hk,78
+ml_dash-0.6.2rc1.dist-info/entry_points.txt,sha256=dYs2EHX1uRNO7AQGNnVaJJpgiy0Z9q7tiy4fHSyaf3Q,46
+ml_dash-0.6.2rc1.dist-info/METADATA,sha256=d_EDyVjjcNTdhItUZYayP--dzrIchFsIOOBJ4aWrKSU,7206
+ml_dash-0.6.2rc1.dist-info/RECORD,,

{ml_dash-0.6.1.dist-info → ml_dash-0.6.2rc1.dist-info}/WHEEL

@@ -1,4 +1,4 @@
 Wheel-Version: 1.0
-Generator: uv 0.9.15
+Generator: uv 0.9.3
 Root-Is-Purelib: true
 Tag: py3-none-any