GEPA

Genetic Evolution of Prompt Architectures - evolutionary prompt optimization

GEPA: Genetic Evolution of Prompt Architectures

GEPA uses genetic algorithms with LLM-guided mutations to evolve prompt structures. It can outperform RL-based methods on prompt optimization tasks.

Paper: GEPA: Reflective Prompt Evolution Can Outperform Reinforcement Learning

When to Use

• Complex prompt structures
• Multi-component prompts (system + few-shot + chain-of-thought)
• Exploring diverse prompt mutations
• When you want interpretable prompt improvements

Config Reference

[prompt_learning]
algorithm = "gepa"
task_app_url = "https://your-tunnel.trycloudflare.com"
task_app_api_key = "$ENVIRONMENT_API_KEY"
task_app_id = "your-task"

[prompt_learning.initial_prompt]
id = "my_prompt"
name = "My Classification Prompt"

[[prompt_learning.initial_prompt.messages]]
role = "system"
pattern = "You are a classifier. {instructions}"
order = 0

[[prompt_learning.initial_prompt.messages]]
role = "user"
pattern = "{query}"
order = 1

[prompt_learning.policy]
model = "gpt-4o-mini"
provider = "openai"
temperature = 0.0
max_completion_tokens = 512

[prompt_learning.gepa]
env_name = "my-task"
proposer_type = "dspy"
proposer_effort = "LOW"
proposer_output_tokens = "FAST"

[prompt_learning.gepa.rollout]
budget = 100
max_concurrent = 20
minibatch_size = 8

[prompt_learning.gepa.evaluation]
seeds = [0, 1, 2, 3, 4, 5, 6, 7, 8, 9]
validation_seeds = [10, 11, 12, 13, 14]
validation_pool = "validation"
validation_top_k = 3

[prompt_learning.gepa.mutation]
rate = 0.3
llm_model = "gpt-oss-120b"
llm_provider = "groq"

[prompt_learning.gepa.population]
initial_size = 20
num_generations = 10
children_per_generation = 5
crossover_rate = 0.5
selection_pressure = 1.0
patience_generations = 3

[prompt_learning.gepa.archive]
size = 64
pareto_set_size = 64
pareto_eps = 1e-6
feedback_fraction = 0.5

[prompt_learning.gepa.token]
counting_model = "gpt-4"
enforce_pattern_limit = true

Top-Level Parameters

Parameter	Type	Default	Description
algorithm	string	-	Must be "gepa"
task_app_url	string	-	URL of your task app (tunnel URL)
task_app_api_key	string	-	Environment API key for auth
task_app_id	string	-	Identifier for your task

GEPA Section [prompt_learning.gepa]

Parameter	Type	Default	Description
env_name	string	"banking77"	Environment/task name
proposer_type	string	"dspy"	Proposer type: "dspy" or "spec"
proposer_effort	string	"LOW"	Model quality: "LOW_CONTEXT", "LOW", "MEDIUM", "HIGH"
proposer_output_tokens	string	"FAST"	Token limit: "RAPID" (3k), "FAST" (10k), "SLOW" (25k)
metaprompt	string	null	Custom metaprompt for mutations
rng_seed	int	null	Random seed for reproducibility

Rollout Config [prompt_learning.gepa.rollout]

Parameter	Type	Default	Description
budget	int	-	Total prompt evaluations allowed
max_concurrent	int	20	Max concurrent rollouts
minibatch_size	int	8	Batch size for evaluation

Evaluation Config [prompt_learning.gepa.evaluation]

Parameter	Type	Default	Description
seeds	list[int]	-	Training seeds (dataset indices)
validation_seeds	list[int]	-	Held-out validation seeds
test_pool	list[int]	null	Final test pool seeds
validation_pool	string	null	Pool name (e.g., "validation")
validation_top_k	int	null	Top-K prompts to validate

Mutation Config [prompt_learning.gepa.mutation]

Parameter	Type	Default	Description
rate	float	0.3	Probability of mutation per component
llm_model	string	null	Model for generating mutations
llm_provider	string	"groq"	Provider for mutation LLM
llm_inference_url	string	null	Custom inference URL
prompt	string	null	Custom mutation prompt

Population Config [prompt_learning.gepa.population]

Parameter	Type	Default	Description
initial_size	int	20	Initial population size
num_generations	int	10	Number of evolution generations
children_per_generation	int	5	Children generated per generation
crossover_rate	float	0.5	Probability of crossover
selection_pressure	float	1.0	Pareto selection pressure
patience_generations	int	3	Early stopping patience

Archive Config [prompt_learning.gepa.archive]

Parameter	Type	Default	Description
size	int	64	Archive size
pareto_set_size	int	64	Pareto set size
pareto_eps	float	1e-6	Pareto epsilon
feedback_fraction	float	0.5	Fraction of archive for feedback

Token Config [prompt_learning.gepa.token]

Parameter	Type	Default	Description
max_limit	int	null	Maximum tokens in prompt
counting_model	string	"gpt-4"	Model for token counting
enforce_pattern_limit	bool	true	Enforce token limits
max_spend_usd	float	null	Maximum spend in USD

Policy Config [prompt_learning.policy]

Parameter	Type	Default	Description
model	string	-	Model name (e.g., "gpt-4o-mini")
provider	string	-	Provider: "openai", "groq", "synth"
temperature	float	0.0	Sampling temperature
max_completion_tokens	int	512	Max output tokens
inference_mode	string	"synth_hosted"	Inference mode

Returns

from synth_ai.sdk.api.train.prompt_learning import PromptLearningJob

job = PromptLearningJob.from_config("gepa.toml")
job.submit()
result = job.poll_until_complete()

# Get results
results = job.get_results()
print(f"Best Score: {results['best_score']}")

# Get best prompt text
best_prompt = job.get_best_prompt_text(rank=1)
print(best_prompt)

Results Structure

{
    "best_prompt": {...},     # Full prompt with sections
    "best_score": 0.85,       # Accuracy on validation
    "top_prompts": [...],     # Top K prompts by score
    "optimized_candidates": [...],  # All evolved candidates
    "attempted_candidates": [...],  # All evaluated candidates
    "validation_results": {...},    # Per-seed validation scores
}

Download via CLI

# Download best prompt as JSON
uvx synth-ai artifacts download pl_71c12c4c7c474c34

# Download as YAML
uvx synth-ai artifacts download pl_71c12c4c7c474c34 --format yaml

# Save to file
uvx synth-ai artifacts download pl_71c12c4c7c474c34 --output prompt.json

Related

• MIPRO — Alternative prompt optimization method
• Artifacts CLI — Download prompts
• Prompt Optimization SDK — Job events reference