Skip to content

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, maps agent names to their evolved instruction text.

Type: dict[str, str]

Stored in: EvolutionResult.evolved_components, MultiAgentEvolutionResult.evolved_components

Example: {"instruction": "Optimized prompt text..."}

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.

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

[1] [2]

trials

A collection of trial records used for reflection. The reflection agent analyzes trials to propose improved component_text.

Type: list[dict[str, Any]] (JSON-serialized in session state)

[1] [2]

feedback

Critic evaluation results for a single trial. Contains the score and optional feedback text and dimensions.

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

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

[1]

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": [...]}

[1]

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(), evolve_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 (or LiteLLM model) examines feedback and trajectories to identify improvements.

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

[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

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_instruction" by default. Multi-agent pipelines use output_key for inter-agent data flow.

Example: 

agent = LlmAgent(
    name="generator",
    model="gemini-2.5-flash",
    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

Old Term (Deprecated) New Term
instruction (IterationRecord field) component_text
evolved_instruction evolved_components["instruction"]
evolved_component_text evolved_components["instruction"]
evolved_instructions evolved_components

Terminology Scope

Term Scope When to Use
evolve, evolution, evolved Process/outcome User-facing APIs, result types, field prefixes
mutate, mutation, mutated Operator/operation Proposer classes, internal methods, parameters
merge Operator/operation Crossover proposer, parent tracking
propose, proposed Reflection output Reflection agent output, pre-acceptance text

See Also