ML-Dash API Reference

Complete API reference for the ML-Dash Python SDK. For tutorials and workflow examples, see /parameters, /metrics, /files, and /complete-examples.

Table of Contents

• Experiment
  • Constructor
  • Properties
  • RunManager (exp.run)
• Parameters (exp.params)
• Logging (exp.log, exp.logs)
• Metrics (exp.metrics)
• Files (exp.files)
• Auto-Start (dxp)

Experiment

The Experiment class is the main entry point for ML-Dash. It represents a single machine learning experiment run.

from ml_dash import Experiment

Constructor

Experiment(
    prefix: Optional[str] = None,
    *,
    readme: Optional[str] = None,
    tags: Optional[List[str]] = None,
    bindrs: Optional[List[str]] = None,
    metadata: Optional[Dict[str, Any]] = None,
    dash_url: Optional[Union[str, bool]] = None,
    dash_root: Optional[str] = ".dash",
)

Parameters:

Prefix format: owner/project/path.../name — first segment is owner, second is project, remaining segments form the folder path, last segment becomes the experiment name.

Example:

# Local mode
exp = Experiment(prefix="alice/my-project/exp-001", dash_root=".dash")

# Remote mode
exp = Experiment(
    prefix="alice/my-project/exp-001",
    dash_url="https://custom-server.com",
)

Properties

RunManager

exp.run returns a RunManager supporting three usage patterns: context manager, decorator, or manual control.

Context Manager

with Experiment(prefix="alice/proj/exp").run as exp:
    exp.log("Training started")
    # Auto-completes on success, auto-fails on exception

Decorator

exp = Experiment(prefix="alice/proj/exp")

@exp.run
def train(experiment):
    experiment.log("Training...")
    return "done"

result = train()

Manual Control

exp.run.start()
try:
    exp.log("Training...")
    exp.run.complete()
except Exception:
    exp.run.fail()

Methods

Parameters

Access via the exp.params property. See /parameters for usage patterns.

params.set(**kwargs)

Set or merge experiment parameters. Supports nested dicts (auto-flattened to dot notation for storage).

Returns: ParametersBuilder

exp.params.set(learning_rate=0.001, batch_size=32)
exp.params.set(model={"architecture": "resnet50", "layers": 50})
# Stored as: {"learning_rate": 0.001, "batch_size": 32,
#             "model.architecture": "resnet50", "model.layers": 50}

params.get(flatten=True)

Retrieve parameters.

Parameters:

Returns: dict

flat = exp.params.get()
# {"learning_rate": 0.001, "model.architecture": "resnet50"}

nested = exp.params.get(flatten=False)
# {"learning_rate": 0.001, "model": {"architecture": "resnet50"}}

Logging

Log messages with severity levels and optional metadata. See /logging for patterns.

exp.log(message, level="info", metadata=None, **kwargs)

Log a message.

Parameters:

exp.log("Training started")
exp.log("Warning: Low GPU memory", level="warn")
exp.log("Epoch completed", level="info", epoch=1, loss=0.5)

Fluent API: exp.logs

Convenience methods for each level.

exp.logs.info("Training started", epoch=1)
exp.logs.error("Failed to load data", error_code=500)

Log Levels

Metrics

Track time-series metrics. Access via exp.metrics. See /metrics for patterns.

exp.metrics(prefix)

Create/get a MetricBuilder for the given namespace prefix.

Parameters: prefix: str

Returns: MetricBuilder

exp.metrics("train").log(loss=0.5, accuracy=0.85)

metrics.log(**data)

Log a metric data point. When called on a prefixed builder, the prefix is applied. When called on the top-level metrics, supports grouped fields like train=dict(...), eval=dict(...).

Returns: MetricBuilder

exp.metrics("train").log(loss=0.5, accuracy=0.85)
exp.metrics.log(
    epoch=epoch,
    train=dict(loss=train_loss, accuracy=train_acc),
    eval=dict(loss=val_loss, accuracy=val_acc),
)

metrics("prefix").buffer(**data)

Buffer per-batch values in memory (not yet written). Use with log_summary() to aggregate.

Returns: None

for batch in dataloader:
    loss = train_step(batch)
    exp.metrics("train").buffer(loss=loss)

metrics.buffer.log_summary(*aggregations)

Compute and log summary statistics from buffered values.

Parameters: *aggregations: str — names of aggregations. Defaults to "mean". Supported: mean, std, min, max, count, percentile codes like p50, p90, p95, p99.

Returns: None

exp.metrics.buffer.log_summary()                          # mean only
exp.metrics.buffer.log_summary("mean", "std", "min", "max", "count")
exp.metrics.buffer.log_summary("p50", "p90", "p95", "p99")

metrics.flush()

Flush pending metric writes to disk/remote.

Returns: None

exp.metrics.log(epoch=epoch).flush()

metrics("prefix").read(start_index=0, limit=100)

Read logged data points for the given metric.

Parameters:

Returns: dict — {"data": [...], "startIndex", "endIndex", "total", "hasMore"}

data = exp.metrics("train_loss").read(start_index=0, limit=100)

metrics("prefix").stats()

Get summary statistics for a metric.

Returns: dict — {"count", "firstValue", "lastValue", ...}

stats = exp.metrics("train_loss").stats()

Method Summary

Files

Upload, download, and manage experiment files. Access via exp.files. See /files for patterns.

exp.files(**kwargs)

Create a FileBuilder.

Parameters:

builder = exp.files("models")
builder = exp.files(file_id="abc123")

save(local_path, **kwargs)

Upload a file from local disk.

Returns: dict

exp.files("models").save("./model.pt")
exp.files("models").save(
    "./model.pt",
    description="Best checkpoint",
    tags=["best"],
    metadata={"epoch": 50},
    bindrs=["v1", "production"],
)

save_json(content, to)

Serialize a Python object as JSON and upload.

Parameters:

Returns: dict

exp.files("configs").save_json({"lr": 0.001}, to="config.json")

save_torch(model, to)

Save a PyTorch model (or state dict) via torch.save.

Parameters:

Returns: dict

exp.files("models").save_torch(model, to="model.pt")
exp.files("models").save_torch(model.state_dict(), to="model.pth")

save_pkl(content, to)

Serialize a Python object via pickle and upload.

Parameters:

Returns: dict

exp.files("data").save_pkl({"results": [1, 2, 3]}, to="data.pkl")

save_fig(fig=None, to, **kwargs)

Save a matplotlib figure.

Parameters:

Returns: dict

exp.files("plots").save_fig(to="plot.png")
exp.files("plots").save_fig(fig=fig, to="plot.pdf", dpi=150, bbox_inches="tight")

save_video(frames, to, fps=20, **kwargs)

Encode a list/array of frames as MP4 or GIF.

Parameters:

Returns: dict

exp.files("videos").save_video(frames, to="output.mp4", fps=30)
exp.files("videos").save_video(frames, to="hq.mp4", codec="libx264", quality=8)

list()

List files for the current builder filters.

Returns: List[dict]

exp.files().list()                       # all files
exp.files("models").list()               # by prefix
exp.files(tags=["checkpoint"]).list()    # by tags

download(dest_path=None)

Download a file (requires file_id).

Parameters:

Returns: str — local path of the downloaded file

path = exp.files(file_id="123").download()
path = exp.files(file_id="123").download(dest_path="./model.pt")

update()

Update file metadata (requires file_id).

Returns: dict

exp.files(
    file_id="123",
    description="Updated",
    tags=["new"],
    metadata={"version": "2.0"},
).update()

delete()

Soft-delete a file (requires file_id).

Returns: dict

exp.files(file_id="123").delete()

Method Summary

Auto-Start

The ml_dash.auto_start module exposes dxp, a pre-configured, auto-started Experiment singleton for quick prototyping and notebooks.

from ml_dash.auto_start import dxp

Behavior

• Pre-configured: name "dxp", project "scratch", local storage at .dash
• Auto-started: ready to use on import; no .run.start() needed
• Auto-completed: closed on Python exit via atexit
• Full API: supports all Experiment methods

Fixed Configuration

Usage

from ml_dash.auto_start import dxp

dxp.params.set(lr=0.001, batch_size=32)
dxp.metrics("train").log(loss=0.5, step=0)
dxp.files("models").save("model.pt")
# Auto-completed on Python exit

Manual Lifecycle

The standard run methods still work:

dxp.run.complete()   # close manually
dxp.run.start()      # reopen
dxp.run.fail()       # mark failed

Regular Experiment vs. dxp