# SDK patterns by workflow

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

- [Run the quickstart](/docs/quickstart.md)
- [Log metrics and steps](/docs/sdk/metrics-steps.md)
- [Log tables, histograms, and media](/docs/sdk/rich-objects.md)
- [Log rank-aware distributed metrics](/docs/sdk/distributed-training.md)
- [Buffering, offline mode, and reliability](/docs/sdk/reliability.md)

## Agent navigation

- [Docs index](/llms.txt)
- [Full docs bundle](/llms-full.txt)

### Get Started

- [Overview](/docs/index.md)
- [Quickstart](/docs/quickstart.md)
- [Core Concepts](/docs/concepts/core-concepts.md)
- [Pricing](/docs/pricing.md)
- [Benchmarks](/docs/benchmarks.md)
- [Examples](/docs/guides/examples.md)
- [Troubleshooting](/docs/troubleshooting.md)

### SDK

- [Installation Auth](/docs/sdk/installation-auth.md)
- [Logging](/docs/sdk/logging.md)
- [Tracing](/docs/sdk/tracing.md)
- [Metrics Steps](/docs/sdk/metrics-steps.md)
- [Config Tags Notes](/docs/sdk/config-tags-notes.md)
- [Artifacts Checkpoints](/docs/sdk/artifacts-checkpoints.md)
- [Rich Objects](/docs/sdk/rich-objects.md)
- [Distributed Training](/docs/sdk/distributed-training.md)
- [Console System Integrations](/docs/sdk/console-system-integrations.md)
- [Reliability](/docs/sdk/reliability.md)
- [Cli Login](/docs/sdk/cli-login.md)
- [Querying Data](/docs/sdk/querying-data.md)
- [Agent Mcp](/docs/sdk/agent-mcp.md)
- [Examples Patterns](/docs/sdk/examples-patterns.md) (current page)

### Integrations

- [Overview](/docs/integrations/overview.md)
- [Pytorch Lightning](/docs/integrations/pytorch-lightning.md)
- [Huggingface Transformers](/docs/integrations/huggingface-transformers.md)
- [Keras](/docs/integrations/keras.md)
- [Wandb](/docs/integrations/wandb.md)

### Dashboard

- [Tour](/docs/dashboard/tour.md)
- [Organizations Workspaces](/docs/dashboard/organizations-workspaces.md)
- [Runs Workspace](/docs/dashboard/runs-workspace.md)
- [Metrics Charts](/docs/dashboard/metrics-charts.md)
- [Run Detail](/docs/dashboard/run-detail.md)
- [Traces](/docs/dashboard/traces.md)
- [Compare Runs](/docs/dashboard/compare-runs.md)
- [Research Dashboards](/docs/dashboard/research-dashboards.md)
- [Artifacts Files](/docs/dashboard/artifacts-files.md)
- [Run Health](/docs/dashboard/alerts.md)
- [Datasets](/docs/dashboard/datasets.md)
- [Checkpoints](/docs/dashboard/checkpoints.md)
- [Reports](/docs/dashboard/reports.md)
- [Settings Api Keys](/docs/dashboard/settings-api-keys.md)
- [Api Tab](/docs/dashboard/api-tab.md)
- [Onboarding Team Billing](/docs/dashboard/onboarding-team-billing.md)

### Data

- [Imports](/docs/guides/imports.md)
- [W&B alternative](/docs/guides/wandb-alternative.md)
- [InstantML vs MLflow](/docs/guides/instantml-vs-mlflow.md)
- [W&B import guide](/docs/guides/wandb-import-guide.md)
- [W&B and Neptune imports](/docs/guides/wandb-neptune-imports.md)
- [Export Usage Limits](/docs/guides/export-usage-limits.md)
- [Pricing Limits Billing](/docs/guides/pricing-limits-billing.md)
- [Auth Billing Storage](/docs/guides/auth-billing-storage.md)
- [Customer Owned Clickhouse](/docs/guides/customer-owned-clickhouse.md)
- [Observability](/docs/guides/observability.md)

### API

**Practical API guides**

- [Authentication](/docs/api/authentication.md)
- [Errors And Limits](/docs/api/errors-and-limits.md)
- [Health Observability](/docs/api/health-observability.md)
- [Projects Runs](/docs/api/projects-runs.md)
- [Metrics Series](/docs/api/metrics-series.md)
- [Attributes Objects](/docs/api/attributes-objects.md)
- [Artifacts](/docs/api/artifacts.md)
- [Reports](/docs/api/reports.md)
- [Iframe Embeds](/docs/api/iframe-embeds.md)
- [Import Export Usage](/docs/api/import-export-usage.md)
- [Dashboard Control State](/docs/api/dashboard-control-state.md)
**Architecture**

- [System Overview](/docs/architecture/system-overview.md)
- [Service Planes](/docs/architecture/service-planes.md)
- [Storage Model](/docs/architecture/storage-model.md)
- [Google Clickhouse](/docs/architecture/google-clickhouse.md)
- [Auth Tenancy](/docs/architecture/auth-tenancy.md)
- [Schema Reference](/docs/architecture/schema-reference.md)

### API Reference

- [API Reference](/docs/api-reference.md)