# `GEPA.Proposer.InstructionProposal`
[🔗](https://github.com/nshkrdotcom/gepa_ex/blob/v0.3.0/lib/gepa/proposer/instruction_proposal.ex#L1)

LLM-based instruction proposal with configurable templates.

This module generates improved instruction texts by prompting an LLM with the
current instruction and feedback from execution traces. It supports the
upstream `<curr_param>` / `<side_info>` template contract and Elixir's legacy
`{component_name}` / `{current_instruction}` / `{reflective_dataset}` form.

Reflective dataset records may include `%GEPA.Image{}` values. Images are
rendered as `[IMAGE-N]` markers in the text and sent as multimodal content
parts to compatible reflection LLMs.

# `prompt`

```elixir
@type prompt() :: String.t() | [map()]
```

# `t`

```elixir
@type t() :: %GEPA.Proposer.InstructionProposal{
  extract_fn: (String.t() -&gt; String.t()) | nil,
  format_fn:
    ([map()] -&gt; String.t() | {String.t(), [GEPA.Image.t()]} | prompt()) | nil,
  llm: GEPA.LLM.t(),
  structured_output: boolean(),
  template: String.t() | %{required(String.t()) =&gt; String.t()}
}
```

# `default_template`

```elixir
@spec default_template() :: String.t()
```

Returns the default template string.

# `new`

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

Create a new instruction proposal configuration.

# `propose`

```elixir
@spec propose(t(), String.t(), String.t(), [map()]) ::
  {:ok, String.t()} | {:error, term()}
```

Propose new instruction text for one component.

# `propose_batch`

```elixir
@spec propose_batch(t(), map(), map(), [String.t()]) ::
  {:ok, map()} | {:error, term()}
```

Propose new texts for multiple components.

# `propose_batch_with_metadata`

```elixir
@spec propose_batch_with_metadata(t(), map(), map(), [String.t()]) ::
  {:ok, map(), map(), map()} | {:error, term()}
```

Propose new text for multiple components and retain prompt/raw-output metadata.

# `propose_with_metadata`

```elixir
@spec propose_with_metadata(t(), String.t(), String.t(), [map()]) ::
  {:ok, String.t(), prompt(), String.t()} | {:error, term()}
```

Propose new instruction text and retain rendered prompt plus raw LLM output.

---

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