Instruction Optimization with dspy.GEPA

Guide the user through using dspy.GEPA to automatically discover better instructions for their DSPy programs through reflective evolution.

Step 1 — Gather context

Before generating code, ask (skip questions already clear from context):

1. Task type - Classification, generation, extraction, or multi-step pipeline? Multi-step pipelines can leverage per-predictor feedback via pred_name, which significantly improves optimization quality.
2. Data size - How many labeled examples are available? GEPA needs 20-100 examples. Fewer examples favor auto="light"; more favor auto="medium" or "heavy".
3. Failure mode - What does "wrong" output look like? GEPA's power comes from textual feedback — knowing the failure pattern lets you write a metric that explains errors to the reflection LM, not just scores them.
4. Budget - Rough API cost tolerance? auto="light" costs a few dollars; auto="heavy" can reach $20-50+ depending on validation set size and model choice. The reflection_lm model has the biggest cost impact.

What is dspy.GEPA

Experimental: dspy.GEPA is marked @experimental as of DSPy v3.0.0. The API may change in future releases. Included in pip install dspy via the gepa[dspy] package.

dspy.GEPA is a DSPy optimizer that evolves the instruction text in your program's predictors. Rather than adding few-shot examples (like BootstrapFewShot) or tuning model weights (like BootstrapFinetune), GEPA iteratively proposes, evaluates, and refines the natural-language instructions that guide each LM call.