Skip to content

Candidate selector

candidate_selector

Candidate selector adapter implementations.

Defines adapter implementations of CandidateSelectorProtocol for Pareto, greedy, and epsilon-greedy selection strategies.

ATTRIBUTE DESCRIPTION
ParetoCandidateSelector

Pareto frontier sampling selector.

TYPE: class

CurrentBestCandidateSelector

Greedy best-average selector.

TYPE: class

EpsilonGreedyCandidateSelector

Epsilon-greedy exploration selector.

TYPE: class

create_candidate_selector

Selector factory by name.

TYPE: function

Note

This module provides selector adapters for Pareto-aware evolution workflows.

ParetoCandidateSelector

Sample from the Pareto front proportional to leadership frequency.

ATTRIBUTE DESCRIPTION
_rng

RNG for sampling candidates.

TYPE: Random

Note

A Pareto selector emphasizes candidates that lead more examples.

Examples:

selector = ParetoCandidateSelector(rng=random.Random(42))
candidate_idx = await selector.select_candidate(state)
Source code in src/gepa_adk/adapters/candidate_selector.py 
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
class ParetoCandidateSelector:
    """Sample from the Pareto front proportional to leadership frequency.

    Attributes:
        _rng (random.Random): RNG for sampling candidates.

    Note:
        A Pareto selector emphasizes candidates that lead more examples.

    Examples:
        ```python
        selector = ParetoCandidateSelector(rng=random.Random(42))
        candidate_idx = await selector.select_candidate(state)
        ```
    """

    def __init__(self, rng: random.Random | None = None) -> None:
        """Initialize the selector.

        Args:
            rng: Optional random number generator for reproducibility.
        """
        self._rng = rng or random.Random()

    async def select_candidate(self, state: ParetoState) -> int:
        """Select a candidate index from the Pareto frontier.

        Args:
            state: Current evolution state with Pareto tracking.

        Returns:
            Selected candidate index.

        Raises:
            NoCandidateAvailableError: If no candidates or leaders exist.

        Examples:
            ```python
            candidate_idx = await selector.select_candidate(state)
            ```
        """
        if not state.candidates:
            raise NoCandidateAvailableError("No candidates available for selection")

        weights = state.frontier.get_selection_weights()
        if not weights:
            raise NoCandidateAvailableError("Pareto frontier is empty")

        sampling_list = [
            candidate_idx
            for candidate_idx, weight in weights.items()
            for _ in range(weight)
        ]
        if not sampling_list:
            raise NoCandidateAvailableError("Pareto frontier has no leaders")

        return self._rng.choice(sampling_list)

__init__ 

__init__(rng: Random | None = None) -> None

Initialize the selector.

PARAMETER DESCRIPTION
rng

Optional random number generator for reproducibility.

TYPE: Random | None DEFAULT: None

Source code in src/gepa_adk/adapters/candidate_selector.py 
41
42
43
44
45
46
47
def __init__(self, rng: random.Random | None = None) -> None:
    """Initialize the selector.

    Args:
        rng: Optional random number generator for reproducibility.
    """
    self._rng = rng or random.Random()

select_candidate async 

select_candidate(state: ParetoState) -> int

Select a candidate index from the Pareto frontier.

PARAMETER DESCRIPTION
state

Current evolution state with Pareto tracking.

TYPE: ParetoState

RETURNS DESCRIPTION
int

Selected candidate index.
RAISES DESCRIPTION
NoCandidateAvailableError

If no candidates or leaders exist.

Examples:

candidate_idx = await selector.select_candidate(state)
Source code in src/gepa_adk/adapters/candidate_selector.py 
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
async def select_candidate(self, state: ParetoState) -> int:
    """Select a candidate index from the Pareto frontier.

    Args:
        state: Current evolution state with Pareto tracking.

    Returns:
        Selected candidate index.

    Raises:
        NoCandidateAvailableError: If no candidates or leaders exist.

    Examples:
        ```python
        candidate_idx = await selector.select_candidate(state)
        ```
    """
    if not state.candidates:
        raise NoCandidateAvailableError("No candidates available for selection")

    weights = state.frontier.get_selection_weights()
    if not weights:
        raise NoCandidateAvailableError("Pareto frontier is empty")

    sampling_list = [
        candidate_idx
        for candidate_idx, weight in weights.items()
        for _ in range(weight)
    ]
    if not sampling_list:
        raise NoCandidateAvailableError("Pareto frontier has no leaders")

    return self._rng.choice(sampling_list)

CurrentBestCandidateSelector

Always select the candidate with the highest average score.

Note

A greedy selector always exploits the best-average candidate.

Examples:

selector = CurrentBestCandidateSelector()
candidate_idx = await selector.select_candidate(state)
Source code in src/gepa_adk/adapters/candidate_selector.py 
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
class CurrentBestCandidateSelector:
    """Always select the candidate with the highest average score.

    Note:
        A greedy selector always exploits the best-average candidate.

    Examples:
        ```python
        selector = CurrentBestCandidateSelector()
        candidate_idx = await selector.select_candidate(state)
        ```
    """

    async def select_candidate(self, state: ParetoState) -> int:
        """Return the best-average candidate index.

        Args:
            state: Current evolution state with Pareto tracking.

        Returns:
            Selected candidate index.

        Raises:
            NoCandidateAvailableError: If no candidates are available.

        Examples:
            ```python
            candidate_idx = await selector.select_candidate(state)
            ```
        """
        if state.best_average_idx is None:
            raise NoCandidateAvailableError("No candidates available for selection")
        return state.best_average_idx

select_candidate async 

select_candidate(state: ParetoState) -> int

Return the best-average candidate index.

PARAMETER DESCRIPTION
state

Current evolution state with Pareto tracking.

TYPE: ParetoState

RETURNS DESCRIPTION
int

Selected candidate index.
RAISES DESCRIPTION
NoCandidateAvailableError

If no candidates are available.

Examples:

candidate_idx = await selector.select_candidate(state)
Source code in src/gepa_adk/adapters/candidate_selector.py 
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
async def select_candidate(self, state: ParetoState) -> int:
    """Return the best-average candidate index.

    Args:
        state: Current evolution state with Pareto tracking.

    Returns:
        Selected candidate index.

    Raises:
        NoCandidateAvailableError: If no candidates are available.

    Examples:
        ```python
        candidate_idx = await selector.select_candidate(state)
        ```
    """
    if state.best_average_idx is None:
        raise NoCandidateAvailableError("No candidates available for selection")
    return state.best_average_idx

EpsilonGreedyCandidateSelector

Epsilon-greedy selection balancing exploration and exploitation.

ATTRIBUTE DESCRIPTION
_epsilon

Exploration probability.

TYPE: float

_rng

RNG for exploration decisions.

TYPE: Random

Note

A mixed strategy sometimes explores and otherwise exploits the best.

Examples:

selector = EpsilonGreedyCandidateSelector(epsilon=0.1, rng=random.Random(7))
candidate_idx = await selector.select_candidate(state)
Source code in src/gepa_adk/adapters/candidate_selector.py 
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
class EpsilonGreedyCandidateSelector:
    """Epsilon-greedy selection balancing exploration and exploitation.

    Attributes:
        _epsilon (float): Exploration probability.
        _rng (random.Random): RNG for exploration decisions.

    Note:
        A mixed strategy sometimes explores and otherwise exploits the best.

    Examples:
        ```python
        selector = EpsilonGreedyCandidateSelector(epsilon=0.1, rng=random.Random(7))
        candidate_idx = await selector.select_candidate(state)
        ```
    """

    def __init__(self, epsilon: float, rng: random.Random | None = None) -> None:
        """Initialize the selector.

        Args:
            epsilon: Probability of random exploration.
            rng: Optional random number generator for reproducibility.

        Raises:
            ConfigurationError: If epsilon is outside [0.0, 1.0].
        """
        if not 0.0 <= epsilon <= 1.0:
            raise ConfigurationError(
                "epsilon must be between 0.0 and 1.0",
                field="epsilon",
                value=epsilon,
                constraint="0.0 <= epsilon <= 1.0",
            )
        self._epsilon = epsilon
        self._rng = rng or random.Random()

    async def select_candidate(self, state: ParetoState) -> int:
        """Select a candidate using epsilon-greedy strategy.

        Args:
            state: Current evolution state with Pareto tracking.

        Returns:
            Selected candidate index.

        Raises:
            NoCandidateAvailableError: If no candidates are available.

        Examples:
            ```python
            candidate_idx = await selector.select_candidate(state)
            ```
        """
        if not state.candidates:
            raise NoCandidateAvailableError("No candidates available for selection")

        if self._rng.random() < self._epsilon:
            return self._rng.randint(0, len(state.candidates) - 1)

        if state.best_average_idx is None:
            raise NoCandidateAvailableError("No candidates available for selection")

        return state.best_average_idx

__init__ 

__init__(epsilon: float, rng: Random | None = None) -> None

Initialize the selector.

PARAMETER DESCRIPTION
epsilon

Probability of random exploration.

TYPE: float

rng

Optional random number generator for reproducibility.

TYPE: Random | None DEFAULT: None

RAISES DESCRIPTION
ConfigurationError

If epsilon is outside [0.0, 1.0].
Source code in src/gepa_adk/adapters/candidate_selector.py 
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
def __init__(self, epsilon: float, rng: random.Random | None = None) -> None:
    """Initialize the selector.

    Args:
        epsilon: Probability of random exploration.
        rng: Optional random number generator for reproducibility.

    Raises:
        ConfigurationError: If epsilon is outside [0.0, 1.0].
    """
    if not 0.0 <= epsilon <= 1.0:
        raise ConfigurationError(
            "epsilon must be between 0.0 and 1.0",
            field="epsilon",
            value=epsilon,
            constraint="0.0 <= epsilon <= 1.0",
        )
    self._epsilon = epsilon
    self._rng = rng or random.Random()

select_candidate async 

select_candidate(state: ParetoState) -> int

Select a candidate using epsilon-greedy strategy.

PARAMETER DESCRIPTION
state

Current evolution state with Pareto tracking.

TYPE: ParetoState

RETURNS DESCRIPTION
int

Selected candidate index.
RAISES DESCRIPTION
NoCandidateAvailableError

If no candidates are available.

Examples:

candidate_idx = await selector.select_candidate(state)
Source code in src/gepa_adk/adapters/candidate_selector.py 
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
async def select_candidate(self, state: ParetoState) -> int:
    """Select a candidate using epsilon-greedy strategy.

    Args:
        state: Current evolution state with Pareto tracking.

    Returns:
        Selected candidate index.

    Raises:
        NoCandidateAvailableError: If no candidates are available.

    Examples:
        ```python
        candidate_idx = await selector.select_candidate(state)
        ```
    """
    if not state.candidates:
        raise NoCandidateAvailableError("No candidates available for selection")

    if self._rng.random() < self._epsilon:
        return self._rng.randint(0, len(state.candidates) - 1)

    if state.best_average_idx is None:
        raise NoCandidateAvailableError("No candidates available for selection")

    return state.best_average_idx

create_candidate_selector 

create_candidate_selector(
    selector_type: str,
    *,
    epsilon: float = 0.1,
    rng: Random | None = None,
) -> CandidateSelectorProtocol

Create a candidate selector by name.

PARAMETER DESCRIPTION
selector_type

Selector identifier (pareto, greedy, epsilon_greedy).

TYPE: str

epsilon

Exploration rate for epsilon-greedy selector.

TYPE: float DEFAULT: 0.1

rng

Optional RNG for selectors using randomness.

TYPE: Random | None DEFAULT: None

RETURNS DESCRIPTION
CandidateSelectorProtocol

CandidateSelectorProtocol implementation.
RAISES DESCRIPTION
ConfigurationError

If selector_type is unsupported.

Examples:

selector = create_candidate_selector("pareto")
candidate_idx = await selector.select_candidate(state)
Source code in src/gepa_adk/adapters/candidate_selector.py 
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
def create_candidate_selector(
    selector_type: str,
    *,
    epsilon: float = 0.1,
    rng: random.Random | None = None,
) -> CandidateSelectorProtocol:
    """Create a candidate selector by name.

    Args:
        selector_type: Selector identifier (pareto, greedy, epsilon_greedy).
        epsilon: Exploration rate for epsilon-greedy selector.
        rng: Optional RNG for selectors using randomness.

    Returns:
        CandidateSelectorProtocol implementation.

    Raises:
        ConfigurationError: If selector_type is unsupported.

    Examples:
        ```python
        selector = create_candidate_selector("pareto")
        candidate_idx = await selector.select_candidate(state)
        ```
    """
    normalized = selector_type.strip().lower()
    if normalized in {"pareto"}:
        return ParetoCandidateSelector(rng=rng)
    if normalized in {"greedy", "current_best", "current-best"}:
        return CurrentBestCandidateSelector()
    if normalized in {"epsilon_greedy", "epsilon-greedy"}:
        return EpsilonGreedyCandidateSelector(epsilon=epsilon, rng=rng)
    raise ConfigurationError(
        "selector_type must be one of pareto, greedy, epsilon_greedy",
        field="selector_type",
        value=selector_type,
        constraint="pareto|greedy|epsilon_greedy",
    )