ML-Dash

A simple and flexible SDK for ML experiment tracking and data storage with background buffering for high-performance training.

Features

Core Features

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; the SDK reads the token the ml-dash CLI stores
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

Performance Features (New in 0.6.7)

Background Buffering: Non-blocking I/O operations eliminate training interruptions
Automatic Batching: Time-based (5s) and size-based (100 items) flush triggers
Track API: Time-series data tracking for robotics, RL, and sequential experiments
Numpy Image Support: Direct saving of numpy arrays as PNG/JPEG images
Parallel Uploads: ThreadPoolExecutor for efficient file uploads

Installation

This repo is the Python SDK — the library you import ml_dash from. The ml-dash command line is a separate program, distributed on npm; see The CLI moved to npm below.

SDK (this package)

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

CLI

Version 0.1.1, published as @dreamlake/ml-dash. With Node.js >= 20.19:

npm install -g @dreamlake/ml-dash

Or a self-contained binary, needing neither Node.js nor Python:

# macOS / Linux
curl -fsSL https://pub-42e1dcc7de574d4a92984865fdc95f10.r2.dev/install.sh | sh

# Windows PowerShell
irm https://pub-42e1dcc7de574d4a92984865fdc95f10.r2.dev/install.ps1 | iex

On Alpine the musl builds need apk add --no-cache libstdc++.

The package is scoped because the unscoped ml-dash name is not claimable on npm, but the command is still ml-dash. Either channel updates itself, in place and through the channel it was installed from:

ml-dash update --check   # report whether a newer release exists
ml-dash update           # install it

The CLI moved to npm

Up to and including 0.6.27, pip install ml-dash also put an ml-dash executable on your PATH. From 0.7.0 it does not: the command line has been rewritten in TypeScript and ships on its own — as the npm package @dreamlake/ml-dash or the standalone installer above — so it installs and updates without touching your training environment's Python dependencies. Upgrading the Python package to 0.7.0 removes the old executable; install the new CLI alongside it.

Nothing about the SDK changes. pip install ml-dash is still how you get ml_dash, and every Experiment, files, tracks, and storage API is untouched.

	Before	Now
SDK (`import ml_dash`)	`pip install ml-dash`	`pip install ml-dash`
CLI (`ml-dash login`, `upload`, …)	`pip install ml-dash`	`npm install -g @dreamlake/ml-dash`, or the standalone installer

The command names and arguments carry over, and the two share a credential store: the CLI writes its token to the same OS keyring entry (and the same ~/.dash/ fallback files) that ml_dash.auth.token_storage reads, so ml-dash login still authenticates your Python code and an existing valid login is normally picked up as-is. Re-run ml-dash login if it is not.

Command behaviour is not identical — the rewrite changes and fixes a number of things — and the CLI's own release notes are where those differences are described.

If you were importing ml_dash.cli or ml_dash.cli_commands.* directly from Python — an unsupported path, but a real one — those modules are gone. Shell out to the ml-dash binary instead.

Releases up to 0.6.27 keep the old Python CLI; pin ml-dash<0.7 only if you cannot install the new one yet.

Quick Start

1. Authenticate (Required for Remote Mode)

npm install -g @dreamlake/ml-dash   # one time; requires Node.js >= 20.19
                                    # (or use the standalone installer above)
ml-dash login

This opens your browser for secure OAuth2 authentication. Your credentials are stored securely in your system keychain — where the Python SDK reads them.

2. Start Tracking Experiments

Option A: Use the Pre-configured Singleton (Easiest)

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

from ml_dash import Experiment

with Experiment(
  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)

Option C: Local Mode (No Authentication Required)

from ml_dash import Experiment

with Experiment(
  project="my-project", prefix="my-experiment", dash_root=".dash"
).run as experiment:
  experiment.log("Running locally", level="info")

New Features in 0.6.7

🚀 Background Buffering (Non-blocking I/O)

All write operations are now buffered and executed in background threads:

with Experiment("my-project/exp").run as experiment:
    for i in range(10000):
        # Non-blocking! Returns immediately
        experiment.log(f"Step {i}")
        experiment.metrics("train").log(loss=loss, accuracy=acc)
        experiment.files("frames").save_image(frame, to=f"frame_{i}.jpg")

    # All data automatically flushed when context exits

Configure buffering via environment variables:

export ML_DASH_BUFFER_ENABLED=true
export ML_DASH_FLUSH_INTERVAL=5.0
export ML_DASH_LOG_BATCH_SIZE=100

📊 Track API (Time-Series Data)

Perfect for robotics, RL, and sequential experiments. Supports timestamp inheritance for synchronized multi-modal data and track slicing for efficient querying.

with Experiment("robotics/training").run as experiment:
    for step in range(1000):
        # First track auto-generates timestamp
        experiment.tracks("robot/position").append(
            step=step,
            x=position[0],
            y=position[1],
            z=position[2]
        )

        # Other tracks inherit same timestamp with _ts=-1 (synchronized!)
        experiment.tracks("camera/left").append(width=640, height=480, _ts=-1)
        experiment.tracks("robot/velocity").append(vx=0.1, vy=0.0, _ts=-1)
        experiment.tracks("sensors/lidar").append(ranges=[1.5, 2.0], _ts=-1)

    experiment.tracks.flush()

    # Query synchronized data with floor-match timestamp queries
    pose_slice = experiment.tracks("robot/position").slice(0.0, 10.0)

    # Single timestamp query
    entry = pose_slice.findByTime(5.5)  # Returns entry at timestamp 5.0

    # Batch queries
    entries = pose_slice.findByTime([1.0, 3.5, 7.0])  # Returns list of 3 entries

    # Iterate through time range
    for entry in pose_slice:
        print(entry["timestamp"], entry["x"], entry["y"])

See the Tracks guide for complete documentation.

🖼️ Numpy Image Support

Save numpy arrays directly as images (PNG/JPEG):

import numpy as np

with Experiment("vision/training").run as experiment:
    # From MuJoCo, OpenCV, PIL, etc.
    pixels = renderer.render()  # numpy array

    # Save as PNG (lossless)
    experiment.files("frames").save_image(pixels, to="frame.png")

    # Save as JPEG with quality control
    experiment.files("frames").save_image(pixels, to="frame.jpg", quality=85)

    # Auto-detection also works
    experiment.files("frames").save(pixels, to="frame.jpg")

See CHANGELOG.md for complete release notes.

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
ruff>=0.3.0 - Linter and formatter
mypy>=1.9.0 - Type checker

The Sphinx toolchain is gone with the docs tree — see Documentation below.

Running Tests

Using uv	Using pytest directly
uv run pytest	pytest

Documentation

The docs live at docs.dash.ml and are built from dreamlake-ai/dash-workspace (docs/), not from this repo. The Sphinx tree that used to sit in docs/ and the Docusaurus site in website/ have both been retired — they had drifted apart from each other and from the SDK, and one of them documented _ts as a required argument that raises ValueError when it is optional and raises ConfigurationError.

Doc changes therefore go to that repo. It runs a check:sdk guard that verifies every python snippet against the installed ml_dash, so a signature change here will fail the docs build there rather than sit unnoticed.

The skills/dash-docs/ directory is a vendored copy of the generated agent skill. Never edit it by hand:

make sync-skill    # refresh from docs.dash.ml
make check-skill   # fail if the vendored copy is stale

For maintainers, to build and publish a new release: uv build && uv publish (this publishes the SDK only — the CLI is released from its own npm repo).

Metadata

Release files for ml-dash 0.7.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for ml-dash 0.7.0
File	Size	Uploaded
ml_dash-0.7.0.tar.gz	82.8 kB	Sep 24, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for ml-dash 0.7.0
File	Interpreter	ABI	Platform	Reset
ml_dash-0.7.0-py3-none-any.whl 92.0 kB Sep 24, 2026	Python 3	none	any	Details

Total release size: 174.8 kB

Release files / ml_dash-0.7.0.tar.gz

Download URL	ml_dash-0.7.0.tar.gz
Size	82.8 kB
Tags	Source
SHA-256 checksum How to use checksums	`4a6c0080831223ec25833bfbb5d3056e13f2ce5f03f5c9f03c4e4f75b5e02317`
BLAKE2b-256 checksum How to use checksums	`20620fd9339a4e7ad467edda0511631f700f391c1a23b2766f9ece8f1a226041`
Upload date	Sep 24, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/7.0.0 CPython/3.13.14`

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/fortyfive-labs/ml-dash
Publishing commit: github.com/fortyfive-labs/ml-dash/tree/95bc1efdd7489391927fdddcfc9bd3321518cba9

Workflow

Publishing configuration: github.com/fortyfive-labs/ml-dash/blob/95bc1efdd7489391927fdddcfc9bd3321518cba9/.github/workflows/release.yml
Publishing logs: github.com/fortyfive-labs/ml-dash/actions/runs/35964969159/attempts/2

Artifact

Subject: ml_dash-0.7.0.tar.gz
SHA-256 checksum: 4a6c0080831223ec25833bfbb5d3056e13f2ce5f03f5c9f03c4e4f75b5e02317 Verifying attestations

Release files / ml_dash-0.7.0-py3-none-any.whl

Download URL	ml_dash-0.7.0-py3-none-any.whl
Size	92.0 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`f78e636cec737b24ce7fa785b0017e59055c3dd603d5551a7607f34649bdd7b8`
BLAKE2b-256 checksum How to use checksums	`ad576dfb722561aec37ac0d9973d23c303e00d615bc9eae5a509866f864d9e75`
Upload date	Sep 24, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/7.0.0 CPython/3.13.14`

Provenance

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/fortyfive-labs/ml-dash
Publishing commit: github.com/fortyfive-labs/ml-dash/tree/95bc1efdd7489391927fdddcfc9bd3321518cba9

Workflow

Publishing configuration: github.com/fortyfive-labs/ml-dash/blob/95bc1efdd7489391927fdddcfc9bd3321518cba9/.github/workflows/release.yml
Publishing logs: github.com/fortyfive-labs/ml-dash/actions/runs/35964969159/attempts/2

Artifact

Subject: ml_dash-0.7.0-py3-none-any.whl
SHA-256 checksum: f78e636cec737b24ce7fa785b0017e59055c3dd603d5551a7607f34649bdd7b8 Verifying attestations