mldash-sdk 0.7.2

Export trained ML models to ML-Dash

mldash

Export trained ML models from notebooks to ML-Dash.

Install

uv tool install mldash-sdk

Or with pipx:

pipx install mldash-sdk

Requires Python 3.8+.

Update

Use whichever installer you used:

uv tool upgrade mldash-sdk        # uv
pipx upgrade mldash-sdk           # pipx
pip install --upgrade mldash-sdk  # pip

After updating the CLI, restart the bridge: Ctrl-C the mldash connect terminal, then re-run mldash connect. The bridge auto-upgrades the kernel's mldash-sdk inside the managed venv (~/.mldash/venv/) on startup, so a single mldash connect after the CLI upgrade brings everything in sync.

Quick Start

import mldash

# One-time login (saved to ~/.config/mldash/credentials)
mldash.login()

# See your projects
mldash.list_projects()

# Set active project for this notebook (by name or ID)
mldash.init(project="Churn Analysis")

# Train your model
from sklearn.ensemble import RandomForestClassifier
model = RandomForestClassifier()
model.fit(X_train, y_train)

# Export — just model + name, everything else is resolved
mldash.export(model=model, name="Churn Predictor")

Authentication

mldash.login() — One-time setup

Run once per machine. You'll be prompted for your ML-Dash URL and API key:

>>> mldash.login()
ML-Dash URL: https://api.mldash.com
Get your API key from: https://www.mldash.com/developers/keys
API Key: ········
Authenticated with https://api.mldash.com
Credentials saved to ~/.config/mldash/credentials

Credentials are stored locally at ~/.config/mldash/credentials (chmod 600) and reused automatically.

You can also pass values directly (useful for CI or scripting):

mldash.login(url="https://api.mldash.com", api_key="mldash_xxx")

mldash.logout()

mldash.logout()  # removes stored credentials

mldash.whoami()

mldash.whoami()
# URL:     https://api.mldash.com
# API Key: mldash_abcde...
# Project: Churn Analysis (id=3)

Alternative auth methods

These work without calling login():

Environment variables:

export MLDASH_URL=https://api.mldash.com
export MLDASH_API_KEY=mldash_your_key_here

Google Colab Secrets:

Add MLDASH_URL and MLDASH_API_KEY to your Colab Secrets (key icon in sidebar).

Browsing

mldash.list_projects()

mldash.list_projects()
# ID     Name                           Models   Datasets
# ----------------------------------------------------
# 1      Churn Analysis                 3        2
# 2      Imported Models                1        0

mldash.list_models()

mldash.list_models()                          # all models
mldash.list_models(project="Churn Analysis")  # filter by project
mldash.list_models(project=1)                 # filter by project ID

mldash.list_datasets()

mldash.list_datasets()                          # all datasets
mldash.list_datasets(project="Churn Analysis")  # filter by project

mldash.read_dataset() — Download as DataFrame

df = mldash.read_dataset(1)                    # by ID
df = mldash.read_dataset("my-dataset")         # by slug
df = mldash.read_dataset("alice/her-dataset")  # public dataset by username/slug
# Loaded dataset: 150 rows, 5 columns

Requires pandas (not included in SDK dependencies — install separately).

Project Association

mldash.init() — Set active project

Accepts a project name (string) or project ID (int):

mldash.init(project="Churn Analysis")   # by name
mldash.init(project=3)                  # by ID

# All exports now go to that project
mldash.export(model=model1, name="Logistic v1")
mldash.export(model=model2, name="XGBoost v1")

The project is saved to credentials, so it persists across sessions. Override per-export with the project= argument:

mldash.export(model=model, name="Experiment", project="Other Project")

If no project is set, exports go to an auto-created Imported Models project.

Usage

Export with artifacts

mldash.export(
    model=model,
    name="Sales Predictor",
    scaler=scaler,              # StandardScaler, MinMaxScaler, etc.
    encoder=encoder,            # OneHotEncoder, LabelEncoder, etc.
    label_map={"0": "no", "1": "yes"},
    features={"age": "numeric", "dept": "categorical", "review": "text"},
    target={"churn": "categorical"},
)

mldash.push() — Alias for export

mldash.push(model=model, name="My Model")  # same as export()

Save to local ZIP (offline)

mldash.save(
    model=model,
    name="My Model",
    path="./my_model.zip",
)
# Upload the ZIP manually via the ML-Dash web UI

Auto-detection

The package auto-detects:

• task_type — classification or regression (from sklearn mixins)
• framework — sklearn, xgboost, lightgbm, etc. (from module path)
• hyperparameters — via model.get_params()
• model_class — e.g., RandomForestClassifier
• n_features — from model.n_features_in_
• class_labels — from model.classes_

Typical Notebook Workflow

# Cell 1: Setup (run once)
import mldash
mldash.login()
mldash.init(project="MAS 648 Final")

# Cell 2-N: Train models...
model = RandomForestClassifier(n_estimators=100)
model.fit(X_train, y_train)

# Cell N+1: Export
mldash.export(model=model, name="RF 100 trees")

CLI

The SDK includes a command-line interface:

mldash login              # Authenticate (prompts for URL + API key)
mldash logout             # Remove stored credentials
mldash whoami             # Show current auth status
mldash connect            # Start local compute bridge for Studio
mldash setup              # Create managed Python venv (~/.mldash/venv/)
mldash install xgboost    # Install packages into managed venv
mldash uninstall          # Remove managed venv + credentials

mldash connect

Starts a local Python bridge so code written in ML-Dash Studio executes on your machine:

mldash connect                      # auto-select port
mldash connect --port 8765          # specific port
mldash connect --url http://...     # custom server URL

mldash setup

Creates a managed Python environment at ~/.mldash/venv/ with common ML packages (pandas, numpy, scikit-learn, matplotlib, seaborn, mldash-sdk). The bridge auto-uses this environment.

mldash setup              # create environment
mldash setup --force      # recreate from scratch

mldash uninstall

Removes the managed environment (~/.mldash/) and stored credentials (~/.config/mldash/credentials):

mldash uninstall                    # confirms before deleting
mldash uninstall --yes              # no prompts
mldash uninstall --keep-credentials # remove the venv but keep your login

To remove the CLI itself, run pipx uninstall mldash-sdk afterwards.

Errors

from mldash import MLDashValidationError, MLDashAuthError, MLDashUploadError

try:
    mldash.export(model=model, name="Test")
except MLDashValidationError as e:
    print(f"Invalid input: {e}")
except MLDashAuthError as e:
    print(f"Auth failed: {e}")
except MLDashUploadError as e:
    print(f"Upload failed: {e}")