Building Reflective Prompt Optimization with GEPA: Multi-Component Prompts, Structured Feedback, and Held-Out Validation - MarkTechPost

Home Artificial Intelligence Applications Building Reflective Prompt Optimization with GEPA: Multi-Component Prompts, Structured Feedback, and Held-Out...

Building Reflective Prompt Optimization with GEPA: Multi-Component Prompts, Structured Feedback, and Held-Out Validation

Sana Hassan

June 7, 2026

In this tutorial, we use GEPA as a reflective prompt-evolution framework to improve the way a language model solves arithmetic word problems. We begin with a weak seed prompt, create a small deterministic benchmark, define a structured evaluator, and pass actionable feedback to GEPA so it can understand why a candidate prompt fails. We also use a multi-component prompt setup in which both the instruction field and the output-format rules evolve together. By the end, we compare the baseline prompt with the optimized prompt on a held-out validation set and inspect how the evolutionary process improves performance.

Installing GEPA and LiteLLM and Configuring the Task and Reflection Models

Copy Code

!pip install -q gepa litellm
import os, re, json, random, getpass, textwrap
import litellm
import gepa.optimize_anything as oa
from gepa.optimize_anything import (
   optimize_anything, GEPAConfig, EngineConfig, ReflectionConfig,
)
litellm.suppress_debug_info = True
if not os.environ.get("OPENAI_API_KEY"):
   os.environ["OPENAI_API_KEY"] = getpass.getpass("Enter your OpenAI API key: ")
TASK_LM        = "openai/gpt-4o-mini"
REFLECTION_LM  = "openai/gpt-4.1"
MAX_METRIC_CALLS = 100

We install GEPA and LiteLLM, then import the required libraries for prompt optimization and model calls. We securely set up the OpenAI API key and define two models: a task model that solves the problem and a reflection model that improves the prompt. We also set the maximum metric-call budget to keep the optimization process under control.

Building a Deterministic Arithmetic Benchmark Dataset

Copy Code

def make_problems(n, seed=0):
   rng = random.Random(seed)
   out = []
   for _ in range(n):
       t = rng.choice(["discount", "travel", "wallet", "chain"])
       if t == "discount":
           unit  = rng.choice([40, 60, 80, 120])
           qty   = rng.choice([5, 6, 8, 10])
           disc  = rng.choice([10, 20, 25, 50])
           total = unit * qty
           gold  = total - total * disc // 100
           q = (f"A shop sells notebooks at {unit} rupees each. You buy {qty} "
                f"notebooks and get a {disc}% discount on the total bill. "
                f"How many rupees do you pay in total?")
       elif t == "travel":
           s1, h1 = rng.choice([40, 50, 60]), rng.choice([2, 3])
           s2, h2 = rng.choice([30, 45, 70]), rng.choice([1, 2, 3])
           gold = s1 * h1 + s2 * h2
           q = (f"A car drives at {s1} km/h for {h1} hours, then at {s2} km/h "
                f"for {h2} hours. What is the total distance travelled, in km?")
       elif t == "wallet":
           tens   = rng.choice([3, 5, 7, 9])
           fifties= rng.choice([2, 4, 6])
           spent  = rng.choice([50, 80, 110, 150])
           gold = tens * 10 + fifties * 50 - spent
           q = (f"You have {tens} ten-rupee notes and {fifties} fifty-rupee "
                f"notes. You spend {spent} rupees. How many rupees are left?")
       else:
           x = rng.choice([6, 9, 12, 15]); y = rng.choice([4, 7, 10]); z = rng.choice([3, 8, 11])
           gold = x * 2 - y + z
           q = (f"Start with the number {x}. Double it, then subtract {y}, "
                f"then add {z}. What number do you end with?")
       out.append({"question": q, "answer": gold})
   return out
all_problems = make_problems(18, seed=42)
random.Random(1).shuffle(all_problems)
trainset = all_problems[:12]
valset   = all_problems[12:]
print(f"Dataset: {len(trainset)} train / {len(valset)} val problems\n")

We create a small deterministic dataset of arithmetic word problems covering discounts, travel distance, wallet calculations, and chained operations. We generate the correct answer for each problem programmatically, which keeps the benchmark reliable and easy to evaluate. We then shuffle the examples and split them into a training set for optimization and a validation set for testing generalization.

Defining the Evaluator and Structured Feedback for GEPA

Copy Code

def build_system_prompt(candidate: dict) -> str:
   return (f"{candidate['instructions']}\n\n"
           f"OUTPUT FORMAT RULES:\n{candidate['format_rules']}")
def call_task_lm(system_prompt: str, question: str) -> str:
   for attempt in range(3):
       try:
           r = litellm.completion(
               model=TASK_LM,
               messages=[{"role": "system", "content": system_prompt},
                         {"role": "user",   "content": question}],
               temperature=0, max_tokens=600, timeout=60,
           )
           return r["choices"][0]["message"]["content"] or ""
       except Exception as e:
           if attempt == 2:
               return f"[LM_ERROR] {e}"
   return ""
def parse_answers(text: str):
   formatted = re.search(r"####\s*(-?\d+)", text)
   all_nums  = re.findall(r"-?\d+", text)
   fmt_val   = int(formatted.group(1)) if formatted else None
   last_val  = int(all_nums[-1]) if all_nums else None
   return fmt_val, last_val
def evaluate(candidate: dict, example: dict):
   system = build_system_prompt(candidate)
   raw    = call_task_lm(system, example["question"])
   gold   = example["answer"]
   fmt_val, last_val = parse_answers(raw)
   if fmt_val is not None and fmt_val == gold:
       score, fb = 1.0, "Correct and correctly formatted."
   elif fmt_val is not None and fmt_val != gold:
       score, fb = 0.0, (f"WRONG ANSWER. You output '#### {fmt_val}' but the "
                         f"correct answer is {gold}. Re-check the arithmetic and "
                         f"the order of the steps.")
   elif last_val == gold:
       score, fb = 0.5, (f"Right number ({gold}) but FORMAT VIOLATION: the final "
                         f"line was not exactly '#### {gold}'. Always end with a "
                         f"line of the form '#### <integer>' and nothing else.")
   else:
       score, fb = 0.0, (f"WRONG. Correct answer is {gold}. The model's final "
                         f"number was {last_val}. Likely a multi-step reasoning "
                         f"slip; show each step and verify before answering.")
   oa.log(f"score={score} gold={gold} parsed_fmt={fmt_val} parsed_last={last_val}")
   side_info = {
       "feedback": fb,
       "problem": example["question"],
       "gold_answer": gold,
       "model_output": raw[:500],
   }
   return score, side_info
def eval_set(candidate, dataset, label=""):
   scores, exact, formatted = [], 0, 0
   for ex in dataset:
       s, info = evaluate(candidate, ex)
       scores.append(s)
       if s == 1.0: exact += 1; formatted += 1
       elif s == 0.5: formatted += 0
   acc = exact / len(dataset)
   avg = sum(scores) / len(dataset)
   print(f"  [{label}] avg_score={avg:.3f}  exact_correct+formatted={exact}/{len(dataset)}")
   return avg, acc

We define how the candidate prompt is converted into a system prompt and how the task model receives each question. We also create the evaluator that parses the model output, checks whether the final answer follows the required #### <integer> format, and assigns a score. We return structured feedback as actionable side information so that GEPA can determine whether the issue is incorrect reasoning, poor formatting, or both.

Configuring GEPA and Running the Prompt Optimization

Copy Code

seed_candidate = {
   "instructions": "Solve the math problem.",
   "format_rules": "Give the answer.",
}
print("=== BASELINE (seed prompt) ===")
print("Train:"); base_train = eval_set(seed_candidate, trainset, "train")
print("Val:  "); base_val   = eval_set(seed_candidate, valset,   "val")
print()
objective = (
   "Evolve a system prompt (the 'instructions' and 'format_rules' fields) so a "
   "small LLM reliably solves multi-step arithmetic word problems AND always "
   "ends with a line of exactly the form '#### <integer>'. Maximize the score."
)
background = (
   "Scoring: 1.0 = correct number in the exact '#### <int>' format; 0.5 = correct "
   "number but wrong/missing format; 0.0 = wrong number. Common failures are (a) not "
   "emitting the '####' line, and (b) order-of-operations or multi-step slips. The "
   "winning prompt should force explicit step-by-step work, a verification step, and "
   "a strict final-answer line."
)
config = GEPAConfig(
   engine=EngineConfig(
       max_metric_calls=MAX_METRIC_CALLS,
       max_workers=4,
       parallel=True,
       display_progress_bar=True,
       seed=0,
   ),
   reflection=ReflectionConfig(
       reflection_lm=REFLECTION_LM,
   ),
)
print("=== RUNNING GEPA (this calls the LLMs; ~1-4 min) ===")
result = optimize_anything(
   seed_candidate=seed_candidate,
   evaluator=evaluate,
   dataset=trainset,
   valset=valset,
   objective=objective,
   background=background,
   config=config,
)

We start with a weak seed prompt and evaluate its baseline performance on both the training and validation sets. We then define the optimization objective, background scoring rules, and GEPA configuration, including parallel evaluation and the reflection model. Finally, we run optimize_anything so GEPA can evolve the instruction and format-rule fields using the evaluator feedback.

Comparing the Baseline and GEPA-Optimized Prompts on the Validation Set

Copy Code

best = result.best_candidate
print("\n" + "=" * 78)
print("OPTIMIZED CANDIDATE")
print("=" * 78)
print("\n--- instructions ---\n" + textwrap.fill(best["instructions"], 96))
print("\n--- format_rules ---\n" + textwrap.fill(best["format_rules"], 96))
print("\n" + "=" * 78)
print("BEFORE vs AFTER  (held-out validation set)")
print("=" * 78)
print("Seed prompt:"); _ = eval_set(seed_candidate, valset, "val-seed")
print("GEPA  prompt:"); _ = eval_set(best,          valset, "val-gepa")
print(f"\nBaseline val avg_score : {base_val[0]:.3f}")
print("\n" + "=" * 78)
print("EVOLUTION HISTORY (candidate index -> val score, parents)")
print("=" * 78)
cands   = getattr(result, "candidates", [])
vscores = getattr(result, "val_aggregate_scores", [])
parents = getattr(result, "parents", [None] * len(cands))
for i, sc in enumerate(vscores):
   par = parents[i] if i < len(parents) else None
   tag = "  <-- BEST" if cands and cands[i] == best else ""
   print(f"  cand {i:2d}: val_score={sc:.3f}  parents={par}{tag}")
print(f"\nTotal metric calls used : {getattr(result, 'total_metric_calls', 'n/a')}")
print(f"Full validation evals   : {getattr(result, 'num_full_val_evals', 'n/a')}")
print("\nDone. Try raising MAX_METRIC_CALLS or swapping REFLECTION_LM for a stronger model.")

We extract the best prompt found by GEPA and print its optimized instruction and format-rule components. We compare the seed prompt and the GEPA-optimized prompt on the held-out validation set to check whether the improvement transfers to unseen examples. We also inspect the evolution history, validation scores, parent relationships, and total metric calls to understand how the prompt improved over the course of optimization.

In conclusion, we used GEPA to show how prompt optimization can move beyond manual trial and error. We created a complete workflow where a task model solves examples, an evaluator scores the outputs, and a reflection model uses detailed feedback to propose better prompts. We also tested the optimized prompt on unseen validation problems, which helps us assess whether the improvement generalizes rather than merely fitting the training set. Also, we built a practical example of reflective prompt evolution in which structured feedback, strict evaluation, and iterative refinement work together to produce a stronger, more reliable prompt.

Check out the Full Codes with Notebook. Also, feel free to follow us on Twitter and don’t forget to join our 150k+ ML SubReddit and Subscribe to our Newsletter. Wait! are you on telegram? now you can join us on telegram as well.

Need to partner with us for promoting your GitHub Repo OR Hugging Face Page OR Product Release OR Webinar etc.? Connect with us

Sana Hassan

+ posts

Sana Hassan, a consulting intern at Marktechpost and dual-degree student at IIT Madras, is passionate about applying technology and AI to address real-world challenges. With a keen interest in solving practical problems, he brings a fresh perspective to the intersection of AI and real-life solutions.

Building Reflective Prompt Optimization with GEPA: Multi-Component Prompts, Structured Feedback, and Held-Out Validation

Installing GEPA and LiteLLM and Configuring the Task and Reflection Models

Building a Deterministic Arithmetic Benchmark Dataset

Defining the Evaluator and Structured Feedback for GEPA

Configuring GEPA and Running the Prompt Optimization

Comparing the Baseline and GEPA-Optimized Prompts on the Validation Set

Sana Hassan

Best 21 Low-Code and No-Code AI Tools in 2026

Meet Harness-1: A 20B Retrieval Subagent Trained With Reinforcement Learning Inside a Stateful Search...

NVIDIA garak Tutorial: Build a Complete Defensive LLM Red-Teaming Workflow with Custom Probes and...

Google’s New Colab CLI Lets Developers and AI Agents Run Python on Remote Colab...

Moonshot AI Releases Kimi Code CLI: A Terminal AI Coding Agent Built in TypeScript...

NVIDIA Releases Nemotron 3.5 ASR: A 600M-Parameter Cache-Aware Streaming Model Transcribing 40 Language-Locales in...

A Hands-On Coding Tutorial on Qualcomm AI Hub Models for Classification, Object Detection, and...

Google DeepMind Releases Gemma 4 QAT Checkpoints: Q4_0 and a New Mobile Format Cut...

NVIDIA AI Releases Dynamo Snapshot: A CRIU-Based Fast Startup System for AI Inference on...

Perplexity AI Introduces Hybrid Local-Server Inference Orchestrator for Personal Computer: Automatic On-Device and Cloud...

Ottimizzazione Prompt LLM: Guida Pratica con GEPA e Python