GEPA.CandidateProposal (GEPA v0.3.0)

A proposed new candidate program with metadata for acceptance testing.

A proposal contains the new candidate program along with information about its parents and subsample evaluation results that can be used to decide whether to accept the proposal.

Fields

candidate: The new program as a map of component name -> text
parent_program_ids: List of parent program indices (1 for mutation, 2+ for merge)
subsample_indices: Data IDs used for subsample evaluation
subsample_scores_before: Parent scores on subsample
subsample_scores_after: New candidate scores on subsample
eval_before: Rich parent minibatch evaluation data
eval_after: Rich proposed-candidate minibatch evaluation data
tag: Proposal type identifier ("reflective_mutation", "merge", etc.)
metadata: Additional proposal-specific data

Summary

Types

t()

Functions

should_accept?(proposal)

Check if proposal should be accepted.

should_accept?(proposal, criterion, state)

Check if proposal should be accepted using a configurable criterion.

Types

t()

@type t() :: %GEPA.CandidateProposal{
  candidate: GEPA.Types.candidate(),
  eval_after: GEPA.CandidateProposal.SubsampleEvaluation.t() | nil,
  eval_before: GEPA.CandidateProposal.SubsampleEvaluation.t() | nil,
  metadata: map(),
  parent_program_ids: [GEPA.Types.program_idx()],
  subsample_indices: [GEPA.Types.data_id()] | nil,
  subsample_scores_after: [float()] | nil,
  subsample_scores_before: [float()] | nil,
  tag: String.t()
}

Functions

should_accept?(proposal)

@spec should_accept?(t()) :: boolean()

Check if proposal should be accepted.

The default acceptance criterion is strict improvement: sum(new_scores) > sum(old_scores).

Examples

iex> proposal = %GEPA.CandidateProposal{
...>   candidate: %{},
...>   parent_program_ids: [0],
...>   tag: "test",
...>   subsample_scores_before: [0.5, 0.6],
...>   subsample_scores_after: [0.7, 0.8]
...> }
iex> GEPA.CandidateProposal.should_accept?(proposal)
true

iex> proposal = %GEPA.CandidateProposal{
...>   candidate: %{},
...>   parent_program_ids: [0],
...>   tag: "test",
...>   subsample_scores_before: [0.9],
...>   subsample_scores_after: [0.8]
...> }
iex> GEPA.CandidateProposal.should_accept?(proposal)
false

should_accept?(proposal, criterion, state)

@spec should_accept?(
  t(),
  GEPA.Strategies.Acceptance.criterion() | nil,
  GEPA.State.t() | nil
) ::
  boolean()

Check if proposal should be accepted using a configurable criterion.