InstantMLDocs

SDK patterns by workflow

Copy-paste logging patterns for supervised learning, RL, distributed jobs, and checkpoints.

Open .md

Grab a copy-paste pattern for your workflow — each snippet keeps run data easy to search, compare, export, and replay.

Track a supervised run

Stable config keys plus train/... and val/... metric keys make runs comparable across seeds and variants.

python
import math
import random

import instantml as im

run = im.init(
    project="iris-classification",
    name="softmax-baseline-seed-7",
    config={
        "dataset": "UCI Iris",
        "model": "softmax-regression",
        "seed": 7,
        "learning_rate": 0.14,
        "l2": 0.0005,
        "epochs": 160,
    },
    tags=["example", "classification"],
    notes="Track validation accuracy, calibration, and class-level errors.",
)

for epoch in range(1, 161):
    run.log_metrics(
        {
            "train/loss": 2.0 * math.exp(-epoch / 40) + random.uniform(0.0, 0.05),
            "val/loss": 2.1 * math.exp(-epoch / 45) + random.uniform(0.0, 0.08),
            "val/accuracy": 0.4 + 0.55 * (1 - math.exp(-epoch / 30)),
            "optimizer/grad_norm": random.uniform(0.5, 3.0),
        },
        step=epoch,
    )

run.upload_file("artifacts/model.json", artifact_type="checkpoint", step=160)
run.finish()

Compare by validation metrics first, then open Run Detail for config, artifacts, and source context.

Log chart-ready data

Put fields you want to group or plot against in config, and values you want to chart or sort in scalar metric keys.

python
import math
import random

import instantml as im

variant, seed = "wide", 7
confidence_bins = [index / 32 for index in range(33)]

run = im.init(
    project="ablation",
    name=f"{variant}-seed-{seed}",
    config={
        "variant": variant,
        "seed": seed,
        "learning_rate": 3e-4,
        "batch_size": 64,
        "model": "mlp-wide",
    },
    tags=[variant],
)

for epoch in range(1, 21):
    scores = [random.random() for _ in range(256)]
    run.log_metrics(
        {
            "train/loss": 1.5 * math.exp(-epoch / 6),
            "eval/accuracy": 0.5 + 0.45 * (1 - math.exp(-epoch / 8)),
            "eval/macro_f1": 0.45 + 0.45 * (1 - math.exp(-epoch / 9)),
            "system/throughput": random.uniform(900, 1100),
        },
        step=epoch,
    )
    run.log_objects(
        {"eval/confidence": im.Histogram.from_values(scores, bins=confidence_bins)},
        step=epoch,
    )

run.log_classification_eval(
    "eval/classification",
    y_true=[random.randint(0, 1) for _ in range(200)],
    y_score=[random.random() for _ in range(200)],
    class_names=["negative", "positive"],
    positive_label="positive",
    step=20,
)

run.finish()

This shape gives you:

  • Line charts for train/loss and eval/accuracy.
  • Bar, dot, and value histogram panels from latest scalar summaries.
  • Scatter panels such as config.learning_rate versus eval/accuracy best.
  • Distribution panels grouped by config.variant with config.seed as replicate metadata.
  • Logged histogram timelines for eval/confidence when frames share confidence_bins.
  • Classification eval previews in Run Detail without saving screenshots.

Track an RL or simulation job

Use eval/... keys for periodic policy evaluation and train/... keys for noisy online learning signals.

python
import math
import random

import instantml as im

run = im.init(
    project="cartpole",
    name="ppo-seed-42",
    config={"algorithm": "ppo", "seed": 42, "env": "CartPole-v1"},
    tags=["ppo", "baseline"],
)

for global_step in range(0, 100_000, 1_000):
    progress = global_step / 100_000
    run.log_metrics(
        {
            "train/episode_return": 500 * progress + random.uniform(-40, 40),
            "train/policy_loss": 0.8 * math.exp(-progress * 4),
            "eval/return_mean": 500 * progress,
            "eval/success_rate": min(1.0, progress * 1.2),
        },
        step=global_step,
    )

@run.trace_op(
    name="reward.score",
    kind="reward",
    capture="preview",
    attributes={"phase": "eval"},
)
def score_reward(observation, action, authorization):
    return {"reward": reward_model(observation, action)}

with run.trace("eval rollout", kind="rollout", step=100_000, capture="preview"):
    action = policy(observation)
    score_reward(observation, action, authorization="Bearer service-token")

run.log_video("eval-rollout.mp4", "s3://bucket/rollouts/eval-rollout.mp4", step=100_000)
run.finish()

Use eval/... keys for periodic policy evaluation and train/... keys for noisy online learning signals. Use traces sparingly for representative rollouts, failures, or reward/evaluator calls where you need execution evidence beside the metrics.

Spool long-running jobs

Spool mode keeps the training process from blocking on post-init HTTP calls.

python
import instantml as im

run = im.init(
    project="humanoid",
    upload_mode="spool",
    spool_dir=".instantml/spool",
)

Run a separate uploader process:

bash
python3 -m instantml.uploader \
  --spool-dir .instantml/spool \
  --base-url https://api.instantml.ai \
  --follow

Save and restore checkpoints

Use CheckpointPolicy(every_steps=N) to save on a fixed interval.

python
policy = im.CheckpointPolicy(every_steps=1000)

if policy.should_save(step):
    run.log_checkpoint_file(
        "checkpoints/policy.pt",
        step=step,
        metadata={"framework": "pytorch"},
    )

Run Detail shows checkpoint artifacts with download and resume snippets. Use Api.download_artifact(...) in automated restore scripts.

Mark failed runs

Use a context manager when a failing script should mark the run as failed:

python
with im.init(project="sweep", name="seed-7") as run:
    train(run)

Use explicit try/finally when a framework owns the training loop:

python
run = im.init(project="sweep", name="seed-7")
try:
    train(run)
    run.finish()
except Exception:
    run.finish("failed")
    raise

Next steps