ml-dash 0.6.1__tar.gz → 0.6.2rc1__tar.gz

{ml_dash-0.6.1 → ml_dash-0.6.2rc1}/PKG-INFO

@@ -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 → ml_dash-0.6.2rc1}/README.md

@@ -1,11 +1,12 @@
 # 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)
@@ -24,23 +25,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
@@ -48,13 +74,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
@@ -63,11 +89,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 → ml_dash-0.6.2rc1}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "ml-dash"
-version = "0.6.1"
+version = "0.6.2rc1"
 description = "ML experiment tracking and data storage"
 readme = "README.md"
 requires-python = ">=3.9"
@@ -31,6 +31,7 @@ dependencies = [
     "scikit-image>=0.21.0",
     "rich>=13.0.0",
     "cryptography>=42.0.0",
+    "params-proto>=3.0.0rc12",
 ]
 
 [project.scripts]

{ml_dash-0.6.1 → ml_dash-0.6.2rc1}/src/ml_dash/__init__.py

@@ -51,6 +51,7 @@ from .client import RemoteClient
 from .storage import LocalStorage
 from .log import LogLevel, LogBuilder
 from .params import ParametersBuilder
+from .run import RUN
 from .auto_start import dxp
 
 __version__ = "0.1.0"
@@ -65,6 +66,7 @@ __all__ = [
     "LogLevel",
     "LogBuilder",
     "ParametersBuilder",
+    "RUN",
     "dxp",
 ]
 

{ml_dash-0.6.1 → ml_dash-0.6.2rc1}/src/ml_dash/experiment.py

@@ -17,7 +17,8 @@ from .client import RemoteClient
 from .storage import LocalStorage
 from .log import LogLevel, LogBuilder
 from .params import ParametersBuilder
-from .files import FileBuilder
+from .files import FilesAccessor, BindrsBuilder
+from .run import RUN
 
 
 class OperationMode(Enum):
@@ -121,28 +122,13 @@ class RunManager:
                 "Set folder before calling start() or entering 'with' block."
             )
 
-        # Process template variables if present
+        # Check if this is a template (contains {RUN.) or static folder
         if value and '{RUN.' in value:
-            # Generate unique run ID (timestamp-based)
-            from datetime import datetime
-            run_timestamp = datetime.utcnow().strftime("%Y%m%d_%H%M%S")
-
-            # Simple string replacement for template variables
-            # Supports: {RUN.name}, {RUN.project}, {RUN.id}, {RUN.timestamp}
-            replacements = {
-                '{RUN.name}': f"{self._experiment.name}_{run_timestamp}",  # Unique name with timestamp
-                '{RUN.project}': self._experiment.project,
-                '{RUN.id}': run_timestamp,  # Just the timestamp
-                '{RUN.timestamp}': run_timestamp,  # Alias for id
-            }
-
-            # Replace all template variables
-            for template, replacement in replacements.items():
-                if template in value:
-                    value = value.replace(template, replacement)
-
-        # Update the folder on the experiment
-        self._experiment.folder = value
+            # Store the template - it will be formatted when the run starts
+            self._experiment._folder_template = value
+        else:
+            # Static folder - set directly
+            self._experiment.folder = value
 
     def __enter__(self) -> "Experiment":
         """Context manager entry - starts the experiment."""
@@ -240,7 +226,7 @@ class Experiment:
         self.project = project
         self.description = description
         self.tags = tags
-        self.bindrs = bindrs
+        self._bindrs_list = bindrs
         self.folder = folder
         self._write_protected = _write_protected
         self.metadata = metadata
@@ -264,6 +250,7 @@ class Experiment:
         self._experiment_data: Optional[Dict[str, Any]] = None
         self._is_open = False
         self._metrics_manager: Optional['MetricsManager'] = None  # Cached metrics manager
+        self._folder_template: Optional[str] = None  # Template for folder path
 
         if self.mode in (OperationMode.REMOTE, OperationMode.HYBRID):
             # api_key can be None - RemoteClient will auto-load from storage
@@ -284,6 +271,16 @@ class Experiment:
         if self._is_open:
             return self
 
+        # Initialize RUN with experiment values
+        RUN.name = self.name
+        RUN.project = self.project
+        RUN.description = self.description
+        RUN._init_run()  # Generate id and timestamp
+
+        # Format folder template if present
+        if self._folder_template:
+            self.folder = RUN._format(self._folder_template)
+
         if self._client:
             # Remote mode: create/update experiment via API
             response = self._client.create_or_update_experiment(
@@ -291,7 +288,7 @@ class Experiment:
                 name=self.name,
                 description=self.description,
                 tags=self.tags,
-                bindrs=self.bindrs,
+                bindrs=self._bindrs_list,
                 folder=self.folder,
                 write_protected=self._write_protected,
                 metadata=self.metadata,
@@ -306,7 +303,7 @@ class Experiment:
                 name=self.name,
                 description=self.description,
                 tags=self.tags,
-                bindrs=self.bindrs,
+                bindrs=self._bindrs_list,
                 folder=self.folder,
                 metadata=self.metadata,
             )
@@ -341,6 +338,9 @@ class Experiment:
 
         self._is_open = False
 
+        # Reset RUN for next experiment
+        RUN._reset()
+
     @property
     def run(self) -> RunManager:
         """
@@ -545,39 +545,86 @@ class Experiment:
         else:
             print(formatted_message, file=sys.stdout)
 
-    def files(self, **kwargs) -> FileBuilder:
+    @property
+    def files(self) -> FilesAccessor:
         """
-        Get a FileBuilder for fluent file operations.
+        Get a FilesAccessor for fluent file operations.
 
         Returns:
-            FileBuilder instance for chaining
+            FilesAccessor instance for chaining
 
         Raises:
             RuntimeError: If experiment is not open
 
         Examples:
             # Upload file
-            experiment.files(file_path="./model.pt", prefix="/models").save()
+            experiment.files("checkpoints").save(net, to="checkpoint.pt")
 
             # List files
-            files = experiment.files().list()
-            files = experiment.files(prefix="/models").list()
+            files = experiment.files("/some/location").list()
+            files = experiment.files("/models").list()
 
             # Download file
-            experiment.files(file_id="123").download()
+            experiment.files("some.text").download()
+            experiment.files("some.text").download(to="./model.pt")
+
+            # Download Files via Glob Pattern
+            file_paths = experiment.files("images").list("*.png")
+            experiment.files("images").download("*.png")
+
+            # This is equivalent to downloading to a directory
+            experiment.files.download("images/*.png", to="local_images")
+
+            # Delete files
+            experiment.files("some.text").delete()
+            experiment.files.delete("some.text")
+
+            # Specific File Types
+            dxp.files.save_text("content", to="view.yaml")
+            dxp.files.save_json(dict(hey="yo"), to="config.json")
+            dxp.files.save_blob(b"xxx", to="data.bin")
+        """
+        if not self._is_open:
+            raise RuntimeError(
+                "Experiment not started. Use 'with experiment.run:' or call experiment.run.start() first.\n"
+                "Example:\n"
+                "  with dxp.run:\n"
+                "      dxp.files('path').save()"
+            )
+
+        return FilesAccessor(self)
+
+    def bindrs(self, bindr_name: str) -> BindrsBuilder:
+        """
+        Get a BindrsBuilder for working with file collections (bindrs).
+
+        Bindrs are collections of files that can span multiple prefixes.
+
+        Args:
+            bindr_name: Name of the bindr (collection)
+
+        Returns:
+            BindrsBuilder instance for chaining
+
+        Raises:
+            RuntimeError: If experiment is not open
+
+        Examples:
+            # List files in a bindr
+            file_paths = experiment.bindrs("some-bindr").list()
 
-            # Delete file
-            experiment.files(file_id="123").delete()
+        Note:
+            This is a placeholder for future bindr functionality.
         """
         if not self._is_open:
             raise RuntimeError(
                 "Experiment not started. Use 'with experiment.run:' or call experiment.run.start() first.\n"
                 "Example:\n"
                 "  with dxp.run:\n"
-                "      dxp.files().save()"
+                "      files = dxp.bindrs('my-bindr').list()"
             )
 
-        return FileBuilder(self, **kwargs)
+        return BindrsBuilder(self, bindr_name)
 
     def _upload_file(
         self,