Train

Prompt learning jobs consume TOML configs that describe the algorithm, initial prompt template, training/validation seeds, and optimization parameters. The CLI converts this into a job payload and submits it to Synth.

For command-line options and examples, see Launch Training Jobs.

1. Create the config TOML

Create a TOML file that follows the schema documented in the Prompt Learning config reference.

Example: Banking77 GEPA Configuration

[prompt_learning]
algorithm = "gepa"
task_app_url = "http://127.0.0.1:8102"
task_app_id = "banking77"

# Training seeds (30 seeds from train pool)
evaluation_seeds = [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]

# Validation seeds (50 seeds from validation pool - not in training)
validation_seeds = [0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20, 21, 22, 23, 24, 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]

[prompt_learning.initial_prompt]
messages = [
  { role = "system", content = "You are a banking intent classification assistant." },
  { role = "user", pattern = "Customer Query: {query}\n\nClassify this query into one of 77 banking intents." }
]

[prompt_learning.gepa]
initial_population_size = 20    # Starting population of prompts
num_generations = 15            # Number of evolutionary cycles
mutation_rate = 0.3             # Probability of mutation
crossover_rate = 0.5            # Probability of crossover
rollout_budget = 1000           # Total rollouts across all generations
max_concurrent_rollouts = 20    # Parallel rollout limit
pareto_set_size = 20           # Size of Pareto front

2. Launch the job

uvx synth-ai train \
  --config configs/prompt_learning/banking77_gepa.toml \
  --backend http://localhost:8000 \
  --poll

Steps performed by the CLI:

1. Validate the TOML (PromptLearningConfig) and ensure algorithm is selected (gepa or mipro).
2. Verify the task app via health check using ENVIRONMENT_API_KEY.
3. Create and start the job; by default the CLI polls status until it reaches a terminal state.

Useful overrides:

• --backend – point at a dev backend.
• --idempotency – provide an Idempotency-Key header (safe retries).
• --no-poll / --poll-timeout / --poll-interval – control how the CLI waits for completion.

Reminder: the CLI auto-loads the .env from uvx synth-ai setup. Use --env-file when you need to override secrets (you can supply the flag multiple times to merge values).

Algorithm Selection

GEPA (Genetic Evolution for Prompt Optimization)

Best for: Classification tasks, multi-hop QA, instruction following

• Uses evolutionary operations (mutation, crossover, selection)
• Maintains a Pareto front balancing accuracy, token count, and task-specific metrics
• Typically achieves 60-75% → 85-90%+ accuracy over 15 generations

MIPROv2 (Multi-Objective Prompt Optimization)

Best for: Tasks requiring strict token budgets or specific output formats

• Focuses on efficient prompt discovery with constraint-aware optimization
• Optimizes for multiple objectives simultaneously

Key Parameters

Parameter	Description	Typical Range
initial_population_size	Starting number of prompt variants	10-50
num_generations	Evolutionary cycles to run	5-30
mutation_rate	Probability of mutating a prompt	0.1-0.5
crossover_rate	Probability of combining two prompts	0.3-0.7
rollout_budget	Total task evaluations allowed	200-2000
max_concurrent_rollouts	Parallel rollout limit	10-50

See Configuration Reference for complete parameter documentation.