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

Typed internal predictors used by instruction, rule, and value optimizers.

Every proposal is an ordinary predictor call under the explicit `:proposal`
role, so it is rendered by that role's adapter, validated against a typed
output schema, and counted against the run's call limit. Proposed text is
trimmed, deduplicated, and bounded before use. Proposals see training
evidence only.

# `contrast`

```elixir
@spec contrast(
  Tune.Search.Program.Context.t(),
  String.t(),
  String.t(),
  String.t(),
  String.t()
) ::
  {String.t() | nil, Tune.Search.Program.Context.t()}
```

Compares good and bad trajectories and returns one rule or advice text.

# `describe`

```elixir
@spec describe(Tune.Predictor.t()) :: String.t()
```

Describes a predictor's task from its signature for proposal prompts.

# `evidence`

```elixir
@spec evidence([Tune.Case.t()], non_neg_integer()) :: String.t()
```

Renders up to `n` training examples as evidence text.

# `instructions`

```elixir
@spec instructions(Tune.Search.Program.Context.t(), Tune.Predictor.t(), keyword()) ::
  {[String.t()], Tune.Search.Program.Context.t()}
```

Proposes up to `n` instruction alternatives for one predictor.

# `lessons`

```elixir
@spec lessons(
  Tune.Search.Program.Context.t(),
  String.t(),
  [String.t()],
  String.t(),
  pos_integer()
) ::
  {[String.t()] | nil, Tune.Search.Program.Context.t()}
```

Proposes a new list of lessons from the current lessons and training feedback.

# `max_text`

```elixir
@spec max_text() :: pos_integer()
```

Returns the maximum accepted length of one proposed text.

# `reflect`

```elixir
@spec reflect(Tune.Search.Program.Context.t(), String.t(), String.t(), String.t()) ::
  {String.t() | nil, Tune.Search.Program.Context.t()}
```

Proposes a revised instruction from feedback on training trajectories.

# `rewrite`

```elixir
@spec rewrite(Tune.Search.Program.Context.t(), String.t(), String.t(), String.t()) ::
  {String.t() | nil, Tune.Search.Program.Context.t()}
```

Rewrites an instruction from feedback.

# `rules`

```elixir
@spec rules(Tune.Search.Program.Context.t(), String.t(), String.t(), pos_integer()) ::
  {[String.t()], Tune.Search.Program.Context.t()}
```

Derives up to `n` natural-language rules from successful examples.

# `value`

```elixir
@spec value(
  Tune.Search.Program.Context.t(),
  String.t(),
  String.t(),
  String.t(),
  String.t()
) ::
  {String.t() | nil, Tune.Search.Program.Context.t()}
```

Proposes a new JSON-encoded value for a declared parameter.

---

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