Skip to content

Candidate selector

candidate_selector

Protocol definition for candidate selection strategies.

ATTRIBUTE DESCRIPTION
CandidateSelectorProtocol

Async protocol for candidate selection strategies.

Examples:

Implement a simple random selector:

import random

from gepa_adk.ports.candidate_selector import CandidateSelectorProtocol
from gepa_adk.domain.state import ParetoState


class RandomSelector:
    async def select_candidate(self, state: ParetoState) -> int:
        frontier = state.pareto_frontier
        return random.choice(frontier) if frontier else 0


selector = RandomSelector()
assert isinstance(selector, CandidateSelectorProtocol)
See Also
  • ParetoState: Evolution state consumed by candidate selectors.

CandidateSelectorProtocol

Bases: Protocol


              flowchart TD
              gepa_adk.ports.candidate_selector.CandidateSelectorProtocol[CandidateSelectorProtocol]

              

              click gepa_adk.ports.candidate_selector.CandidateSelectorProtocol href "" "gepa_adk.ports.candidate_selector.CandidateSelectorProtocol"

Async protocol for candidate selection strategies.

Note

Adapters implementing this protocol provide strategies for selecting candidates from the Pareto frontier for mutation.

Examples:

class Selector:
    async def select_candidate(self, state: ParetoState) -> int:
        return 0
Source code in src/gepa_adk/ports/candidate_selector.py 
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
@runtime_checkable
class CandidateSelectorProtocol(Protocol):
    """Async protocol for candidate selection strategies.

    Note:
        Adapters implementing this protocol provide strategies for selecting
        candidates from the Pareto frontier for mutation.

    Examples:
        ```python
        class Selector:
            async def select_candidate(self, state: ParetoState) -> int:
                return 0
        ```
    """

    async def select_candidate(self, state: ParetoState) -> int:
        """Select a candidate index for mutation.

        Args:
            state: Current evolution state with Pareto frontier tracking.

        Returns:
            Index of selected candidate.

        Raises:
            NoCandidateAvailableError: If state has no candidates.

        Note:
            Outputs a candidate index from the frontier for mutation,
            enabling Pareto-aware selection strategies.

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

select_candidate async 

select_candidate(state: ParetoState) -> int

Select a candidate index for mutation.

PARAMETER DESCRIPTION
state

Current evolution state with Pareto frontier tracking.

TYPE: ParetoState

RETURNS DESCRIPTION
int

Index of selected candidate.
RAISES DESCRIPTION
NoCandidateAvailableError

If state has no candidates.
Note

Outputs a candidate index from the frontier for mutation, enabling Pareto-aware selection strategies.

Examples:

candidate_idx = await selector.select_candidate(state)
Source code in src/gepa_adk/ports/candidate_selector.py 
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
async def select_candidate(self, state: ParetoState) -> int:
    """Select a candidate index for mutation.

    Args:
        state: Current evolution state with Pareto frontier tracking.

    Returns:
        Index of selected candidate.

    Raises:
        NoCandidateAvailableError: If state has no candidates.

    Note:
        Outputs a candidate index from the frontier for mutation,
        enabling Pareto-aware selection strategies.

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