# `Tune`
[🔗](https://github.com/mikehostetler/tune/blob/v0.5.0/lib/tune.ex#L1)

Lazy evaluation and search pipelines for Elixir values and LLM programs.

Start with `new/2`, add declarations, and end with `preview/2`, `evaluate/2`,
`tune/1`, or `compare/3`. Builder calls only return a new `%Tune{}` value.

# `t`

```elixir
@type t() :: %Tune{
  cancel: (-&gt; boolean()) | nil,
  data: map(),
  limits: map(),
  metadata: map(),
  models: map(),
  on_progress: (map() -&gt; term()) | nil,
  runner: function() | :replay | nil,
  scores: [map()],
  selector: term(),
  strategy: term(),
  target: term(),
  variations: map()
}
```

# `compare`

```elixir
@spec compare(t(), Tune.Result.t() | Tune.Artifact.t(), keyword()) ::
  {:ok, Tune.Comparison.t()} | {:error, Exception.t()}
```

Compares the original target and a search result or saved artifact on an explicit split.

For a saved artifact, Tune loads it into the original target before running the comparison.

# `data`

```elixir
@spec data(t(), keyword() | map()) :: t()
```

Adds named train, validation, or test data without consuming it.

# `dump`

```elixir
@spec dump(Tune.Result.t()) :: {:ok, Tune.Artifact.t()} | {:error, Exception.t()}
```

Builds a versioned artifact from a completed tuning result.

# `evaluate`

```elixir
@spec evaluate(t(), :train | :validation | :test) ::
  {:ok, Tune.Evaluation.t()} | {:error, Exception.t()}
```

Evaluates the pipeline target on test data, or on an explicit data role.

# `limit`

```elixir
@spec limit(t(), keyword() | map()) :: t()
```

Adds explicit work limits.

# `load`

```elixir
@spec load(Tune.Artifact.t(), term()) :: {:ok, term()} | {:error, Exception.t()}
```

Validates an artifact and applies it to fresh application code.

# `new`

```elixir
@spec new(term(), keyword()) :: t()
```

Creates a lazy Tune pipeline.

# `preview`

```elixir
@spec preview(t(), map() | {String.t(), map()}) ::
  {:ok, Tune.Prepared.t()} | {:error, Exception.t()}
```

Prepares one inspectable prompt without making a model call.

# `replay`

```elixir
@spec replay(Enumerable.t() | (-&gt; Enumerable.t()), keyword()) :: t()
```

Builds an evaluation study from saved rows with `input` and `output` fields.

Rows may also provide `id` and `expected`. Pass an Enumerable or a zero-arity
factory. Score saved output with a function that takes `(case, output)`.

# `score`

```elixir
@spec score(t(), atom(), function() | module() | struct(), keyword()) :: t()
```

Adds one uniquely named score.

A one-argument function receives the output. A two-argument function or
module receives `(case, output)`. Use `argument: :prediction` to give a
two-argument scorer the prediction instead. The prediction is `nil` if
the runner did not return one.

# `search`

```elixir
@spec search(t(), atom() | module(), keyword()) :: t()
```

Selects a search strategy without starting it.

# `select`

```elixir
@spec select(t(), atom() | keyword()) :: t()
```

Selects the score policy used to compare candidates.

# `tune`

```elixir
@spec tune(t()) :: {:ok, Tune.Result.t()} | {:error, Exception.t()}
```

Runs the selected search and returns one immutable result.

# `vary`

```elixir
@spec vary(t(), keyword() | map()) :: t()
```

Declares named values that a search strategy can change.

---

*Consult [api-reference.md](api-reference.md) for complete listing*
