ml-dash 0.6.1__py3-none-any.whl

ml_dash/params.py

@@ -0,0 +1,277 @@
+"""
+Parameters module for ML-Dash SDK.
+
+Provides fluent API for parameter management with automatic dict flattening.
+Nested dicts are flattened to dot-notation: {"model": {"lr": 0.001}} → {"model.lr": 0.001}
+"""
+
+from typing import Dict, Any, Optional, TYPE_CHECKING
+import inspect
+
+if TYPE_CHECKING:
+    from .experiment import Experiment
+
+
+class ParametersBuilder:
+    """
+    Fluent interface for parameter operations.
+
+    Usage:
+        experiment.parameters().set(model={"lr": 0.001}, optimizer="adam")
+        params = experiment.parameters().get()
+        params_nested = experiment.parameters().get(flatten=False)
+    """
+
+    def __init__(self, experiment: 'Experiment'):
+        """
+        Initialize parameters builder.
+
+        Args:
+            experiment: Parent experiment instance
+        """
+        self._experiment = experiment
+
+    def set(self, **kwargs) -> 'ParametersBuilder':
+        """
+        Set/merge parameters. Always merges with existing parameters (upsert behavior).
+
+        Nested dicts are automatically flattened:
+            set(model={"lr": 0.001, "batch_size": 32})
+            → {"model.lr": 0.001, "model.batch_size": 32}
+
+        Args:
+            **kwargs: Parameters to set (can be nested dicts)
+
+        Returns:
+            Self for potential chaining
+
+        Raises:
+            RuntimeError: If experiment is not open
+            RuntimeError: If experiment is write-protected
+
+        Examples:
+            # Set nested parameters
+            experiment.parameters().set(
+                model={"lr": 0.001, "batch_size": 32},
+                optimizer="adam"
+            )
+
+            # Merge/update specific parameters
+            experiment.parameters().set(model={"lr": 0.0001})  # Only updates model.lr
+
+            # Set flat parameters with dot notation
+            experiment.parameters().set(**{"model.lr": 0.001, "model.batch_size": 32})
+        """
+        if not self._experiment._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.params.set(lr=0.001)"
+            )
+
+        if self._experiment._write_protected:
+            raise RuntimeError("Experiment is write-protected and cannot be modified.")
+
+        # Convert class objects to dicts (for params_proto support)
+        processed_kwargs = self._process_class_objects(kwargs)
+
+        # Flatten the kwargs
+        flattened = self.flatten_dict(processed_kwargs)
+
+        if not flattened:
+            # No parameters to set, just return
+            return self
+
+        # Write parameters through experiment
+        self._experiment._write_params(flattened)
+
+        return self
+
+    def log(self, **kwargs) -> 'ParametersBuilder':
+        """
+        Alias for set(). Sets/merges parameters.
+
+        This method exists for better parameter organization and semantic clarity.
+        It behaves exactly the same as set().
+
+        Nested dicts are automatically flattened:
+            log(model={"lr": 0.001, "batch_size": 32})
+            → {"model.lr": 0.001, "model.batch_size": 32}
+
+        Args:
+            **kwargs: Parameters to set (can be nested dicts)
+
+        Returns:
+            Self for potential chaining
+
+        Raises:
+            RuntimeError: If experiment is not open
+            RuntimeError: If experiment is write-protected
+
+        Examples:
+            # Set parameters using log() - same as set()
+            experiment.params.log(
+                learning_rate=0.001,
+                batch_size=32,
+                model="resnet50"
+            )
+
+            # Track parameter changes during training
+            for epoch in range(10):
+                if epoch == 5:
+                    experiment.params.log(learning_rate=0.0001)  # Log LR decay
+        """
+        # Just call set() - they behave exactly the same
+        return self.set(**kwargs)
+
+    def get(self, flatten: bool = True) -> Dict[str, Any]:
+        """
+        Get parameters from the experiment.
+
+        Args:
+            flatten: If True, returns flattened dict with dot notation.
+                    If False, returns nested dict structure.
+
+        Returns:
+            Parameters dict (flattened or nested based on flatten arg)
+
+        Raises:
+            RuntimeError: If experiment is not open
+
+        Examples:
+            # Get flattened parameters
+            params = experiment.parameters().get()
+            # → {"model.lr": 0.001, "model.batch_size": 32, "optimizer": "adam"}
+
+            # Get nested parameters
+            params = experiment.parameters().get(flatten=False)
+            # → {"model": {"lr": 0.001, "batch_size": 32}, "optimizer": "adam"}
+        """
+        if not self._experiment._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.params.get()"
+            )
+
+        # Read parameters through experiment
+        params = self._experiment._read_params()
+
+        if params is None:
+            return {}
+
+        # Return as-is if flatten=True (stored flattened), or unflatten if needed
+        if flatten:
+            return params
+        else:
+            return self.unflatten_dict(params)
+
+    @staticmethod
+    def flatten_dict(d: Dict[str, Any], parent_key: str = '', sep: str = '.') -> Dict[str, Any]:
+        """
+        Flatten a nested dictionary into dot-notation keys.
+
+        Args:
+            d: Dictionary to flatten (can contain nested dicts)
+            parent_key: Prefix for keys (used in recursion)
+            sep: Separator character (default: '.')
+
+        Returns:
+            Flattened dictionary with dot-notation keys
+
+        Examples:
+            >>> flatten_dict({"a": {"b": 1, "c": 2}, "d": 3})
+            {"a.b": 1, "a.c": 2, "d": 3}
+
+            >>> flatten_dict({"model": {"lr": 0.001, "layers": {"hidden": 128}}})
+            {"model.lr": 0.001, "model.layers.hidden": 128}
+        """
+        items = []
+
+        for k, v in d.items():
+            new_key = f"{parent_key}{sep}{k}" if parent_key else k
+
+            if isinstance(v, dict):
+                # Recursively flatten nested dicts
+                items.extend(ParametersBuilder.flatten_dict(v, new_key, sep=sep).items())
+            else:
+                # Keep non-dict values as-is
+                items.append((new_key, v))
+
+        return dict(items)
+
+    @staticmethod
+    def unflatten_dict(d: Dict[str, Any], sep: str = '.') -> Dict[str, Any]:
+        """
+        Unflatten a dot-notation dictionary into nested structure.
+
+        Args:
+            d: Flattened dictionary with dot-notation keys
+            sep: Separator character (default: '.')
+
+        Returns:
+            Nested dictionary structure
+
+        Examples:
+            >>> unflatten_dict({"a.b": 1, "a.c": 2, "d": 3})
+            {"a": {"b": 1, "c": 2}, "d": 3}
+
+            >>> unflatten_dict({"model.lr": 0.001, "model.layers.hidden": 128})
+            {"model": {"lr": 0.001, "layers": {"hidden": 128}}}
+        """
+        result = {}
+
+        for key, value in d.items():
+            parts = key.split(sep)
+            current = result
+
+            # Navigate/create nested structure
+            for part in parts[:-1]:
+                if part not in current:
+                    current[part] = {}
+                current = current[part]
+
+            # Set the final value
+            current[parts[-1]] = value
+
+        return result
+
+    @staticmethod
+    def _process_class_objects(d: Dict[str, Any]) -> Dict[str, Any]:
+        """
+        Convert class objects to dicts by extracting their attributes.
+
+        This enables passing configuration classes directly:
+            dxp.params.log(Args=Args)  # Args is a class
+            → {"Args": {"batch_size": 64, "lr": 0.001, ...}}
+
+        Args:
+            d: Dictionary that may contain class objects as values
+
+        Returns:
+            Dictionary with class objects converted to attribute dicts
+
+        Examples:
+            >>> class Args:
+            ...     batch_size = 64
+            ...     lr = 0.001
+            >>> _process_class_objects({"Args": Args})
+            {"Args": {"batch_size": 64, "lr": 0.001}}
+        """
+        result = {}
+        for key, value in d.items():
+            if inspect.isclass(value):
+                # Extract class attributes (skip private/magic and callables)
+                attrs = {}
+                for attr_name, attr_value in vars(value).items():
+                    if not attr_name.startswith('_') and not callable(attr_value):
+                        # Recursively handle nested types
+                        if isinstance(attr_value, type):
+                            continue  # Skip type annotations
+                        attrs[attr_name] = attr_value
+                result[key] = attrs
+            else:
+                result[key] = value
+        return result

ml_dash/remote_auto_start.py

@@ -0,0 +1,55 @@
+"""
+Pre-configured remote experiment singleton for ML-Dash SDK.
+
+Provides a pre-configured experiment singleton named 'rdxp' that uses remote mode.
+Requires manual start using 'with' statement or explicit start() call.
+
+IMPORTANT: Before using rdxp, you must authenticate with the ML-Dash server:
+    # First time setup - authenticate with the server
+    python -m ml_dash.cli login
+
+Usage:
+    from ml_dash import rdxp
+
+    # Use with statement (recommended)
+    with rdxp.run:
+        rdxp.log().info("Hello from rdxp!")
+        rdxp.params.set(lr=0.001)
+        rdxp.metrics("loss").append(step=0, value=0.5)
+    # Automatically completes on exit from with block
+
+    # Or start/complete manually
+    rdxp.run.start()
+    rdxp.log().info("Training...")
+    rdxp.run.complete()
+
+Configuration:
+    - Default server: https://api.dash.ml
+    - To use a different server, set MLDASH_API_URL environment variable
+    - Authentication token is auto-loaded from secure storage
+"""
+
+import atexit
+from .experiment import Experiment
+
+# Create pre-configured singleton experiment for remote mode
+# Uses remote API server - token auto-loaded from storage
+rdxp = Experiment(
+    name="rdxp",
+    project="scratch",
+    remote="https://api.dash.ml"
+)
+
+# Register cleanup handler to complete experiment on Python exit (if still open)
+def _cleanup():
+    """Complete the rdxp experiment on exit if still open."""
+    if rdxp._is_open:
+        try:
+            rdxp.run.complete()
+        except Exception:
+            # Silently ignore errors during cleanup
+            pass
+
+atexit.register(_cleanup)
+
+__all__ = ["rdxp"]