# Experiments

The `Experiment` class is the core abstraction in ML-Dash. A single instance owns one run's logs, parameters, metrics, and files.

## Prefix Format

The prefix is a universal key that identifies an experiment:

```
owner/project/path.../name
```

- **owner**: first segment (e.g. your username)
- **project**: second segment
- **path**: any number of intermediate segments forming a folder path
- **name**: last segment

Reopening the same prefix resumes that experiment (upsert semantics).

## Constructor

```python
Experiment(
    prefix: str | None = None,        # owner/project/.../name (or DASH_PREFIX env)
    *,
    readme: str | None = None,        # human-readable description
    tags: list[str] | None = None,    # categorization
    bindrs: list[str] | None = None,  # resource/team association
    metadata: dict | None = None,
    dash_url: str | bool | None = None,  # remote API URL (None = local-only)
    dash_root: str | None = ".dash",     # local storage root (None = remote-only)
    **run_params,                        # forwarded to the RUN namespace
)
```

Mode is inferred from `dash_url` / `dash_root`:

- `dash_root` only (default): local-only, writes to `.dash/`
- `dash_url` + `dash_root`: hybrid (local + remote)
- `dash_url`, `dash_root=None`: remote-only

The auth token is auto-loaded from `~/.dash/token.enc` when `dash_url` is set.

## The `.run` Lifecycle

Every `Experiment` exposes `.run`, a context manager that drives the lifecycle:

| Method | Status set | Notes |
|---|---|---|
| `exp.run.start()` | RUNNING | also performed by `__enter__` |
| `exp.run.complete()` | COMPLETED | called by `__exit__` on clean exit |
| `exp.run.fail()` | FAILED | called by `__exit__` if an exception propagates |
| `exp.run.cancel()` | CANCELLED | manual only |

Status updates require remote mode; local mode does not track status.

## Usage

Context manager (recommended):

```python
from ml_dash import Experiment

with Experiment(prefix="alice/project/my-experiment").run as exp:
    exp.log("Training started")
    exp.params.set(learning_rate=0.001)
    exp.metrics("train").log(loss=0.5, epoch=1)
    exp.files("models").save("model.pth")
```

For decorator-style usage (`@ml_dash_experiment(...)`) and the `RUN.entry = __file__` auto-prefix pattern, see [Getting Started](/getting-started.md). For full multi-step training scripts, see [Complete Examples](/complete-examples.md).

## What Lives Where

Once an experiment is open, feature-specific APIs are documented on their own pages:

- [Logging](/logging.md) — `exp.log(...)`
- [Parameters](/parameters.md) — `exp.params.set(...)`
- [Metrics](/metrics.md) — `exp.metrics(track).log(...)`
- [Files](/files.md) — `exp.files(prefix).save(...)`

---

**Next:** Learn about [Logging](/logging.md) to track events and progress.