On this page
- Why Optimize?
- Quick Optimizer Comparison
- GEPA - Generative Evolutionary Prompt Adaptation
- Agent Optimization Workflows
- MIPRO - Multi-step Interactive Prompt Optimization
- SIMBA - Stochastic Introspective Mini-Batch Ascent
- BootstrapFewShot - Quick Example Selection
- COPRO - Collaborative Prompt Optimization
- Choosing the Right Optimizer
- Metrics - Measuring Success
- Best Practices
- CLI Tool - Zero Code Optimization
- What’s Next?
Optimizers
Optimizers
Optimizers are one of dspy-go’s most powerful features. Instead of manually tweaking prompts, optimizers automatically improve your signatures, instructions, and examples based on your dataset and metrics.
Why Optimize?
Manual prompt engineering is:
- Time-consuming: Hours of trial and error
- Subjective: What works for you might not work universally
- Brittle: Small changes can break everything
- Un-scalable: Hard to improve systematically
Optimizers solve this by:
- ✅ Automatically testing variations
- ✅ Using data to find what works
- ✅ Systematically improving performance
- ✅ Producing reproducible results
Quick Optimizer Comparison
| Optimizer | Best For | Speed | Quality | Complexity |
|---|---|---|---|---|
| BootstrapFewShot | Quick wins, simple tasks | ⚡⚡⚡ | ⭐⭐⭐ | Low |
| COPRO | Multi-module systems | ⚡⚡ | ⭐⭐⭐⭐ | Medium |
| MIPRO | Systematic optimization | ⚡⚡ | ⭐⭐⭐⭐ | Medium |
| SIMBA | Introspective learning | ⚡ | ⭐⭐⭐⭐⭐ | High |
| GEPA | Reflective prompt evolution | ⚡ | ⭐⭐⭐⭐⭐ | High |
GEPA - Generative Evolutionary Prompt Adaptation
GEPA evolves prompts using execution feedback and the metric you supply. It starts from your seed program, retains parents, and adds only children that strictly improve the total score on the parent’s current minibatch.
What Makes GEPA Special?
- Fresh evidence: Epoch-shuffled training minibatches supply case-specific inputs, outputs, scores, feedback, and module traces.
- One proposal call: The reflection LM rewrites the selected parent’s instructions; failed, empty, or unchanged proposals are skipped, not replaced with random edits.
- Selective validation: Only the seed and accepted children receive full validation. Parents and children use the same minibatch for acceptance.
- Metric-driven Pareto selection: Per-example validation winners guide parent selection; final selection uses aggregate validation score.
- Bounded evaluation: The metric-call budget includes training and validation evaluations; cached cases do not consume it.
Metrics and diagnostics
The user metric determines acceptance and selection. MultiObjectiveFitness remains available to agent integrations for diagnostics, but its seven diagnostic dimensions do not drive GEPA’s prompt search.
When to Use GEPA
✅ Perfect for:
- Complex, multi-faceted problems
- When you need multiple solution strategies
- Production systems requiring robustness
- Trade-offs between speed and quality
❌ Avoid for:
- Simple, single-objective tasks
- Very tight time constraints
- Limited compute resources
GEPA Example
package main
import (
"context"
"fmt"
"log"
"github.com/XiaoConstantine/dspy-go/pkg/core"
"github.com/XiaoConstantine/dspy-go/pkg/optimizers"
"github.com/XiaoConstantine/dspy-go/pkg/datasets"
"github.com/XiaoConstantine/dspy-go/pkg/llms"
)
func main() {
// 1. Configure LLM
llm, _ := llms.NewGeminiLLM("", core.ModelGoogleGeminiPro)
core.SetDefaultLLM(llm)
// 2. Create your program
program := createMyProgram() // Your application
// 3. Load dataset
examples, err := datasets.LoadGSM8K()
if err != nil {
log.Fatal(err)
}
training := make([]core.Example, len(examples))
for i, example := range examples {
training[i] = core.Example{
Inputs: map[string]any{"question": example.Question},
Outputs: map[string]any{"answer": example.Answer},
}
}
// 4. Define a scorer. GEPA calls it from several goroutines, so it must
// be safe for concurrent use; this one keeps no state.
scorer := core.ScorerFunc(func(ctx context.Context, example core.Example, prediction map[string]any) (float64, error) {
actual, ok := prediction["answer"].(string)
if !ok {
return 0, fmt.Errorf("prediction has no string answer")
}
if actual == example.Outputs["answer"] {
return 1, nil
}
return 0, nil
})
// 5. Configure GEPA
config := optimizers.DefaultGEPAConfig()
config.MaxMetricCalls = 1000 // Includes seed and accepted-child validation.
config.MaxGenerations = 10 // Additional safety cap, including the seed.
config.MutationRate = 1.0 // Attempt a proposal each iteration (the default).
gepa, err := optimizers.NewGEPA(config)
if err != nil {
log.Fatal(err)
}
// 6. Optimize
ctx := context.Background()
optimizedProgram, err := gepa.CompileWithScorer(ctx, program, training, scorer)
if err != nil {
log.Fatal(err)
}
// 7. Access results
state := gepa.GetOptimizationState()
fmt.Printf("Best fitness: %.3f\n", state.BestFitness)
fmt.Printf("Generations: %d\n", state.CurrentGeneration)
// 8. Get Pareto archive (candidates covering different examples)
archive := state.GetParetoArchive()
fmt.Printf("Elite solutions: %d\n", len(archive))
// The archive uses per-example user-metric scores, not diagnostic objectives.
}GEPA Configuration Guide
config := optimizers.DefaultGEPAConfig()
config.MaxMetricCalls = 1000 // Primary evaluation budget; 0 disables.
config.MaxGenerations = 1000 // Safety cap for skipped/failed proposals; 0 disables.
config.EvaluationBatchSize = 5 // Epoch-shuffled training minibatch size.
config.ValidationSplit = 0.2 // Optional holdout; explicit ValidationExamples also supported.
config.SkipPerfectScore = true // Skip minibatches already solved by the parent.
config.PerfectScore = 1.0 // Set to the maximum of your metric, or disable skipping.
config.RandomSeed = 42 // Reproducible sampling.Use a budget large enough for full seed validation plus proposed-child evaluation. A complete evaluation must fit the remaining budget; GEPA never adds a partially validated candidate to the frontier. With no holdout or explicit validation examples, validation uses the full training set. Runtime depends on your model and dataset, not just the iteration cap. StagnationLimit defaults to 0 (disabled); at least one of the metric budget and generation cap must be enabled.
Migration: PopulationSize, ReflectionFreq, ValidationFrequency, CrossoverRate, ElitismRate, Temperature, MaxTokens, and SelfCritiqueTemp were removed from GEPAConfig, along with the unused PopulationInsights and IndividualReflectionInsights types. Remove those fields from configuration literals. Sampling settings belong on the supplied LMs; GEPA’s removed temperature/token fields never configured them. DefaultGEPAConfig now uses a 1000-call budget, a 1000-generation safety cap, and no stagnation limit.
Agent Optimization Workflows
GEPA is no longer just for prompt modules. Native, ReAct, and RLM-backed agents can now export a shared optimized-program envelope, save it, restore it, and replay it on held-out tasks.
Baseline -> Optimize -> Save -> Restore -> Replay
package main
import (
"context"
"time"
agentrlm "github.com/XiaoConstantine/dspy-go/pkg/agents/rlm"
"github.com/XiaoConstantine/dspy-go/pkg/agents/optimize"
"github.com/XiaoConstantine/dspy-go/pkg/modules/rlm"
)
func main() {
baseAgent := agentrlm.NewAgent(
"demo-rlm",
rlm.NewFromLLM(
llm,
rlm.WithMaxIterations(8),
rlm.WithContextPolicyPreset(rlm.ContextPolicyAdaptive),
),
)
workflow, err := optimize.RunGEPAWorkflow(ctx, baseAgent, optimize.GEPAWorkflowRequest{
Evaluator: evaluator,
TrainingExamples: trainExamples,
ValidationExamples: validationExamples,
ReplayExamples: heldOutExamples,
PassThreshold: 0.9,
ApplyBest: true,
ArtifactPath: "optimized_program.json",
Config: optimize.GEPAAdapterConfig{
MaxGenerations: 2,
MaxMetricCalls: 50,
ScoreThreshold: 0.95,
MaxRuntime: 2 * time.Minute,
AddFormatFailureAsFeedback: true,
PrimaryArtifact: optimize.ArtifactRLMIterationPrompt,
},
})
if err != nil {
panic(err)
}
restored, err := optimize.ReadOptimizedAgentProgram("optimized_program.json")
if err != nil {
panic(err)
}
replayAgent, _ := baseAgent.Clone()
_ = optimize.ApplyOptimizedAgentProgram(replayAgent, restored)
_ = workflow
}RunGEPAWorkflow gives you:
- a baseline harness run
- GEPA optimization over agent artifacts
- a persisted
optimized_program.jsonenvelope - a replay run on held-out examples
Named Targets And Stable IDs
Agents can expose stable target IDs instead of one opaque prompt blob. That means GEPA can optimize surfaces like:
root.rlm.iterationroot.rlm.max_iterationsroot.rlm.adaptive.confidence_thresholdroot.react.tool_policy
These target IDs are what get persisted into the optimized-program envelope.
Forward-Compatible Restore
ApplyOptimizedAgentProgram skips unknown target IDs instead of failing hard. That matters when you restore an older saved program onto a newer agent shape that dropped or renamed a target.
In practice:
- known target IDs are applied
- obsolete target IDs are ignored
- missing values do not wipe unrelated defaults
That makes saved optimized programs much safer to carry across agent revisions.
GEPA Adapter Controls
For agent workflows, the most useful GEPA controls are:
MaxMetricCallsScoreThresholdMaxRuntimeFeedbackEvaluatorAddFormatFailureAsFeedback
The examples/rlm_oolong_gepa directory shows the full persisted agent workflow in a live RLM setting.
MIPRO - Multi-step Interactive Prompt Optimization
Systematic optimization using TPE (Tree-structured Parzen Estimator) search. MIPRO is ideal for methodical, data-driven prompt improvement.
What Makes MIPRO Special?
- 🎯 TPE Search: Bayesian optimization for efficient exploration
- 📊 Systematic: Methodical testing of variations
- ⚡ Multiple Modes: Light, Medium, Heavy optimization
- 🔍 Interpretable: Clear insights into what works
When to Use MIPRO
✅ Perfect for:
- Systematic, reproducible optimization
- When you have a good dataset (50+ examples)
- Medium-complexity tasks
- Need explainable improvements
❌ Avoid for:
- Very simple tasks (Bootstrap is faster)
- Extremely complex multi-objective problems (use GEPA)
- Limited datasets (< 20 examples)
MIPRO Example
package main
import (
"context"
"github.com/XiaoConstantine/dspy-go/pkg/optimizers"
)
func main() {
// Configure LLM
llm, _ := llms.NewGeminiLLM("", core.ModelGoogleGeminiPro)
core.SetDefaultLLM(llm)
// Create MIPRO optimizer
mipro := optimizers.NewMIPRO(
nil, // the scorer is passed to CompileWithScorer
optimizers.WithMode(optimizers.LightMode), // Fast optimization
optimizers.WithNumTrials(10), // Number of trials
optimizers.WithTPEGamma(0.25), // Exploration parameter
optimizers.WithMinExamplesPerModule(5), // Min examples needed
)
// Optimize program
optimizedProgram, err := mipro.CompileWithScorer(ctx, program, examples, scorer)
if err != nil {
log.Fatal(err)
}
// Use optimized program
result, _ := optimizedProgram.Execute(ctx, inputs)
}MIPRO Modes
// Light Mode - Quick optimization (5-10 minutes)
// - Fewer trials
// - Faster convergence
// - Good for iteration
optimizers.WithMode(optimizers.LightMode)
// Medium Mode - Balanced (15-30 minutes)
// - Moderate trials
// - Better quality
// - Production-ready
optimizers.WithMode(optimizers.MediumMode)
// Heavy Mode - Thorough (30-60 minutes)
// - Many trials
// - Highest quality
// - Critical systems
optimizers.WithMode(optimizers.HeavyMode)SIMBA - Stochastic Introspective Mini-Batch Ascent
Introspective learning with self-analysis. SIMBA learns from its own optimization process.
What Makes SIMBA Special?
- 🧠 Introspection: Analyzes its own optimization progress
- 📦 Mini-Batch: Stochastic optimization for efficiency
- 📈 Adaptive: Adjusts strategy based on progress
- 💡 Insights: Provides detailed learning analysis
When to Use SIMBA
✅ Perfect for:
- Complex reasoning tasks
- When you want insights into the optimization process
- Iterative improvement workflows
- Research and experimentation
❌ Avoid for:
- Simple tasks
- Very limited compute
- Need for speed over quality
SIMBA Example
package main
import (
"context"
"fmt"
"github.com/XiaoConstantine/dspy-go/pkg/optimizers"
)
func main() {
// Create SIMBA optimizer
simba := optimizers.NewSIMBA(
optimizers.WithSIMBABatchSize(8), // Mini-batch size
optimizers.WithSIMBAMaxSteps(12), // Max optimization steps
optimizers.WithSIMBANumCandidates(6), // Candidates per iteration
optimizers.WithSamplingTemperature(0.2), // Exploration vs exploitation
)
// Optimize
optimizedProgram, err := simba.CompileWithScorer(ctx, program, examples, scorer)
if err != nil {
log.Fatal(err)
}
// Get introspective insights
state := simba.GetState()
fmt.Printf("Steps completed: %d\n", state.CurrentStep)
fmt.Printf("Best score: %.3f\n", state.BestScore)
// View detailed analysis
for i, insight := range state.IntrospectionLog {
fmt.Printf("Insight %d: %s\n", i+1, insight)
}
// Example insights SIMBA might provide:
// - "Longer instructions improved performance by 15%"
// - "Adding context examples reduced errors in edge cases"
// - "Temperature 0.7 balanced creativity and accuracy"
}BootstrapFewShot - Quick Example Selection
Fast and effective for most tasks. Automatically selects high-quality few-shot examples.
What Makes Bootstrap Special?
- ⚡ Fast: Quickest optimizer
- 🎯 Effective: Works well for most tasks
- 📚 Few-Shot Learning: Automatic example selection
- 🔄 Simple: Easy to use and understand
When to Use Bootstrap
✅ Perfect for:
- Getting started with optimization
- Simple to medium complexity tasks
- Quick iterations
- Proof of concepts
❌ Avoid for:
- Very complex multi-step reasoning
- Need for multi-objective optimization
- Research on optimization strategies
Bootstrap Example
package main
import (
"context"
"github.com/XiaoConstantine/dspy-go/pkg/optimizers"
)
func main() {
// Create Bootstrap optimizer that keeps up to 5 demonstrations
bootstrap := optimizers.NewBootstrapFewShot(nil, 5)
// A prediction becomes a demonstration when the scorer rates it above
// zero, or at least MetricThreshold when that is set.
optimizedProgram, err := bootstrap.CompileWithScorer(ctx, program, examples, scorer)
if err != nil {
log.Fatal(err)
}
// Use optimized program
result, _ := optimizedProgram.Execute(ctx, inputs)
}COPRO - Collaborative Prompt Optimization
Multi-module optimization for complex systems with multiple components.
When to Use COPRO
✅ Perfect for:
- Systems with multiple modules
- RAG pipelines
- Multi-step workflows
- Coordinated optimization
COPRO Example
package main
import (
"context"
"github.com/XiaoConstantine/dspy-go/pkg/optimizers"
)
func main() {
// Create COPRO optimizer
copro := optimizers.NewCOPRO(
nil, // the scorer is passed to CompileWithScorer
optimizers.WithBreadth(5),
optimizers.WithDepth(2),
)
// Optimize program (automatically handles multi-module systems)
optimizedProgram, err := copro.CompileWithScorer(ctx, program, examples, scorer)
if err != nil {
log.Fatal(err)
}
}Choosing the Right Optimizer
Decision Tree
Start here
↓
Is it a simple task? → YES → Use Bootstrap
↓ NO
Multiple modules? → YES → Use COPRO
↓ NO
Need multi-objective? → YES → Use GEPA
↓ NO
Want introspection? → YES → Use SIMBA
↓ NO
Use MIPRO (default choice)By Use Case
| Use Case | Recommended Optimizer |
|---|---|
| Getting Started | BootstrapFewShot |
| Simple Q&A | BootstrapFewShot |
| Math/Logic | MIPRO (Medium Mode) |
| RAG Pipelines | COPRO or MIPRO |
| Complex Reasoning | SIMBA or GEPA |
| Production Critical | GEPA (Deep optimization) |
| Research | SIMBA or GEPA |
| Multi-Module Systems | COPRO |
Metrics - Measuring Success
Every optimizer scores predictions with a core.Scorer, passed to
CompileWithScorer together with a []core.Example:
type Scorer interface {
Score(ctx context.Context, example Example, prediction map[string]any) (float64, error)
}Optimizers call the scorer from several goroutines, so it must be safe for concurrent use. Return an error when a prediction cannot be scored, for example when an LLM judge fails; do not return zero for it.
Custom Scorers
scorer := core.ScorerFunc(func(ctx context.Context, example core.Example, prediction map[string]any) (float64, error) {
expected, _ := example.Outputs["answer"].(string)
actual, ok := prediction["answer"].(string)
if !ok {
return 0, fmt.Errorf("prediction has no string answer")
}
if expected == actual {
return 1, nil
}
// Partial credit for close answers
return calculateSimilarity(expected, actual), nil
})Built-in Metrics
pkg/metrics provides ExactMatch, AnyMatch, and F1Score. They compare
the example’s outputs with the prediction and keep no state, so convert them
with core.MetricScorer:
import "github.com/XiaoConstantine/dspy-go/pkg/metrics"
scorer := core.MetricScorer(metrics.ExactMatch)How Optimizers Treat a Scorer Error
| Optimizer | An example the scorer cannot score |
|---|---|
| GEPA | Counts as zero and is scored again the next time its candidate is evaluated |
| COPRO | Counts as zero |
| MIPRO | Counts as zero in a minibatch; a full evaluation returns the error |
| SIMBA | The candidate is rejected |
| BootstrapFewShot | The prediction is not kept as a demonstration |
Legacy Metrics
Compile(ctx, program, dataset, metric) with a core.Metric still works.
GEPA and MIPRO call a legacy metric one call at a time, so it does not need to
be safe for concurrent use, and it cannot report an error or observe
cancellation. core.MetricScorer(metric) converts one for CompileWithScorer;
use it only for metrics that are safe for concurrent use.
Best Practices
Dataset Preparation
✅ DO:
- Use diverse, representative examples
- Include edge cases
- Aim for 50+ examples for MIPRO/SIMBA
- Balance positive and negative cases
❌ DON’T:
- Use only simple examples
- Ignore data quality
- Optimize on test set
- Mix different task types
Optimization Strategy
- Start Small: Use Bootstrap first
- Measure: Establish baseline performance
- Iterate: Try MIPRO for systematic improvement
- Specialize: Use SIMBA/GEPA for complex needs
- Validate: Test on held-out data
Avoiding Overfitting
- Use train/validation split
- Don’t over-optimize (stop when validation plateaus)
- Test on diverse examples
- Monitor generalization metrics
CLI Tool - Zero Code Optimization
Try all optimizers without writing code:
# Build CLI
cd cmd/dspy-cli && go build
# Try Bootstrap
./dspy-cli try bootstrap --dataset gsm8k --max-examples 10
# Try MIPRO
./dspy-cli try mipro --dataset gsm8k --verbose
# Try GEPA
./dspy-cli try gepa --dataset hotpotqa --max-examples 20
# Compare optimizers
./dspy-cli compare --dataset gsm8k --optimizers bootstrap,mipro,gepaWhat’s Next?
- Core Concepts - Understand what optimizers improve
- Examples - See optimizers in action
- Compatibility Testing - Verify optimizer behavior