ml-dash 0.5.8__py3-none-any.whl → 0.6.0__py3-none-any.whl

ml_dash/__init__.py

@@ -5,23 +5,33 @@ A simple and flexible SDK for ML experiment metricing and data storage.
 
 Usage:
 
-    # Remote mode (API server)
+    # Quickest - dxp (pre-configured remote singleton)
+    # Requires: ml-dash login
+    from ml_dash import dxp
+
+    with dxp.run:
+        dxp.params.set(lr=0.001)
+        dxp.log().info("Training started")
+    # Auto-completes on exit from with block
+
+    # Local mode - explicit configuration
     from ml_dash import Experiment
 
     with Experiment(
         name="my-experiment",
         project="my-project",
-        remote="http://localhost:3000",
-        api_key="your-jwt-token"
+        local_path=".ml-dash"
     ) as experiment:
         experiment.log("Training started")
-        experiment.metric("loss", {"step": 0, "value": 0.5})
+        experiment.params.set(lr=0.001)
+        experiment.metrics("loss").append(step=0, value=0.5)
 
-    # Local mode (filesystem)
+    # Remote mode - explicit configuration
     with Experiment(
         name="my-experiment",
         project="my-project",
-        local_path=".ml-dash"
+        remote="https://api.dash.ml",
+        api_key="your-jwt-token"
     ) as experiment:
         experiment.log("Training started")
 
@@ -30,9 +40,7 @@ Usage:
 
     @ml_dash_experiment(
         name="my-experiment",
-        project="my-project",
-        remote="http://localhost:3000",
-        api_key="your-jwt-token"
+        project="my-project"
     )
     def train_model(experiment):
         experiment.log("Training started")
@@ -43,6 +51,7 @@ from .client import RemoteClient
 from .storage import LocalStorage
 from .log import LogLevel, LogBuilder
 from .params import ParametersBuilder
+from .auto_start import dxp
 
 __version__ = "0.1.0"
 
@@ -56,4 +65,21 @@ __all__ = [
     "LogLevel",
     "LogBuilder",
     "ParametersBuilder",
+    "dxp",
 ]
+
+# Hidden for now - rdxp (remote auto-start singleton)
+# Will be exposed in a future release
+#
+# # Lazy-load rdxp to avoid auto-connecting to server on package import
+# _rdxp = None
+#
+# def __getattr__(name):
+#     """Lazy-load rdxp only when accessed."""
+#     if name == "rdxp":
+#         global _rdxp
+#         if _rdxp is None:
+#             from .remote_auto_start import rdxp as _loaded_rdxp
+#             _rdxp = _loaded_rdxp
+#         return _rdxp
+#     raise AttributeError(f"module '{__name__}' has no attribute '{name}'")

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/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/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/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

ml_dash/auth/exceptions.py

@@ -0,0 +1,31 @@
+"""Custom exceptions for ml-dash authentication."""
+
+
+class AuthenticationError(Exception):
+    """Base exception for authentication errors."""
+    pass
+
+
+class NotAuthenticatedError(AuthenticationError):
+    """Raised when user is not authenticated."""
+    pass
+
+
+class DeviceCodeExpiredError(AuthenticationError):
+    """Raised when device code expires before authorization."""
+    pass
+
+
+class AuthorizationDeniedError(AuthenticationError):
+    """Raised when user denies authorization request."""
+    pass
+
+
+class TokenExchangeError(AuthenticationError):
+    """Raised when token exchange with ml-dash server fails."""
+    pass
+
+
+class StorageError(Exception):
+    """Base exception for token storage errors."""
+    pass