# gizai:ml/experiment

Standalone classical ML model selection. Only the fit engine owns algorithms; this module owns validation, scoring and experiment ordering, never model copies.

```gizlang
import * as Experiment from "gizai:ml/experiment";
```

## Types

### `Candidate`

```gizlang
type Candidate = { algorithm: string; params: Json; }
```

One fully specified model and hyperparameter candidate.

- `algorithm`: `string`
- `params`: `gizlang_json.Json`

### `Trial`

```gizlang
type Trial = { algorithm: string; params: Json; score: f64; folds: Vec<f64>; }
```

The mean validation score and individual scores of a completed candidate.

- `algorithm`: `string`
- `params`: `gizlang_json.Json`
- `score`: `f64`
- `folds`: `Vec<f64>`

### `Study`

```gizlang
type Study = { champion: Model; trials: Vec<Trial>; metric: string; folds: i64; seed: u64; transform?: Prep.Standardizer; }
```

Leaderboard is sorted descending (best first); champion is refitted on all input rows.

- `champion`: `M42.Model`
- `trials`: `Vec<M38.Trial>`
- `metric`: `string`
- `folds`: `i64`
- `seed`: `u64`
- `transform`: `_gizlang_sdk_core.Option<M44.Standardizer>`

## Functions

### `score`

```gizlang
function score(task: string, metric: string, y: Vec<f64>, predicted: Vec<f64>): f64 throws string
```

Primary supervised metric: higher is better. Class labels need not be consecutive integers.

Effects: fail.

### `search`

```gizlang
function search(task: string, data: Data, candidates: Vec<Candidate>, folds: i64, seed: u64, metric: string = "", maxFits: i64 = 128, standardize: bool = false): Study throws string
```

Bounded, deterministic AutoML-style search over user-supplied candidates.
Each candidate gets identical shuffled folds; all scores are out-of-fold.
The winner is refit on all data only after selection. This is not nested CV.

Effects: fail.

### `leaderboard`

```gizlang
function leaderboard(trials: Vec<Trial>): Vec<Trial>
```

Higher validation scores win; exact ties preserve the supplied candidate order.

Effects: fail.

### `importance`

```gizlang
function importance(task: string, metric: string, model: Model, validation: Data, seed: u64): Vec<f64> throws string
```

Held-out permutation importance; each feature is shuffled independently once.
Positive values mean validation performance fell when that feature was corrupted.
Use more repetitions for statistically stable estimates.

Effects: fail.