ml-dash 0.5.9__tar.gz → 0.6.3__tar.gz

{ml_dash-0.5.9 → ml_dash-0.6.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: ml-dash
-Version: 0.5.9
+Version: 0.6.3
 Summary: ML experiment tracking and data storage
 Keywords: machine-learning,experiment-tracking,mlops,data-storage
 Author: Ge Yang, Tom Tao
@@ -42,6 +42,10 @@ Requires-Dist: imageio>=2.31.0
 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.0
+Requires-Dist: keyring>=25.0.0 ; extra == 'auth'
+Requires-Dist: qrcode>=8.0.0 ; extra == 'auth'
 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'
@@ -58,17 +62,19 @@ Requires-Dist: linkify-it-py>=2.0.0 ; extra == 'dev'
 Requires-Dist: ruff>=0.3.0 ; extra == 'dev'
 Requires-Dist: mypy>=1.9.0 ; extra == 'dev'
 Requires-Python: >=3.9
+Provides-Extra: auth
 Provides-Extra: dev
 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)
@@ -87,50 +93,73 @@ 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.auto_start import dxp
+
+# Start experiment (uploads to https://api.dash.ml by default)
+with dxp.run:
+    dxp.log("Training started", level="info")
+    dxp.params.set(learning_rate=0.001, batch_size=32)
+
+    for epoch in range(10):
+        loss = train_one_epoch()
+        dxp.metrics("train").log(loss=loss, epoch=epoch)
+```
+
+#### Option B: Create Your Own Experiment
 
 ```python
 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}")
+  prefix="alice/my-project/my-experiment",
+  dash_url="https://api.dash.ml",  # token auto-loaded
+).run as experiment:
+  experiment.log("Hello!", level="info")
+  experiment.params.set(lr=0.001)
 ```
 
-### Local Mode (Filesystem)
+#### Option C: Local Mode (No Authentication Required)
 
 ```python
 from ml_dash import Experiment
 
 with Experiment(
-    name="my-experiment",
-    project="my-project",
-    local_path=".ml-dash"
-) as experiment:
-    pass  # Your code here
+  project="my-project", prefix="my-experiment", dash_root=".dash"
+).run as experiment:
+  experiment.log("Running locally", level="info")
+
 ```
 
-See [examples/](examples/) for more complete examples.
+See [docs/getting-started.md](docs/getting-started.md) for more examples.
 
 ## Development Setup
 

{ml_dash-0.5.9 → ml_dash-0.6.3}/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,50 +25,73 @@ 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.auto_start import dxp
+
+# Start experiment (uploads to https://api.dash.ml by default)
+with dxp.run:
+    dxp.log("Training started", level="info")
+    dxp.params.set(learning_rate=0.001, batch_size=32)
+
+    for epoch in range(10):
+        loss = train_one_epoch()
+        dxp.metrics("train").log(loss=loss, epoch=epoch)
+```
+
+#### Option B: Create Your Own Experiment
 
 ```python
 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}")
+  prefix="alice/my-project/my-experiment",
+  dash_url="https://api.dash.ml",  # token auto-loaded
+).run as experiment:
+  experiment.log("Hello!", level="info")
+  experiment.params.set(lr=0.001)
 ```
 
-### Local Mode (Filesystem)
+#### Option C: Local Mode (No Authentication Required)
 
 ```python
 from ml_dash import Experiment
 
 with Experiment(
-    name="my-experiment",
-    project="my-project",
-    local_path=".ml-dash"
-) as experiment:
-    pass  # Your code here
+  project="my-project", prefix="my-experiment", dash_root=".dash"
+).run as experiment:
+  experiment.log("Running locally", level="info")
+
 ```
 
-See [examples/](examples/) for more complete examples.
+See [docs/getting-started.md](docs/getting-started.md) for more examples.
 
 ## Development Setup
 

{ml_dash-0.5.9 → ml_dash-0.6.3}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "ml-dash"
-version = "0.5.9"
+version = "0.6.3"
 description = "ML experiment tracking and data storage"
 readme = "README.md"
 requires-python = ">=3.9"
@@ -30,12 +30,18 @@ dependencies = [
     "imageio-ffmpeg>=0.4.9",
     "scikit-image>=0.21.0",
     "rich>=13.0.0",
+    "cryptography>=42.0.0",
+    "params-proto>=3.0.0",
 ]
 
 [project.scripts]
 ml-dash = "ml_dash.cli:main"
 
 [project.optional-dependencies]
+auth = [
+    "keyring>=25.0.0",
+    "qrcode>=8.0.0",
+]
 dev = [
     "pytest>=8.0.0",
     "pytest-asyncio>=0.23.0",

ml_dash-0.6.3/src/ml_dash/__init__.py

@@ -0,0 +1,59 @@
+"""
+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
+from .experiment import Experiment, OperationMode, RunManager, ml_dash_experiment
+from .log import LogBuilder, LogLevel
+from .params import ParametersBuilder
+from .run import RUN
+from .storage import LocalStorage
+
+__version__ = "0.6.3"
+
+__all__ = [
+  "Experiment",
+  "ml_dash_experiment",
+  "OperationMode",
+  "RunManager",
+  "RemoteClient",
+  "LocalStorage",
+  "LogLevel",
+  "LogBuilder",
+  "ParametersBuilder",
+  "RUN",
+]

ml_dash-0.6.3/src/ml_dash/auth/__init__.py

@@ -0,0 +1,51 @@
+"""Authentication module for ml-dash."""
+
+from .constants import VUER_AUTH_URL, CLIENT_ID, DEFAULT_SCOPE
+from .device_flow import DeviceFlowClient, DeviceFlowResponse
+from .device_secret import (
+    generate_device_secret,
+    hash_device_secret,
+    get_or_create_device_secret,
+)
+from .token_storage import (
+    TokenStorage,
+    KeyringStorage,
+    EncryptedFileStorage,
+    PlaintextFileStorage,
+    get_token_storage,
+)
+from .exceptions import (
+    AuthenticationError,
+    NotAuthenticatedError,
+    DeviceCodeExpiredError,
+    AuthorizationDeniedError,
+    TokenExchangeError,
+    StorageError,
+)
+
+__all__ = [
+    # Constants
+    "VUER_AUTH_URL",
+    "CLIENT_ID",
+    "DEFAULT_SCOPE",
+    # Device Flow
+    "DeviceFlowClient",
+    "DeviceFlowResponse",
+    # Device Secret
+    "generate_device_secret",
+    "hash_device_secret",
+    "get_or_create_device_secret",
+    # Token Storage
+    "TokenStorage",
+    "KeyringStorage",
+    "EncryptedFileStorage",
+    "PlaintextFileStorage",
+    "get_token_storage",
+    # Exceptions
+    "AuthenticationError",
+    "NotAuthenticatedError",
+    "DeviceCodeExpiredError",
+    "AuthorizationDeniedError",
+    "TokenExchangeError",
+    "StorageError",
+]

ml_dash-0.6.3/src/ml_dash/auth/constants.py

@@ -0,0 +1,10 @@
+"""Authentication constants for ml-dash."""
+
+# Vuer-auth server URL
+VUER_AUTH_URL = "https://auth.vuer.ai"
+
+# OAuth client ID for ml-dash
+CLIENT_ID = "ml-dash-client"
+
+# Default OAuth scopes (no offline_access since we get permanent tokens)
+DEFAULT_SCOPE = "openid profile email"

ml_dash-0.6.3/src/ml_dash/auth/device_flow.py

@@ -0,0 +1,237 @@
+"""Device authorization flow (RFC 8628) client for ml-dash."""
+
+import time
+from dataclasses import dataclass
+from typing import Optional
+
+import httpx
+
+from .constants import VUER_AUTH_URL, CLIENT_ID, DEFAULT_SCOPE
+from .device_secret import hash_device_secret
+from .exceptions import (
+    DeviceCodeExpiredError,
+    AuthorizationDeniedError,
+    TokenExchangeError,
+)
+
+
+@dataclass
+class DeviceFlowResponse:
+    """Response from device flow initiation."""
+
+    user_code: str
+    device_code: str
+    verification_uri: str
+    verification_uri_complete: str
+    expires_in: int
+    interval: int
+
+
+class DeviceFlowClient:
+    """Client for OAuth 2.0 Device Authorization Flow (RFC 8628)."""
+
+    def __init__(self, device_secret: str, ml_dash_server_url: str):
+        """Initialize device flow client.
+
+        Args:
+            device_secret: Persistent device secret for this client
+            ml_dash_server_url: ML-Dash server URL for token exchange
+        """
+        self.device_secret = device_secret
+        self.ml_dash_server_url = ml_dash_server_url.rstrip("/")
+
+    def start_device_flow(self, scope: str = DEFAULT_SCOPE) -> DeviceFlowResponse:
+        """Initiate device authorization flow with vuer-auth.
+
+        Args:
+            scope: OAuth scopes to request
+
+        Returns:
+            DeviceFlowResponse with user code and verification URI
+
+        Raises:
+            httpx.HTTPError: If request fails
+        """
+        response = httpx.post(
+            f"{VUER_AUTH_URL}/api/device-flow/start",
+            json={
+                "client_id": CLIENT_ID,
+                "scope": scope,
+                "device_secret_hash": hash_device_secret(self.device_secret),
+            },
+            timeout=10.0,
+        )
+        response.raise_for_status()
+        data = response.json()
+
+        return DeviceFlowResponse(
+            user_code=data["user_code"],
+            device_code=data.get("device_code", ""),
+            verification_uri=data["verification_uri"],
+            verification_uri_complete=data.get(
+                "verification_uri_complete",
+                f"{data['verification_uri']}?code={data['user_code'].replace('-', '')}"
+            ),
+            expires_in=data.get("expires_in", 600),
+            interval=data.get("interval", 5),
+        )
+
+    def poll_for_token(
+        self,
+        max_attempts: int = 120,
+        progress_callback: Optional[callable] = None,
+    ) -> str:
+        """Poll vuer-auth for authorization completion.
+
+        Args:
+            max_attempts: Maximum polling attempts (default: 120 = 10 minutes at 5s intervals)
+            progress_callback: Optional callback(elapsed_seconds) for progress updates
+
+        Returns:
+            Vuer-auth access token (JWT)
+
+        Raises:
+            DeviceCodeExpiredError: If device code expires
+            AuthorizationDeniedError: If user denies authorization
+            TimeoutError: If polling times out
+        """
+        device_secret_hash = hash_device_secret(self.device_secret)
+
+        for attempt in range(max_attempts):
+            elapsed = attempt * 5  # 5 second intervals
+
+            if progress_callback:
+                progress_callback(elapsed)
+
+            try:
+                response = httpx.post(
+                    f"{VUER_AUTH_URL}/api/device-flow/poll",
+                    json={
+                        "client_id": CLIENT_ID,
+                        "device_secret_hash": device_secret_hash,
+                    },
+                    timeout=10.0,
+                )
+
+                if response.status_code == 200:
+                    # Authorization successful
+                    data = response.json()
+                    return data["access_token"]
+
+                # Check error responses
+                error_data = response.json()
+                error = error_data.get("error")
+
+                if error == "authorization_pending":
+                    # Still waiting for user authorization
+                    time.sleep(5)
+                    continue
+                elif error == "expired_token":
+                    raise DeviceCodeExpiredError(
+                        "Device code expired. Please run 'ml-dash login' again."
+                    )
+                elif error == "access_denied":
+                    raise AuthorizationDeniedError(
+                        "User denied authorization request."
+                    )
+                elif error == "slow_down":
+                    # Server requests slower polling
+                    time.sleep(10)
+                    continue
+                else:
+                    # Unknown error
+                    raise TokenExchangeError(f"Device flow error: {error}")
+
+            except httpx.HTTPError as e:
+                # Network error, retry
+                time.sleep(5)
+                continue
+
+        raise TimeoutError(
+            "Authorization timed out after 10 minutes. Please run 'ml-dash login' again."
+        )
+
+    def exchange_token(self, vuer_auth_token: str) -> str:
+        """Exchange vuer-auth token for ml-dash permanent token.
+
+        This calls the ml-dash server's token exchange endpoint.
+        The server will:
+        1. Decode the vuer-auth JWT
+        2. Validate signature and expiry
+        3. Extract username from claims
+        4. Generate a permanent ml-dash token for that username
+        5. Return the ml-dash token
+
+        Args:
+            vuer_auth_token: Temporary vuer-auth JWT access token
+
+        Returns:
+            Permanent ml-dash token string
+
+        Raises:
+            TokenExchangeError: If exchange fails
+            httpx.HTTPError: If request fails
+        """
+        try:
+            response = httpx.post(
+                f"{self.ml_dash_server_url}/api/auth/exchange",
+                headers={"Authorization": f"Bearer {vuer_auth_token}"},
+                timeout=10.0,
+            )
+            response.raise_for_status()
+            data = response.json()
+
+            ml_dash_token = data.get("ml_dash_token")
+            if not ml_dash_token:
+                raise TokenExchangeError(
+                    "Server response missing ml_dash_token field"
+                )
+
+            return ml_dash_token
+
+        except httpx.HTTPStatusError as e:
+            if e.response.status_code == 401:
+                raise TokenExchangeError(
+                    "Vuer-auth token invalid or expired. Please try logging in again."
+                )
+            elif e.response.status_code == 404:
+                raise TokenExchangeError(
+                    "Token exchange endpoint not found. "
+                    "Please ensure ml-dash server is up to date."
+                )
+            else:
+                raise TokenExchangeError(
+                    f"Token exchange failed: {e.response.status_code} {e.response.text}"
+                )
+        except httpx.HTTPError as e:
+            raise TokenExchangeError(f"Network error during token exchange: {e}")
+
+    def authenticate(
+        self, progress_callback: Optional[callable] = None
+    ) -> str:
+        """Complete full device authorization flow.
+
+        This is a convenience method that:
+        1. Starts device flow with vuer-auth
+        2. Polls for authorization
+        3. Exchanges vuer-auth token for ml-dash token
+
+        Args:
+            progress_callback: Optional callback(elapsed_seconds) for progress updates
+
+        Returns:
+            Permanent ml-dash token string
+
+        Raises:
+            Various authentication exceptions
+        """
+        # Step 1: Start device flow
+        flow = self.start_device_flow()
+
+        # Step 2: Poll for authorization (caller should display user_code)
+        vuer_auth_token = self.poll_for_token(progress_callback=progress_callback)
+
+        # Step 3: Exchange for ml-dash token
+        ml_dash_token = self.exchange_token(vuer_auth_token)
+
+        return ml_dash_token

ml_dash-0.6.3/src/ml_dash/auth/device_secret.py

@@ -0,0 +1,49 @@
+"""Device secret generation and management for ml-dash."""
+
+import hashlib
+import secrets
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from ml_dash.config import Config
+
+
+def generate_device_secret() -> str:
+    """Generate a cryptographically secure device secret.
+
+    Returns:
+        A 64-character hexadecimal string (256 bits of entropy)
+    """
+    return secrets.token_hex(32)  # 32 bytes = 256 bits
+
+
+def hash_device_secret(secret: str) -> str:
+    """Hash device secret using SHA256.
+
+    Args:
+        secret: The device secret to hash
+
+    Returns:
+        SHA256 hash as hexadecimal string
+    """
+    return hashlib.sha256(secret.encode()).hexdigest()
+
+
+def get_or_create_device_secret(config: "Config") -> str:
+    """Load device secret from config or generate a new one.
+
+    Args:
+        config: ML-Dash configuration object
+
+    Returns:
+        Device secret string
+    """
+    device_secret = config.device_secret
+
+    if not device_secret:
+        # Generate new device secret
+        device_secret = generate_device_secret()
+        config.set("device_secret", device_secret)
+        config.save()
+
+    return device_secret