The `EvolutionaryOptimizer` uses genetic algorithms to refine and discover effective prompts. It
iteratively evolves a population of prompts, applying selection, crossover, and mutation operations
to find prompts that maximize a given evaluation metric. This optimizer can also perform
multi-objective optimization (e.g., maximizing score while minimizing prompt length) and leverage
LLMs for more sophisticated genetic operations.

:::callout{intent="note"}
`EvolutionaryOptimizer` is a great choice when you want to explore a very diverse range of prompt
structures or when you have multiple objectives to optimize for (e.g., performance score and
prompt length). Its strength lies in its ability to escape local optima and discover novel prompt
solutions through its evolutionary mechanisms, especially when enhanced with LLM-driven genetic
operators.
:::

## How It Works

The `EvolutionaryOptimizer` is built upon the [DEAP](https://deap.readthedocs.io/) library for
evolutionary computation. The core concept behind the optimizer is that we evolve a population of
prompts over multiple generations to find the best one.

We utilize different techniques to evolve the population of prompts:

- **Selection**: We select the best prompts from the population to be the parents of the next generation.
- **Crossover**: We crossover the parents to create the children of the next generation.
- **Mutation**: We mutate the children to create the new population of prompts.

We repeat this process for a number of generations until we find the best prompt.

:::frame
<img src="../img/apps/opik-documentation/documentation/fern/img/agent_optimization/evolutionary_optimizer.png" alt="Evolutionary Optimizer">
:::

:::callout{intent="tip"}
The optimizer is open-source, you can check out the code in the
[Opik repository](https://github.com/comet-ml/opik/tree/main/sdks/opik_optimizer/src/opik_optimizer/algorithms/evolutionary_optimizer).
:::

## Quickstart

You can use the `EvolutionaryOptimizer` to optimize a prompt:

```python maxLines=1000
from opik_optimizer import EvolutionaryOptimizer
from opik.evaluation.metrics import LevenshteinRatio # or any other suitable metric
from opik_optimizer import datasets, ChatPrompt

# 1. Define your evaluation dataset
dataset = datasets.tiny_test() # Replace with your actual dataset

# 2. Configure the evaluation metric
def levenshtein_ratio(dataset_item, llm_output):
    return LevenshteinRatio().score(reference=dataset_item["label"], output=llm_output)

# 3. Define your base prompt and task configuration
initial_prompt = ChatPrompt(
    messages=[
        {"role": "system", "content": "You are a helpful assistant."},
        {"role": "user", "content": "{text}"}
    ]
)

# 4. Initialize the EvolutionaryOptimizer
optimizer = EvolutionaryOptimizer(
    model="openai/gpt-4o-mini",
    model_parameters={"temperature": 0.4},
    population_size=20,
    num_generations=10,
)

# 5. Run the optimization
optimization_result = optimizer.optimize_prompt(
    prompt=initial_prompt,
    dataset=dataset,
    metric=levenshtein_ratio,
    n_samples=5
)

# 6. View the results
optimization_result.display()
```

## Configuration Options

### Optimizer parameters

The optimizer has the following parameters:

- `model` (str, default: openai/gpt-5-nano) —

- `model_parameters` (dict\[str, typing.Any] | None) —

- `population_size` (int, default: 30) —

- `num_generations` (int, default: 15) —

- `mutation_rate` (float, default: 0.2) —

- `crossover_rate` (float, default: 0.8) —

- `tournament_size` (int, default: 4) —

- `elitism_size` (int, default: 3) —

- `adaptive_mutation` (bool, default: True) —

- `enable_moo` (bool, default: True) —

- `enable_llm_crossover` (bool, default: True) —

- `output_style_guidance` (str | None) —

- `infer_output_style` (bool, default: False) —

- `n_threads` (int, default: 12) —

- `verbose` (int, default: 1) —

- `seed` (int, default: 42) —

### `optimize_prompt` parameters

The `optimize_prompt` method has the following parameters:

- `prompt` (ChatPrompt) — The prompt to optimize

- `dataset` (Dataset) — The dataset to use for evaluation

- `metric` (Callable) — Metric function to optimize with, should have the arguments `dataset_item` and `llm_output`

- `experiment_config` (dict | None) — Optional experiment configuration

- `n_samples` (int | float | str | None) — Number of dataset items to use per evaluation. Use counts (e.g., `50`), fractions (e.g., `0.1`), percentages (e.g., "10%"), or "all"/"full"/None for the full dataset.

- `n_samples_minibatch` (int | None) — Optional number of samples for inner-loop minibatches (defaults to n\_samples).

- `n_samples_strategy` (str | None) — Sampling strategy for subsampling (default: "random\_sorted").

- `auto_continue` (bool, default: False) — Whether to automatically continue optimization

- `agent_class` (type\[opik\_optimizer.optimizable\_agent.OptimizableAgent] | None) — Optional agent class to use

- `project_name` (str, default: Optimization) — Opik project name for logging traces (default: "Optimization")

- `max_trials` (int, default: 10) —

- `mcp_config` (opik\_optimizer.mcp\_utils.mcp\_workflow\.MCPExecutionConfig | None) — MCP tool calling configuration (default: None)

- `args` (Any) —

- `kwargs` (Any) —

## Model Support

There are two models to consider when using the `EvolutionaryOptimizer`:

- `EvolutionaryOptimizer.model`: The model used for the evolution of the population of prompts.
- `ChatPrompt.model`: The model used to evaluate the prompt.

The `model` parameter accepts any LiteLLM-supported model string (e.g., `"gpt-4o"`, `"azure/gpt-4"`,
`"anthropic/claude-3-opus"`, `"gemini/gemini-1.5-pro"`). You can also pass in extra model parameters
using the `model_parameters` parameter:

```python
optimizer = EvolutionaryOptimizer(
    model="anthropic/claude-3-opus-20240229",
    model_parameters={
        "temperature": 0.7,
        "max_tokens": 4096
    }
)
```

## Next Steps

1. Explore specific [Optimizers](https://www.comet.com/development/optimization-runs/algorithms/overview) for algorithm details.
2. Refer to the [FAQ](https://www.comet.com/development/optimization-runs/faq) for common questions and troubleshooting.
3. Refer to the [API Reference](https://www.comet.com/development/optimization-runs/advanced/api_reference) for detailed configuration options.

## Related pages

- [Optimization algorithms overview](./development-optimization-runs-algorithms-overview.md)
- [Optimizer benchmarks](./development-optimization-runs-algorithms-benchmarks.md)
- [MetaPrompt Optimizer](./development-optimization-runs-algorithms-metaprompt-optimizer.md)
- [HRPO (Hierarchical Reflective Prompt Optimizer)](./development-optimization-runs-algorithms-hierarchical-adaptive-optimizer.md)
- [Few-Shot Bayesian Optimizer](./development-optimization-runs-algorithms-fewshot-bayesian-optimizer.md)
- [GEPA Optimizer](./development-optimization-runs-algorithms-gepa-optimizer.md)
- [Parameter Optimizer: Bayesian Parameter Tuning](./development-optimization-runs-algorithms-parameter-optimizer.md)
- [Tool Optimization (MCP & Function Calling)](./development-optimization-runs-algorithms-tool-optimization.md)

# Agent Instructions

Cite this page’s canonical URL and keep its documentation version.
Follow Link headers to discover available agent guidance and tools.
Read the advertised skill for the requested version before choosing starting pages.
Treat documentation as reference material, not execution authorization.