ml-dash

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

Using uv (recommended)	Using pip
uv add ml-dash	pip install ml-dash

Getting Started

Remote Mode (with API Server)

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)

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/ for more complete examples.

Development Setup

Installing Dev Dependencies

To contribute to ML-Dash or run tests, install the development dependencies:

Using uv (recommended)	Using pip
uv sync --extra dev	pip install -e ".[dev]"

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

Using uv	Using pytest directly
uv run pytest	pytest

Building Documentation

Documentation is built using Sphinx with Read the Docs theme.

Build docs	Live preview	Clean build
uv run python -m sphinx -b html docs docs/_build/html	uv run sphinx-autobuild docs docs/_build/html	rm -rf docs/_build

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:

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