Dsxir.Optimizer.GEPA.Operators behaviour (dsxir v0.2.0)

Behaviour and dispatcher for GEPA mutation operators.

Each operator returns {:ok, %Delta{}, proposer_calls} or {:error, exc}. sample/4 picks an operator by weighted draw against config.operator_weights and returns the parents the operator needs.

Summary

Types

ctx()

parents()

Callbacks

apply(parents, ctx)

kind()

parent_count()

Functions

sample(frontier, pop, weights, rng)

Weighted draw of an operator. Returns {operator_module, parents, rng2}. Population invariants make stale frontier references impossible by construction: the loop never removes ids.

Types

ctx()

@type ctx() :: %{
  reflective_lm: {module(), keyword()},
  demo_table: %{required(atom()) => %{required(map()) => [Dsxir.Demo.t()]}},
  decls: [Dsxir.Program.PredictorDecl.t()],
  rng: term(),
  config: map()
}

parents()

@type parents() ::
  Dsxir.Optimizer.GEPA.Individual.t()
  | {Dsxir.Optimizer.GEPA.Individual.t(), Dsxir.Optimizer.GEPA.Individual.t()}

Callbacks

apply(parents, ctx)

@callback apply(parents :: parents(), ctx :: ctx()) ::
  {:ok, Dsxir.Optimizer.GEPA.Delta.t(), proposer_calls :: non_neg_integer()}
  | {:error, Exception.t()}

kind()

@callback kind() :: :mutate_instr | :mutate_demos | :crossover

parent_count()

@callback parent_count() :: 1 | 2

Functions

sample(frontier, pop, weights, rng)

@spec sample(
  frontier :: [Dsxir.Optimizer.GEPA.Population.id()],
  pop :: Dsxir.Optimizer.GEPA.Population.t(),
  weights :: %{required(atom()) => float()},
  rng :: term()
) :: {module(), parents(), term()}

Weighted draw of an operator. Returns {operator_module, parents, rng2}. Population invariants make stale frontier references impossible by construction: the loop never removes ids.