InstantMLDocs

Tables, histograms, evals, and media

Log rich objects for table previews, histogram timelines, typed evaluation bundles, and media evidence.

Open .md

Log rich objects when a run needs structured evidence — prediction tables, score distributions, evaluation bundles, and media — alongside its scalar metrics.

Use scalar metrics for one numeric value per step. Use rich objects when the dashboard needs more:

  • run.log_table_object(...) for prediction samples, eval rows, and compact per-example diagnostics in Run Detail.
  • run.log_objects({"key": im.Histogram.from_values(...)}) for score, confidence, activation, gradient, reward, weight, or latency distributions.
  • run.log_classification_eval(...) for binary PR/ROC curves, a confusion matrix, per-class metrics, and optional prediction rows.
  • im.Image, im.Video, and im.Audio for rollout evidence, generated examples, and audio samples.

For Runs workspace summary panels, keep logging scalar metrics with run.log_metrics(...). For selected-run histogram timelines, log histogram objects under the same key at multiple steps.

Log tables

Use tables for bounded previewable rows such as predictions, eval samples, or per-example metrics.

python
import instantml as im

run.log_table_object(
    "eval/predictions",
    ["id", "target", "prediction", "score"],
    [
        {"id": "ex-1", "target": "cat", "prediction": "cat", "score": 0.98},
        {"id": "ex-2", "target": "dog", "prediction": "cat", "score": 0.61},
    ],
    step=10,
)

The dashboard fetches table rows through a separate bounded endpoint, so large tables do not slow down the run page.

Log histograms

Use histograms for distributions such as logits, rewards, gradient norms, or latency samples.

python
confidence_bins = [index / 8 for index in range(9)]

run.log_objects(
    {
        "eval/confidence": im.Histogram.from_values(
            [0.91, 0.72, 0.88, 0.43],
            bins=confidence_bins,
        )
    },
    step=10,
)

Histograms appear as previews in Run Detail and artifact/object surfaces. They are rich evidence objects — a different surface from Runs workspace value-histogram panels, which aggregate scalar metric summaries across runs.

Runs workspace histogram timeline panels can also read a selected run's histogram objects by explicit key. When frames share bin edges, the panel shows a heatmap over steps. When bins differ, it shows a single selected frame instead, so non-comparable frames are not implied to be comparable.

Log classification evaluations

Use log_classification_eval(...) for compact binary classification eval bundles. The SDK stores typed rich-object data rather than screenshots, so Run Detail can render PR/ROC curves, a confusion matrix, per-class metrics, and an optional prediction preview.

python
run.log_classification_eval(
    "eval/classification",
    y_true=[0, 1, 1, 0],
    y_score=[0.1, 0.8, 0.7, 0.2],
    class_names=["negative", "positive"],
    positive_label="positive",
    split="validation",
    threshold=0.5,
    predictions=[{"id": "ex-1"}],
    step=10,
)

The current version is binary-only. y_score is the positive-class score, and y_pred is optional — it defaults to score >= threshold. Confusion matrix rows are true classes and columns are predicted classes, both in class_names order. Prediction rows are optional and capped at 100 preview rows.

Log media objects

Use media objects when the dashboard should treat a stored image, audio, or video as previewable run evidence. Passing a local media path uploads the file bytes and creates the linked rich object for the same run.

python
run.log_objects(
    {
        "eval/confusion_matrix": im.Image(
            path="outputs/confusion-matrix.png",
            caption="Validation confusion matrix",
        )
    },
    step=10,
)

For videos and audio, log the rich object directly when you want Run Detail and artifact surfaces to render a preview:

python
run.log_objects(
    {"eval/rollout": im.Video(path="outputs/rollout.mp4", caption="Evaluation rollout")},
    step=100,
)

Use upload_file(...) separately only when you also want a standalone raw file artifact in addition to the rich media object.

Local image, audio, and video objects upload artifact bytes and then create the linked rich object, so the API key needs both artifacts:write and sdk:ingest. These helpers are not supported in upload_mode="spool" because the object link needs the artifact upload response; use upload_mode="sync" or the default async mode for those events.

External references such as object-store URIs remain metadata artifacts. They are useful for provenance, but they are not previewable unless bytes are stored through InstantML.

Log text

Use text values for short generated summaries, explanations, or compact debug output.

python
run.log_text({"notes/eval": "Policy stabilized after the reward schedule change."}, step=10)

Mix value types in one call

run.log(...) classifies values by type before sending requests:

python
run.log(
    {
        "train/loss": 0.12,
        "notes/eval": "policy stabilized",
    },
    step=2,
)

Mixed payloads are deterministic but not atomic across routes. Metrics are sent first, then text, then objects, then files — media values travel inside the object and file requests rather than as a separate batch. If a later request fails, earlier requests may already be stored.

Next steps