GEPA.EvaluationCache (GEPA v0.3.0)

Cache for validation evaluations keyed by candidate content and example id.

GEPA treats cached entries as opaque task outputs plus score metadata. A cache hit avoids re-running the adapter and contributes zero new metric calls.

Summary

Types

candidate()

data_id()

key()

t()

Functions

candidate_hash(candidate)

Deterministic hash for candidate maps.

get(evaluation_cache, candidate, example_id)

Fetch one cached evaluation.

get_batch(cache, candidate, example_ids)

Split ids into cached entries and uncached ids.

new()

Create an empty evaluation cache.

put(cache, candidate, example_id, output, score, objective_scores \\ nil)

Store one cached evaluation.

put_batch(cache, candidate, example_ids, outputs, scores, objective_scores_list \\ nil)

Store a batch of evaluation results.

Types

candidate()

@type candidate() :: %{required(String.t()) => String.t()}

data_id()

@type data_id() :: term()

key()

@type key() :: {String.t(), data_id()}

t()

@type t() :: %GEPA.EvaluationCache{
  entries: %{required(key()) => GEPA.EvaluationCache.Entry.t()}
}

Functions

candidate_hash(candidate)

@spec candidate_hash(candidate()) :: String.t()

Deterministic hash for candidate maps.

get(evaluation_cache, candidate, example_id)

@spec get(t(), candidate(), data_id()) ::
  {:ok, GEPA.EvaluationCache.Entry.t()} | :miss

Fetch one cached evaluation.

get_batch(cache, candidate, example_ids)

@spec get_batch(t(), candidate(), [data_id()]) ::
  {%{required(data_id()) => GEPA.EvaluationCache.Entry.t()}, [data_id()]}

Split ids into cached entries and uncached ids.

The uncached list preserves the caller's requested order.

new()

@spec new() :: t()

Create an empty evaluation cache.

put(cache, candidate, example_id, output, score, objective_scores \\ nil)

@spec put(
  t(),
  candidate(),
  data_id(),
  term(),
  float(),
  %{required(String.t()) => float()} | nil
) :: t()

Store one cached evaluation.

put_batch(cache, candidate, example_ids, outputs, scores, objective_scores_list \\ nil)

@spec put_batch(
  t(),
  candidate(),
  [data_id()],
  [term()],
  [float()],
  [%{required(String.t()) => float()}] | nil
) :: t()

Store a batch of evaluation results.