ml-dash 0.1.28__tar.gz → 0.6.1__tar.gz

ml_dash-0.6.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Ge Yang, Tom Tao
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

ml_dash-0.6.1/PKG-INFO

@@ -0,0 +1,248 @@
+Metadata-Version: 2.3
+Name: ml-dash
+Version: 0.6.1
+Summary: ML experiment tracking and data storage
+Keywords: machine-learning,experiment-tracking,mlops,data-storage
+Author: Ge Yang, Tom Tao
+License: MIT License
+         
+         Copyright (c) 2025 Ge Yang, Tom Tao
+         
+         Permission is hereby granted, free of charge, to any person obtaining a copy
+         of this software and associated documentation files (the "Software"), to deal
+         in the Software without restriction, including without limitation the rights
+         to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+         copies of the Software, and to permit persons to whom the Software is
+         furnished to do so, subject to the following conditions:
+         
+         The above copyright notice and this permission notice shall be included in all
+         copies or substantial portions of the Software.
+         
+         THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+         IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+         FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+         AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+         LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+         OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+         SOFTWARE.
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: pyjwt>=2.8.0
+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: 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'
+Requires-Dist: furo>=2024.0.0 ; extra == 'dev'
+Requires-Dist: sphinx-autodoc-typehints>=2.0.0 ; extra == 'dev'
+Requires-Dist: sphinx-autobuild>=2024.0.0 ; extra == 'dev'
+Requires-Dist: sphinx-copybutton>=0.5.0 ; extra == 'dev'
+Requires-Dist: sphinx-design>=0.5.0 ; extra == 'dev'
+Requires-Dist: sphinx-tabs>=3.4.0 ; extra == 'dev'
+Requires-Dist: sphinxcontrib-mermaid>=0.9.0 ; extra == 'dev'
+Requires-Dist: sphinxext-opengraph>=0.9.0 ; extra == 'dev'
+Requires-Dist: myst-parser>=2.0.0 ; extra == 'dev'
+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.
+
+## Features
+
+- **Three Usage Styles**: Decorator, context manager, or direct instantiation
+- **Dual Operation Modes**: Remote (API server) or local (filesystem)
+- **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)
+- **Organized File Storage**: Prefix-based file organization with unique snowflake IDs
+- **Rich Metadata**: Tags, bindrs, descriptions, and custom metadata support
+- **Simple API**: Minimal configuration, maximum flexibility
+
+## Installation
+
+<table>
+<tr>
+<td>Using uv (recommended)</td>
+<td>Using pip</td>
+</tr>
+<tr>
+<td>
+
+```bash
+uv add ml-dash
+```
+
+</td>
+<td>
+
+```bash
+pip install ml-dash
+```
+
+</td>
+</tr>
+</table>
+
+## Getting Started
+
+### Remote Mode (with API Server)
+
+```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}")
+```
+
+### Local Mode (Filesystem)
+
+```python
+from ml_dash import Experiment
+
+with Experiment(
+    name="my-experiment",
+    project="my-project",
+    local_path=".ml-dash"
+) as experiment:
+    pass  # Your code here
+```
+
+See [examples/](examples/) for more complete examples.
+
+## Development Setup
+
+### Installing Dev Dependencies
+
+To contribute to ML-Dash or run tests, install the development dependencies:
+
+<table>
+<tr>
+<td>Using uv (recommended)</td>
+<td>Using pip</td>
+</tr>
+<tr>
+<td>
+
+```bash
+uv sync --extra dev
+```
+
+</td>
+<td>
+
+```bash
+pip install -e ".[dev]"
+```
+
+</td>
+</tr>
+</table>
+
+This installs:
+- `pytest>=8.0.0` - Testing framework
+- `pytest-asyncio>=0.23.0` - Async test support
+- `sphinx>=7.2.0` - Documentation builder
+- `sphinx-rtd-theme>=2.0.0` - Read the Docs theme
+- `sphinx-autobuild>=2024.0.0` - Live preview for documentation
+- `myst-parser>=2.0.0` - Markdown support for Sphinx
+- `ruff>=0.3.0` - Linter and formatter
+- `mypy>=1.9.0` - Type checker
+
+### Running Tests
+
+<table>
+<tr>
+<td>Using uv</td>
+<td>Using pytest directly</td>
+</tr>
+<tr>
+<td>
+
+```bash
+uv run pytest
+```
+
+</td>
+<td>
+
+```bash
+pytest
+```
+
+</td>
+</tr>
+</table>
+
+### Building Documentation
+
+Documentation is built using Sphinx with Read the Docs theme.
+
+<table>
+<tr>
+<td>Build docs</td>
+<td>Live preview</td>
+<td>Clean build</td>
+</tr>
+<tr>
+<td>
+
+```bash
+uv run python -m sphinx -b html docs docs/_build/html
+```
+
+</td>
+<td>
+
+```bash
+uv run sphinx-autobuild docs docs/_build/html
+```
+
+</td>
+<td>
+
+```bash
+rm -rf docs/_build
+```
+
+</td>
+</tr>
+</table>
+
+The live preview command starts a local server and automatically rebuilds when files change.
+
+Alternatively, you can use the Makefile from within the docs directory:
+
+```bash
+cd docs
+make html          # Build HTML documentation
+make clean         # Clean build files
+```
+
+For maintainers, to build and publish a new release: `uv build && uv publish`

ml_dash-0.6.1/README.md

@@ -0,0 +1,181 @@
+# ML-Dash
+
+A simple and flexible SDK for ML experiment metricing and data storage.
+
+## Features
+
+- **Three Usage Styles**: Decorator, context manager, or direct instantiation
+- **Dual Operation Modes**: Remote (API server) or local (filesystem)
+- **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)
+- **Organized File Storage**: Prefix-based file organization with unique snowflake IDs
+- **Rich Metadata**: Tags, bindrs, descriptions, and custom metadata support
+- **Simple API**: Minimal configuration, maximum flexibility
+
+## Installation
+
+<table>
+<tr>
+<td>Using uv (recommended)</td>
+<td>Using pip</td>
+</tr>
+<tr>
+<td>
+
+```bash
+uv add ml-dash
+```
+
+</td>
+<td>
+
+```bash
+pip install ml-dash
+```
+
+</td>
+</tr>
+</table>
+
+## Getting Started
+
+### Remote Mode (with API Server)
+
+```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}")
+```
+
+### Local Mode (Filesystem)
+
+```python
+from ml_dash import Experiment
+
+with Experiment(
+    name="my-experiment",
+    project="my-project",
+    local_path=".ml-dash"
+) as experiment:
+    pass  # Your code here
+```
+
+See [examples/](examples/) for more complete examples.
+
+## Development Setup
+
+### Installing Dev Dependencies
+
+To contribute to ML-Dash or run tests, install the development dependencies:
+
+<table>
+<tr>
+<td>Using uv (recommended)</td>
+<td>Using pip</td>
+</tr>
+<tr>
+<td>
+
+```bash
+uv sync --extra dev
+```
+
+</td>
+<td>
+
+```bash
+pip install -e ".[dev]"
+```
+
+</td>
+</tr>
+</table>
+
+This installs:
+- `pytest>=8.0.0` - Testing framework
+- `pytest-asyncio>=0.23.0` - Async test support
+- `sphinx>=7.2.0` - Documentation builder
+- `sphinx-rtd-theme>=2.0.0` - Read the Docs theme
+- `sphinx-autobuild>=2024.0.0` - Live preview for documentation
+- `myst-parser>=2.0.0` - Markdown support for Sphinx
+- `ruff>=0.3.0` - Linter and formatter
+- `mypy>=1.9.0` - Type checker
+
+### Running Tests
+
+<table>
+<tr>
+<td>Using uv</td>
+<td>Using pytest directly</td>
+</tr>
+<tr>
+<td>
+
+```bash
+uv run pytest
+```
+
+</td>
+<td>
+
+```bash
+pytest
+```
+
+</td>
+</tr>
+</table>
+
+### Building Documentation
+
+Documentation is built using Sphinx with Read the Docs theme.
+
+<table>
+<tr>
+<td>Build docs</td>
+<td>Live preview</td>
+<td>Clean build</td>
+</tr>
+<tr>
+<td>
+
+```bash
+uv run python -m sphinx -b html docs docs/_build/html
+```
+
+</td>
+<td>
+
+```bash
+uv run sphinx-autobuild docs docs/_build/html
+```
+
+</td>
+<td>
+
+```bash
+rm -rf docs/_build
+```
+
+</td>
+</tr>
+</table>
+
+The live preview command starts a local server and automatically rebuilds when files change.
+
+Alternatively, you can use the Makefile from within the docs directory:
+
+```bash
+cd docs
+make html          # Build HTML documentation
+make clean         # Clean build files
+```
+
+For maintainers, to build and publish a new release: `uv build && uv publish`

ml_dash-0.6.1/pyproject.toml

@@ -0,0 +1,66 @@
+[project]
+name = "ml-dash"
+version = "0.6.1"
+description = "ML experiment tracking and data storage"
+readme = "README.md"
+requires-python = ">=3.9"
+license = {file = "LICENSE"}
+authors = [
+    {name = "Ge Yang"},
+    {name = "Tom Tao"}
+]
+keywords = ["machine-learning", "experiment-tracking", "mlops", "data-storage"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Intended Audience :: Science/Research",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+]
+dependencies = [
+    "httpx>=0.27.0",
+    "pyjwt>=2.8.0",
+    "imageio>=2.31.0",
+    "imageio-ffmpeg>=0.4.9",
+    "scikit-image>=0.21.0",
+    "rich>=13.0.0",
+    "cryptography>=42.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",
+    "sphinx>=7.2.0",
+    "furo>=2024.0.0",
+    "sphinx-autodoc-typehints>=2.0.0",
+    "sphinx-autobuild>=2024.0.0",
+    "sphinx-copybutton>=0.5.0",
+    "sphinx-design>=0.5.0",
+    "sphinx-tabs>=3.4.0",
+    "sphinxcontrib-mermaid>=0.9.0",
+    "sphinxext-opengraph>=0.9.0",
+    "myst-parser>=2.0.0",
+    "linkify-it-py>=2.0.0",
+    "ruff>=0.3.0",
+    "mypy>=1.9.0",
+]
+
+[tool.uv]
+
+[build-system]
+requires = ["uv_build>=0.9.2,<0.10.0"]
+build-backend = "uv_build"

ml_dash-0.6.1/src/ml_dash/__init__.py

@@ -0,0 +1,85 @@
+"""
+ML-Dash Python SDK
+
+A simple and flexible SDK for ML experiment metricing and data storage.
+
+Usage:
+
+    # 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",
+        local_path=".ml-dash"
+    ) as experiment:
+        experiment.log("Training started")
+        experiment.params.set(lr=0.001)
+        experiment.metrics("loss").append(step=0, value=0.5)
+
+    # Remote mode - explicit configuration
+    with Experiment(
+        name="my-experiment",
+        project="my-project",
+        remote="https://api.dash.ml",
+        api_key="your-jwt-token"
+    ) as experiment:
+        experiment.log("Training started")
+
+    # Decorator style
+    from ml_dash import ml_dash_experiment
+
+    @ml_dash_experiment(
+        name="my-experiment",
+        project="my-project"
+    )
+    def train_model(experiment):
+        experiment.log("Training started")
+"""
+
+from .experiment import Experiment, ml_dash_experiment, OperationMode, RunManager
+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"
+
+__all__ = [
+    "Experiment",
+    "ml_dash_experiment",
+    "OperationMode",
+    "RunManager",
+    "RemoteClient",
+    "LocalStorage",
+    "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-0.6.1/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.1/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"