GEPAState¶
gepa.core.state.GEPAState(seed_candidate: dict[str, str], base_evaluation: ValsetEvaluation[RolloutOutput, DataId], track_best_outputs: bool = False, frontier_type: FrontierType = 'instance', evaluation_cache: EvaluationCache[RolloutOutput, DataId] | None = None)
¶
Bases: Generic[RolloutOutput, DataId]
Internal persistent state of a GEPA optimization run.
Tracks all explored candidates, their per-example and per-objective scores,
Pareto frontiers, evaluation budget, and optional evaluation cache.
Saved/loaded automatically when EngineConfig.run_dir is set.
Users interact with this indirectly via :class:~gepa.core.result.GEPAResult
returned by :func:~gepa.optimize_anything.optimize_anything.
Source code in gepa/core/state.py
Attributes¶
pareto_front_cartesian: dict[tuple[DataId, str], float]
instance-attribute
¶
program_at_pareto_front_cartesian: dict[tuple[DataId, str], set[ProgramIdx]]
instance-attribute
¶
num_full_ds_evals: int
instance-attribute
¶
total_num_evals: int
instance-attribute
¶
best_outputs_valset: dict[DataId, list[tuple[ProgramIdx, RolloutOutput]]] | None
instance-attribute
¶
program_candidates: list[dict[str, str]] = [dict(seed_candidate)]
instance-attribute
¶
iteration_ids_by_candidate_idx: list[str] = [SEED_ITERATION_ID]
instance-attribute
¶
prog_candidate_val_subscores: list[dict[DataId, float]] = [dict(base_evaluation.scores_by_val_id)]
instance-attribute
¶
prog_candidate_objective_scores: list[ObjectiveScores] = [base_objective_aggregates]
instance-attribute
¶
parent_program_for_candidate: list[list[ProgramIdx | None]] = [[None]]
instance-attribute
¶
frontier_type: FrontierType = frontier_type
instance-attribute
¶
pareto_front_valset: dict[DataId, float] = dict(base_evaluation.scores_by_val_id)
instance-attribute
¶
program_at_pareto_front_valset: dict[DataId, set[ProgramIdx]] = {val_id: {0} for val_id in base_evaluation.scores_by_val_id.keys()}
instance-attribute
¶
objective_pareto_front: ObjectiveScores = dict(base_objective_aggregates)
instance-attribute
¶
program_at_pareto_front_objectives: dict[str, set[ProgramIdx]] = {objective: {0} for objective in base_objective_aggregates.keys()}
instance-attribute
¶
list_of_named_predictors: list[str] = list(seed_candidate.keys())
instance-attribute
¶
named_predictor_id_to_update_next_for_program_candidate: list[int] = [0]
instance-attribute
¶
i: int = -1
instance-attribute
¶
num_metric_calls_by_discovery: list[int] = [0]
instance-attribute
¶
full_program_trace: list[dict[str, Any]] = []
instance-attribute
¶
validation_schema_version: int = self._VALIDATION_SCHEMA_VERSION
instance-attribute
¶
evaluation_cache: EvaluationCache[RolloutOutput, DataId] | None = evaluation_cache
instance-attribute
¶
adapter_state: dict[str, Any] = {}
instance-attribute
¶
valset_evaluations: dict[DataId, list[ProgramIdx]]
property
¶
Valset examples by id and programs that have evaluated them. Keys include only validation ids that have been scored at least once.
program_full_scores_val_set: list[float]
property
¶
per_program_tracked_scores: list[float]
property
¶
Methods:¶
is_consistent() -> bool
¶
Source code in gepa/core/state.py
add_budget_hook(hook: Callable[[int, int], None]) -> None
¶
Register a callback to be called whenever total_num_evals changes.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
hook
|
Callable[[int, int], None]
|
A callable that receives (new_total, delta) when evals are incremented. |
required |
Source code in gepa/core/state.py
increment_evals(count: int) -> None
¶
Increment total_num_evals and notify all registered hooks.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
count
|
int
|
Number of evaluations to add. |
required |
Source code in gepa/core/state.py
save(run_dir: str | None, *, use_cloudpickle: bool = False, write_agent_state: bool = False) -> None
¶
Source code in gepa/core/state.py
iteration_id_for_candidate_idx(candidate_idx: int) -> str | None
¶
On-disk iteration id for the accepted candidate at candidate_idx.
O(1) lookup against :attr:iteration_ids_by_candidate_idx, which is
maintained in lockstep with :attr:program_candidates by
:meth:update_state_with_new_program. Returns None for
out-of-range indices.
Source code in gepa/core/state.py
current_iteration_id() -> str
¶
On-disk anchor (iterations/<id>/) for the iteration in flight.
The engine stamps a random iteration_id on every trace entry at
slot creation, so the most-recently-opened entry's id is the current
iteration's anchor. Callers that need a specific iteration's anchor
pass it explicitly; this is the fallback for the single-writer paths
(merge, seed-less proposals) that operate on the current slot.
Source code in gepa/core/state.py
load(run_dir: str) -> GEPAState[RolloutOutput, DataId]
staticmethod
¶
Source code in gepa/core/state.py
get_program_average_val_subset(program_idx: int) -> tuple[float, int]
¶
Source code in gepa/core/state.py
update_state_with_new_program(parent_program_idx: list[ProgramIdx], new_program: dict[str, str], valset_evaluation: ValsetEvaluation, run_dir: str | None, num_metric_calls_by_discovery_of_new_program: int, iteration_id: str | None = None) -> ProgramIdx
¶
Source code in gepa/core/state.py
971 972 973 974 975 976 977 978 979 980 981 982 983 984 985 986 987 988 989 990 991 992 993 994 995 996 997 998 999 1000 1001 1002 1003 1004 1005 1006 1007 1008 1009 1010 1011 1012 1013 1014 1015 1016 1017 1018 1019 1020 1021 1022 1023 1024 1025 1026 1027 1028 1029 1030 1031 1032 1033 1034 1035 1036 | |
get_pareto_front_mapping() -> dict[FrontierKey, set[ProgramIdx]]
¶
Return frontier key to best-program-indices mapping based on configured frontier_type.
cached_evaluate(candidate: dict[str, str], example_ids: list[DataId], fetcher: Callable[[list[DataId]], Any], evaluator: Callable[[Any, dict[str, str]], tuple[Any, list[float], Sequence[ObjectiveScores] | None]], *, split: str) -> tuple[list[float], int]
¶
Evaluate with optional caching. Returns (scores, num_actual_evals). split is required.
Source code in gepa/core/state.py
cached_evaluate_full(candidate: dict[str, str], example_ids: list[DataId], fetcher: Callable[[list[DataId]], Any], evaluator: Callable[[Any, dict[str, str]], tuple[Any, list[float], Sequence[ObjectiveScores] | None]], *, split: str) -> tuple[dict[DataId, RolloutOutput], dict[DataId, float], dict[DataId, ObjectiveScores] | None, int]
¶
Evaluate with optional caching, returning full results. split is required.