Optimization algorithms overview
The Opik Optimizer SDK wraps a mix of in-house algorithms (MetaPrompt, HRPO) and external research projects (e.g., GEPA). Each optimizer follows the same API (optimize_prompt, OptimizationResult) so you can swap them without rewriting your pipeline. Use this page to quickly decide which optimizer to run before diving into the detailed guides.
How optimizers run
Section titled “How optimizers run”- Input – you pass a
ChatPromptdefinition, dataset, and metric. Many optimizers also accept additional parameters to set which model to use, number of optimization rounds, and even tool use (MCP and function calling) definitions. - Candidate generation – each algorithm proposes new prompts (MetaPrompt via reasoning LLMs, Evolutionary via mutation/crossover, GEPA via its genetic-Pareto search).
- Evaluation – Opik runs the candidate against your dataset/metric and logs trials to the dashboard. The steps 2-to-3 continue to loop until such time a best prompt is found or the search has been exhausted.
- Result delivery – every optimizer returns an
OptimizationResultwith the best prompt, history, scores, and metadata which is passed back and also available in the UI.
Selection matrix
Section titled “Selection matrix”| Optimizer | Origin | Best for | Key inputs | Notes |
|---|---|---|---|---|
| MetaPrompt | Opik | General prompt refinement | Prompt + dataset + metric | Reasoning LLM critiques and rewrites prompts, supports MCP workflows and tool schemas. |
| HRPO | Opik | Root-cause analysis on complex prompts | Metrics with detailed reasons | Batches failures, synthesizes themes, proposes targeted fixes. |
| Few-Shot Bayesian | Opik | Optimizing few-shot example sets | Dataset with demonstrations | Uses Optuna to pick count/order of examples for chat prompts. |
| Evolutionary | Opik + DEAP | Exploring diverse prompt structures | Mutation/crossover params | Multi-objective optimization (score vs. length) and LLM-driven operators. |
| GEPA | External (GEPA) | Single-turn, reflection-heavy tasks | gepa dependency + reflection minibatches |
We provide a wrapper so GEPA consumes Opik datasets/metrics while preserving its Pareto search. |
| Parameter | Opik | Temperature / top_p tuning | Prompt + parameter search space | Leaves prompt untouched; focuses on sampling parameters via Bayesian search. |
How to choose
Section titled “How to choose”- Identify the constraint (e.g., wording vs. tool usage vs. parameters).
- Check dataset readiness – reflective optimizers need detailed metric reasons. Consider splitting your data into training and validation sets to prevent overfitting.
- Estimate budget – evolutionary/GEPA runs consume more tokens than MetaPrompt.
- Plan follow-up – you can chain optimizers (MetaPrompt → Parameter) when needed.
Next steps
Section titled “Next steps”- Follow the individual optimizer guides for configuration details.
- Learn how to chain optimizers for complex workflows.