Glossary¶

This glossary defines the canonical terminology used throughout the gepa-adk codebase. All docstrings, documentation, and code should adhere to these definitions.

Core Concepts¶

component

An evolvable unit with a name and text content. Components are the fundamental building blocks that the evolution engine optimizes.

Examples: instruction (the main agent prompt), output_schema (a structured output definition)

[1]

component_text

The current text content of a component being evolved. This is the value associated with a component name in a Candidate's components dictionary.

Type: str

[1]

evolved_components

A dictionary mapping component names to their optimized text values after evolution completes. For single-agent evolution, access via EvolutionResult.evolved_components["instruction"]. For multi-agent scenarios the keys are qualified agent.component names, one per evolved component.

Type: dict[str, str]

Stored in: EvolutionResult.evolved_components, MultiAgentEvolutionResult.evolved_components

Example: {"instruction": "Optimized prompt text..."} (single agent), {"generator.instruction": "...", "critic.output_schema": "..."} (multi-agent)

candidate

One set of component texts under evolution. A Candidate carries components (name to text), generation, parent_id (the candidate a mutation came from), parent_ids (the Pareto indices of a merge's two parents), metadata and a read-only id that hashes components. The engine seeds one from the agent, proposes new ones by mutation or merge, and returns the best-scoring one's texts as EvolutionResult.evolved_components.

Location: gepa_adk.domain.models.Candidate

[1]

critic

An ADK agent that scores another agent's output. CriticScorer wraps it as a Scorer: it runs the critic, reads its structured output (score between 0.0 and 1.0 plus optional feedback, dimension_scores and actionable_guidance) and returns the score with the other fields as metadata, which the trial builder normalizes into the trial's feedback.

Location: gepa_adk.adapters.scoring.critic_scorer.CriticScorer. See the Critic Agents guide.

Scorer

A protocol for scoring agent outputs. Implementations provide scoring logic that evaluates how well an agent's output matches expected results or quality criteria. Returns a score between 0.0 and 1.0 along with optional metadata.

Type: Protocol

Methods: score() (sync), async_score() (async)

Location: gepa_adk.ports.scorer

Trial Data Structures¶

trial

One performance record from evaluating a component_text against a test case. A trial contains two main parts: feedback and trajectory. The reflection agent receives the list of trials for one component as trials, JSON-serialized into session state.

Structure: {"feedback": {...}, "trajectory": {...}}

Collection type: list[dict[str, Any]]

[1] [2] [3] [4] [5]

feedback

Critic evaluation results for a single trial. Always contains score and feedback_text ("" when the scorer gave no text); dimensions and guidance appear when the critic returned dimension_scores and actionable_guidance, and any custom critic field passes through. The multi-agent adapter adds error when an execution failed; the single-agent adapter records that in trajectory.trace.error instead.

Properties: Stochastic - results may vary between evaluations due to LLM sampling.

Structure: {"score": 0.85, "feedback_text": "Good output", "dimensions": {...}, "guidance": "..."}

[1] [2] [3]

trajectory

Execution record capturing the journey from input to output. Contains the deterministic aspects of evaluation.

Properties: Deterministic - same input produces same trajectory structure.

Structure: {"input": "Hello", "output": "Hi there", "trace": {"tool_calls": 2, "tokens": 120, "error": "..."}}. trace is present only when the ADK trajectory recorded tool calls, token usage or an error, and carries only the keys that apply.

[1] [2] [3]

Evolution Process¶

evolution

The complete iterative optimization process that improves component_text over multiple generations. Evolution encompasses all operations including evaluation, selection, mutation, and merge.

Scope: High-level process and outcomes.

Usage: User-facing API (evolve(), run_sync(), evolve_group()), result types (EvolutionResult, EvolutionConfig), field prefixes (evolved_components).

[1]

mutation

A genetic operator that modifies a single candidate to produce an improved variant. In GEPA, mutation is implemented via LLM reflection that analyzes trials and proposes improved component_text.

Scope: Low-level operation (one of several genetic operators).

Contrast with: Evolution (the whole process), Merge (combines two candidates).

Usage: Proposer class (AsyncReflectiveMutationProposer), internal methods (_propose_mutation()), proposal tags (tag="mutation"), parameters (mutated).

[1]

merge

A genetic operator that combines two parent candidates to produce an offspring with characteristics from both. Complements mutation in the evolution process.

Scope: Low-level operation (genetic crossover).

Usage: Proposer class (MergeProposer), proposal tags (tag="merge"), candidate tracking (parent_ids: [idx1, idx2]).

reflection

The process of analyzing trials to propose improved component_text. The reflection agent, an LlmAgent that evolve() builds around EvolutionConfig.reflection_model unless reflection_agent= supplies one, examines feedback and trajectories to identify improvements.

Template Placeholders: {component_text} (current text being evolved), {trials} (JSON-serialized trial records).

[1]

minibatch

A fresh seeded sample of trainset rows that gates each mutation proposal before its full evaluation. The proposal is evaluated on the sampled rows and earns the full trainset pass only when its mean score beats the parent's cached scores on the same rows.

Usage: Config field (EvolutionConfig.reflection_minibatch_size), iteration records (skip_reason="minibatch_rejected", rows_evaluated holds the number of sampled rows).

[1]

proposal_validator

A caller-supplied check that sees each proposed component text before the engine validates or evaluates it. It returns None to accept the proposal or a short reason to reject it; a rejected proposal costs no evaluation and counts toward patience.

Usage: Config field (EvolutionConfig.proposal_validator), iteration records (skip_reason="proposal_rejected", rejection_reason).

token_rollup

A token rollup is the token usage summed over the rows an evolution run evaluated and the reflection calls it made, reported per iteration and for the whole run. Each counter sums the rows whose trajectory reported usage. A row with no usage is counted as unknown, never as zero, and a counter is unknown only when no row reported usage. The rollup carries an evaluation split and a reflection split, one row per reflection call; reflection is None when no reflection call was observed. The valset pass (no traces) is not observed.

Usage: Domain model (TokenRollup, TokenRollup.split()), iteration records (IterationRecord.token_usage), results (EvolutionResult.token_usage, MultiAgentEvolutionResult.token_usage); unknown counters serialize as "unknown".

checkpoint

A JSON file holding the engine's own state, written atomically after the baseline and after every recorded iteration. A run started with resume=True restores it instead of evaluating the baseline, continuing the iteration count, the stagnation counter and the evaluation counter without re-evaluating any candidate it already scored.

Usage: Config fields (EvolutionConfig.checkpoint_path, EvolutionConfig.resume), log event (checkpoint.resumed).

stop_reason

The StopReason value on a result that names why the run ended.

• COMPLETED: default; the run finished normally.
• MAX_ITERATIONS: the iteration cap was reached, including max_iterations=0.
• PATIENCE: early stopping fired after patience iterations without improvement.
• STOPPER_TRIGGERED: a stop callback returned True.
• KEYBOARD_INTERRUPT: a KeyboardInterrupt stopped the run after the baseline was scored.
• TIMEOUT: reserved for a time limit; not set by the engine yet.
• CANCELLED: asyncio cancellation stopped the run after the baseline was scored.
• ERROR: the run aborted after the baseline; set on EvolutionError.partial_result.

Usage: Result field (EvolutionResult.stop_reason, MultiAgentEvolutionResult.stop_reason), enum (gepa_adk.domain.types.StopReason).

[1]

proposed_component_text

The improved text generated by the reflection process. This becomes the new component_text if accepted by the evolution engine.

Type: str

acceptance_metric

How the engine aggregates a proposal's batch scores before deciding acceptance: "sum" (default, matches upstream GEPA) or "mean". A proposal is accepted when its aggregate exceeds the current best score by more than min_improvement_threshold.

Usage: Config fields (EvolutionConfig.acceptance_metric, EvolutionConfig.min_improvement_threshold), engine check (_should_accept).

[1]

pareto_frontier

The candidates that lead, or tie for the lead, on at least one tracked score (ParetoFrontier.get_non_dominated). A candidate that is merely not dominated, without leading anywhere, is tracked in ParetoState but is not on the frontier. The engine keeps a ParetoState only when evolve() receives a candidate_selector; parent choice then depends on the selector: ParetoCandidateSelector samples frontier members in proportion to how many scores they lead, while the current-best and epsilon-greedy selectors pick by average score, inside or outside the frontier. Without a selector every mutation starts from the current best candidate. EvolutionConfig.frontier_type picks which scores are tracked: INSTANCE (one per example, the default), OBJECTIVE, HYBRID or CARTESIAN.

Usage: evolve(candidate_selector=...), selectors in gepa_adk.adapters.selection.candidate_selector, EvolutionConfig.frontier_type.

[1]

stopper

A callable in EvolutionConfig.stop_callbacks that receives a StopperState (iteration, best_score, latest_score, stagnation_counter, total_evaluations, candidates_count, elapsed_seconds) before the first iteration and after each iteration, and returns True to end the run with StopReason.STOPPER_TRIGGERED.

Usage: Built-in stoppers in gepa_adk.adapters.stoppers; see the Stoppers guide.

[1]

ADK Integration Concepts¶

session_state

A dictionary that stores agent inputs and outputs during ADK execution. Session state enables data flow between the caller and agent via template substitution ({key} placeholders in instructions are replaced with session.state[key]).

Type: dict[str, Any]

Usage in GEPA: Reflection agents receive component_text and trials via session state. See Reflection Prompts Guide.

Example:

session_state = {
    "component_text": "Be helpful",
    "trials": json.dumps(trials),
}

output_key

An ADK agent property that enables automatic output storage to session state. When configured, the agent's final response is stored in session.state[output_key], allowing downstream code to retrieve output directly from state rather than parsing events.

Type: str | None

Usage in GEPA: Reflection agents use output_key="proposed_component_text". Multi-agent pipelines use output_key for inter-agent data flow.

Example:

from google.adk.models.lite_llm import LiteLlm

agent = LlmAgent(
    name="generator",
    model=LiteLlm(model="ollama_chat/llama3.2:latest"),
    instruction="Generate code",
    output_key="generated_code",  # Output stored in session.state["generated_code"]
)

Abbreviations¶

ADK

Agent Development Kit (Google)

[1] [2] [3] [4]

GEPA

Genetic-Pareto prompt optimizer. See the GEPA paper.

LLM

Large Language Model

[1]

Schema Evolution¶

schema_text

The Python source code representation of a Pydantic BaseModel class. Used as the component_text for output_schema evolution. Must be self-contained (no import statements allowed).

Type: str

Example:

schema_text = '''
class TaskOutput(BaseModel):
    result: str
    score: float = Field(ge=0.0, le=1.0)
'''

schema_validation

The process of verifying that schema_text is valid before acceptance into the evolution population. Validation includes syntax parsing (ast.parse), structure checks (BaseModel inheritance), and security rules (no imports or function definitions).

Stages: syntax → structure → execution

schema_namespace

A controlled dictionary of allowed names for schema execution. Includes Pydantic types (BaseModel, Field), built-in types (str, int, etc.), and typing module constructs (Optional, Union, etc.). Prevents arbitrary code execution by restricting available names.

Type: dict[str, Any]

Location: gepa_adk.utils.schema_utils.SCHEMA_NAMESPACE

SchemaValidationResult

The result of validating schema text, containing the deserialized class and metadata about the schema structure.

Attributes: - schema_class: The deserialized Pydantic BaseModel subclass - class_name: Name of the class found in the schema text - field_count: Number of fields defined - field_names: Tuple of field names

Location: gepa_adk.utils.schema_utils.SchemaValidationResult

Usage in Code¶

Docstring Terminology Section¶

Modules and classes should include a Terminology section when introducing or clarifying terms:

"""Module description.

Terminology:
    - **component**: An evolvable unit with a name and text (e.g., instruction)
    - **component_text**: The current text content of a component being evolved
    - **trial**: One performance record {feedback, trajectory}
    - **feedback**: Critic evaluation {score, feedback_text, feedback_*} (stochastic)
    - **trajectory**: Execution record {input, output, trace} (deterministic)
"""

Model Field Mapping¶

Terminology Scope¶

See Also¶

• ADR-010: Docstring Quality - Documentation standards
• Docstring Templates - Template reference