# Core concepts

InstantML is built around a small set of training-loop concepts — once they
are clear, the SDK, API, and dashboard all feel predictable.

## How it works

Every InstantML integration follows the same five-step loop:

1. **Init** — `im.init(project=...)` creates a run inside a project.
2. **Config** — the `config` dict you pass to `init` records why this run
   differs from others.
3. **Log** — `run.log({"train/loss": 0.42}, step=step)` appends points to
   named metric series.
4. **Finish** — `run.finish()` marks the run complete.
5. **View** — open the dashboard to chart, search, and compare the run.

The rest of this page defines each noun in that loop, plus the surrounding
concepts: workspaces, artifacts, checkpoint forks, rich objects, reports, and
usage limits.

## Workspace

A workspace is the top-level boundary in InstantML. It owns members, roles,
billing, usage, API keys, reports, storage configuration, projects, and runs.
Switching workspaces changes the context for every dashboard page and API
route.

> **Info:** The API and billing surfaces call the same boundary an **organization** — org-scoped API keys, org IDs. The dashboard and these docs say workspace; API pages say organization where the API literally uses org.

## Project

A project groups related runs. Most teams use one project per model family,
benchmark, environment, or product workflow.

Examples:

- `cartpole`
- `mnist`
- `rank-scale-rl`
- `customer-support-finetune`

Projects cannot be renamed, so pick names you can live with.

Projects are also a useful API-key boundary. Project-scoped keys can restrict
SDK logging and reads to one project.

If you call `instantml.init()` without `project=`, the run lands in a shared
project named **`default`**. You can filter into it like any other project.

## Run

A run is one training, evaluation, sweep, import, or experiment execution.

Runs carry:

- Name and status.
- Start/end timing.
- Config values.
- Searchable tags and notes.
- Parent run and checkpoint fork context when the run was created from a
  checkpoint.
- Maintained metric summaries.
- Source metadata when the SDK can capture it.
- Artifacts, checkpoints, rich objects, logs, traces, and media.

If you call `instantml.init()` without `name=`, the server assigns a unique
name of the form `<adjective>-<noun>-<sequence>` — for example
`bold-falcon-1` or `serene-glacier-42` — where the sequence is the run's
1-indexed position in its project.

> **Note:** Run names are not editable. After creation you can update a run's status, tags, and notes, but not its name — pass a name at init time when the name matters.

## Metric

A metric is a named scalar time series logged at a numeric step.

Good metric keys are stable and namespaced:

| Pattern | Example |
| --- | --- |
| Training loss | `train/loss` |
| Evaluation score | `eval/accuracy` |
| Reward component | `reward/forward_velocity` |
| System signal | `system/gpu_utilization` |

Use consistent names across runs so the dashboard can compare them directly.

Scalar metrics become line charts in Metrics, Run Detail, and Runs workspace
line panels. Compare shows scalar metrics as sortable values and columns. The
Runs workspace can also summarize the runs you have loaded with latest-value
bar panels, value histogram panels, dot plots, scatter plots, and seed/group
distribution panels. Scatter panels combine any two numeric run fields —
metric aggregates, config values, metadata, duration, or created time.
Distribution panels group a numeric run field by a categorical config value,
metadata field, status, or first tag.

Choose the data shape before logging so each dashboard surface can stay fast
and readable:

| Data shape | Use for | Dashboard surfaces |
| --- | --- | --- |
| Scalar metric | One numeric value per step | Line, bar, dot, value histogram, scatter, and seed/group distribution panels |
| Numeric config | Settings that explain outcomes | Scatter panels, Compare columns, and Insights parallel coordinates |
| Categorical config or metadata | Labels and run attributes that explain groups | Distribution grouping, filters, and Compare matrix context |
| Rich histogram object | A distribution for one run at one step | Run Detail previews and selected-run logged-histogram timelines |
| Classification eval bundle | Binary classifier evaluation payloads | Run Detail PR/ROC, confusion matrix, per-class metrics, and optional prediction previews |

## Step

Step is the x-axis coordinate for metric series. Steps must be finite,
nonnegative numbers. The SDK warns when a lower step is logged for the same
metric after a higher step.

Typical step choices:

- Global optimizer step.
- Environment step.
- Epoch.
- Evaluation checkpoint number.

Pick one convention per project and keep it boring.

## Config

Config is run-level context that should explain why a run differs from others.

Good config fields include:

- `seed`
- `model`
- `dataset`
- `optimizer.lr`
- `batch_size`
- `algorithm`
- `checkpoint_source`

Configs appear in Run Detail, Compare, and search context.

## Tags and notes

Tags and notes are first-class run identity fields.

Use tags for compact labels:

```python
run.set_tags(["baseline", "ppo", "ready-for-compare"])
```

Use notes for human context:

```python
run.set_notes("Reward improved, but entropy dipped late.")
```

Both are searchable in the dashboard and visible in comparison workflows. Use
bare text for broad matching, `tag:baseline` for exact tag matching, and
`notes:"ready for compare"` when the note text should be the filter target.

## Artifact

Artifacts track files or external references associated with a run.

Use artifacts for:

- Model checkpoints.
- Prediction files.
- Confusion matrices.
- Eval reports.
- Rollout videos.
- Audio samples.
- Dataset profiles.

Stored artifact bytes are uploaded through the API and served back through a
same-origin download route. External references remain copyable metadata.

## Checkpoint fork

A checkpoint fork is a linked child run created from a source run and
checkpoint artifact. Forking records provenance only. It does not start
training, copy metrics, or copy artifacts. Attach the SDK to the child run when
you are ready to resume or retry training.

## Rich object

Rich objects are structured logged values for dashboard previews.

Current public object types include:

- Tables.
- Histograms.
- Binary classification evaluation bundles.
- Media objects linked to artifacts.

The dashboard fetches object manifests separately from run summaries so hidden
tabs do not load large object payloads by accident.

Rich-object histograms are previewed in Run Detail and artifact/object
surfaces. They are separate from Runs workspace value histogram panels, which
plot scalar metric summary values across the runs currently selected or loaded
in the workspace. Saved logged-histogram timeline panels can read one selected
run's histogram objects by explicit key. Classification evaluation bundles
render typed PR/ROC, confusion-matrix, per-class, and optional prediction
previews.

Keep arrays, tables, media, confusion matrices, and prediction examples as rich
objects. Scalar metrics should stay finite numeric values so summary panels and
comparisons do not need to fetch object payloads or full metric histories.

## Report

A report is a workspace-scoped writeup with block content, live dashboard
panels, share links, and Markdown export. Reports are for experiment decisions,
checkpoint reviews, and summaries that need narrative context beyond a saved
dashboard view.

## Usage and limits

Usage is scoped to the current workspace.

Important limit types:

- Metric points in the current UTC calendar month.
- Retained projects and runs.
- Retained storage.
- Seats.
- API keys.

When a blocking limit is reached, write endpoints return a plan-limit error
instead of silently accepting a partial write. See
[Pricing, limits, and billing](/docs/guides/pricing-limits-billing.md) for the exact
numbers per plan.

## Next steps

- [Quickstart](/docs/quickstart.md)
- [Log from Python](/docs/sdk/logging.md)
- [Runs workspace](/docs/dashboard/runs-workspace.md)
- [Compare runs](/docs/dashboard/compare-runs.md)
- [Pricing, limits, and billing](/docs/guides/pricing-limits-billing.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) (current page)
- [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)

### 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)