InstantMLDocs

Examples

Run bundled training examples against hosted InstantML and know what to inspect.

Open .md

Run the companion examples to exercise different training-loop shapes against hosted InstantML and confirm what lands in the dashboard.

Prerequisites

  • Authenticate once with the CLI:
bash
instantml login
  • For CI or remote jobs that cannot use browser login, set an SDK key instead:
bash
export INSTANTML_API_KEY="instantml_..."

The examples use the same public Python SDK calls that production training scripts use. When an example accepts --server, pass the hosted API URL.

Classify Iris species

Train a real-data NumPy softmax classifier on the UCI Iris dataset.

bash
PYTHONPATH=packages/python-sdk:examples/iris-classification \
  python3 examples/iris-classification/train.py \
  --server https://api.instantml.ai \
  --summary-json .instantml/iris-classification-summary.json

What to inspect:

  • Project iris-classification.
  • Metrics val/accuracy, test/accuracy, test/macro_f1, test/ece.
  • Config rows for seed, learning rate, and L2.
  • Uploaded artifacts: dataset profile, model JSON, predictions, confusion matrix.

Save and resume checkpoints

Run a tiny deterministic checkpoint workflow with upload and resume.

bash
PYTHONPATH=packages/python-sdk \
  python3 examples/checkpoints/train.py \
  --server https://api.instantml.ai \
  --api-key "$INSTANTML_API_KEY" \
  --steps 12 \
  --checkpoint-every 4

Open Run Detail and inspect checkpoint artifacts. The dashboard should expose download and resume-code actions.

Log RL-style metrics

Generate deterministic CartPole-style RL metrics without a simulator dependency.

bash
PYTHONPATH=packages/python-sdk:examples/rl-cartpole \
  python3 examples/rl-cartpole/train.py \
  --server https://api.instantml.ai

Use this example to test scalar logging, status transitions, and spool mode.

Train a Q-learning gridworld

Run a small tabular Q-learning loop with checkpoints and rollout metadata.

bash
PYTHONPATH=packages/python-sdk \
  python3 examples/q-learning-gridworld/train.py \
  --server https://api.instantml.ai

Compare train/episode_return, train/success_rate, train/td_error, and train/epsilon.

Run a contextual bandit

Exercise an online bandit workflow with multiple policies and seeds.

bash
PYTHONPATH=packages/python-sdk:examples/contextual-bandit \
  python3 examples/contextual-bandit/train.py \
  --server https://api.instantml.ai

Compare eval/return_mean, train/click_rate_50, train/cumulative_regret, eval/optimality_gap, and policy/arm_entropy.

Sweep a supervised regression

Run a synthetic tabular regression sweep across seeds.

bash
PYTHONPATH=packages/python-sdk:examples/supervised-regression \
  python3 examples/supervised-regression/train.py \
  --server https://api.instantml.ai \
  --seeds 11,29 \
  --epochs 30

Inspect train/validation loss, RMSE, MAE, R2, optimizer grad norm, and artifact metadata.

Seed Distributed and Insights

Generate distributed-rank and sweep-analysis data for the Distributed and Insights panels.

bash
PYTHONPATH=packages/python-sdk \
  python3 examples/rank-insights/train.py \
  --server https://api.instantml.ai

Open the dashboard, select the generated rank-insights project, and inspect Distributed and Insights for rank coverage, outliers, reducer differences, and clustered run groups.

Query runs from a script

Run the post-hoc SDK query workflow for notebooks and automation.

bash
PYTHONPATH=packages/python-sdk \
  python3 examples/query-api/query.py \
  --server https://api.instantml.ai

The script creates 20 short runs by default, then calls Api.query_runs(), Api.iter_runs(), Api.query_metrics(), Api.query_objects(run_id=...), and Api.object_rows() and prints a compact JSON summary. Use --skip-seed to query an existing query-api-demo project.

Verify the results

After running an example, confirm:

  • The project appears in the project selector.
  • Runs have expected tags, notes, and config values.
  • Metrics are chartable in Runs, Metrics, and Run Detail, and visible as sortable values in Compare.
  • Artifact metadata or uploaded bytes appear in Run Detail and Artifacts.
  • Failed scripts mark runs as failed instead of leaving them running.

Next steps