Experiments

The Experiment class is the core abstraction in ML-Dash. A single instance owns one run's logs, parameters, metrics, and files.

Prefix Format

The prefix is a universal key that identifies an experiment:

owner/project/path.../name

owner: first segment (e.g. your username)
project: second segment
path: any number of intermediate segments forming a folder path
name: last segment

Reopening the same prefix resumes that experiment (upsert semantics).

Constructor

python

Experiment(
    prefix: str | None = None,        # owner/project/.../name (or DASH_PREFIX env)
    *,
    readme: str | None = None,        # human-readable description
    tags: list[str] | None = None,    # categorization
    bindrs: list[str] | None = None,  # resource/team association
    metadata: dict | None = None,
    dash_url: str | bool | None = None,  # remote API URL (None = local-only)
    dash_root: str | None = ".dash",     # local storage root (None = remote-only)
    **run_params,                        # forwarded to the RUN namespace
)

Mode is inferred from dash_url / dash_root:

dash_root only (default): local-only, writes to .dash/
dash_url + dash_root: hybrid (local + remote)
dash_url, dash_root=None: remote-only

The auth token is auto-loaded from ~/.dash/token.enc when dash_url is set.

The `.run` Lifecycle

Every Experiment exposes .run, a context manager that drives the lifecycle:

Method	Status set	Notes
`exp.run.start()`	RUNNING	also performed by `__enter__`
`exp.run.complete()`	COMPLETED	called by `__exit__` on clean exit
`exp.run.fail()`	FAILED	called by `__exit__` if an exception propagates
`exp.run.cancel()`	CANCELLED	manual only

Status updates require remote mode; local mode does not track status.

Usage

Context manager (recommended):

python

from ml_dash import Experiment

with Experiment(prefix="alice/project/my-experiment").run as exp:
    exp.log("Training started")
    exp.params.set(learning_rate=0.001)
    exp.metrics("train").log(loss=0.5, epoch=1)
    exp.files("models").save("model.pth")

For decorator-style usage (@ml_dash_experiment(...)) and the RUN.entry = __file__ auto-prefix pattern, see Getting Started. For full multi-step training scripts, see Complete Examples.

What Lives Where

Once an experiment is open, feature-specific APIs are documented on their own pages:

Logging — exp.log(...)
Parameters — exp.params.set(...)
Metrics — exp.metrics(track).log(...)
Files — exp.files(prefix).save(...)