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

OptimizerBest ForSpeedQualityComplexity
BootstrapFewShotQuick wins, simple tasks⚡⚡⚡⭐⭐⭐Low
COPROMulti-module systems⚡⚡⭐⭐⭐⭐Medium
MIPROSystematic optimization⚡⚡⭐⭐⭐⭐Medium
SIMBAIntrospective learning⚡⭐⭐⭐⭐⭐High
GEPAReflective 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.json envelope
  • 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.iteration
  • root.rlm.max_iterations
  • root.rlm.adaptive.confidence_threshold
  • root.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:

  • MaxMetricCalls
  • ScoreThreshold
  • MaxRuntime
  • FeedbackEvaluator
  • AddFormatFailureAsFeedback

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 CaseRecommended Optimizer
Getting StartedBootstrapFewShot
Simple Q&ABootstrapFewShot
Math/LogicMIPRO (Medium Mode)
RAG PipelinesCOPRO or MIPRO
Complex ReasoningSIMBA or GEPA
Production CriticalGEPA (Deep optimization)
ResearchSIMBA or GEPA
Multi-Module SystemsCOPRO

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

OptimizerAn example the scorer cannot score
GEPACounts as zero and is scored again the next time its candidate is evaluated
COPROCounts as zero
MIPROCounts as zero in a minibatch; a full evaluation returns the error
SIMBAThe candidate is rejected
BootstrapFewShotThe 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

  1. Start Small: Use Bootstrap first
  2. Measure: Establish baseline performance
  3. Iterate: Try MIPRO for systematic improvement
  4. Specialize: Use SIMBA/GEPA for complex needs
  5. 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,gepa

What’s Next?

Example Applications