opik-optimizer 1.0.6__py3-none-any.whl → 2.0.0__py3-none-any.whl

opik_optimizer/evolutionary_optimizer/evolutionary_optimizer.py

@@ -1,40 +1,47 @@
+import copy
 import json
 import logging
-import os
 import random
-from typing import Any, Callable, Dict, List, Optional, Set, Tuple, cast, Type
+from typing import Any, cast, TYPE_CHECKING
+from collections.abc import Callable
+import sys
+import warnings
 
 import rapidfuzz.distance.Indel
-import litellm
 import numpy as np
 import opik
 
 # DEAP imports
 from deap import base, tools
 from deap import creator as _creator
-from litellm import exceptions as litellm_exceptions
-from litellm.caching import Cache
-from litellm.types.caching import LiteLLMCacheType
-from opik.api_objects import opik_client, optimization
+from opik.api_objects import optimization
 from opik.environment import get_tqdm_for_current_environment
-from opik.evaluation.models.litellm import opik_monitor as opik_litellm_monitor
 
-from opik_optimizer import _throttle, task_evaluator
 from opik_optimizer.base_optimizer import BaseOptimizer, OptimizationRound
-from opik_optimizer.optimization_config import chat_prompt, mappers
+from opik_optimizer.optimization_config import chat_prompt
 from opik_optimizer.optimization_result import OptimizationResult
 from opik_optimizer.optimizable_agent import OptimizableAgent
+from opik_optimizer.mcp_utils.mcp_second_pass import MCPSecondPassCoordinator
+from opik_optimizer.mcp_utils.mcp_workflow import (
+    MCPExecutionConfig,
+    extract_tool_arguments,
+)
+from opik_optimizer.utils.prompt_segments import extract_prompt_segments
+
+from .mcp import EvolutionaryMCPContext, finalize_mcp_result
 
-from .. import utils
 from . import reporting
+from .llm_support import LlmSupport
+from .mutation_ops import MutationOps
+from .crossover_ops import CrossoverOps
+from .population_ops import PopulationOps
+from .evaluation_ops import EvaluationOps
+from .helpers import Helpers
+from .style_ops import StyleOps
+from . import prompts as evo_prompts
 
 logger = logging.getLogger(__name__)
 tqdm = get_tqdm_for_current_environment()
-_rate_limiter = _throttle.get_rate_limiter_for_current_opik_installation()
-
-# Using disk cache for LLM calls
-disk_cache_dir = os.path.expanduser("~/.litellm_cache")
-litellm.cache = Cache(type=LiteLLMCacheType.DISK, disk_cache_dir=disk_cache_dir)
 
 creator = cast(Any, _creator)  # type: ignore[assignment]
 
@@ -80,19 +87,14 @@ class EvolutionaryOptimizer(BaseOptimizer):
     )
     DEFAULT_MOO_WEIGHTS = (1.0, -1.0)  # (Maximize Score, Minimize Length)
 
-    _INFER_STYLE_SYSTEM_PROMPT = """You are an expert in linguistic analysis and prompt engineering. Your task is to analyze a few input-output examples from a dataset and provide a concise, actionable description of the desired output style. This description will be used to guide other LLMs in generating and refining prompts.
-
-Focus on characteristics like:
-- **Length**: (e.g., single word, short phrase, one sentence, multiple sentences, a paragraph)
-- **Tone**: (e.g., factual, formal, informal, conversational, academic)
-- **Structure**: (e.g., direct answer first, explanation then answer, list, yes/no then explanation)
-- **Content Details**: (e.g., includes only the answer, includes reasoning, provides examples, avoids pleasantries)
-- **Keywords/Phrasing**: Any recurring keywords or phrasing patterns in the outputs.
-
-Provide a single string that summarizes this style. This summary should be directly usable as an instruction for another LLM.
-For example: 'Outputs should be a single, concise proper noun.' OR 'Outputs should be a short paragraph explaining the reasoning, followed by a direct answer, avoiding conversational pleasantries.' OR 'Outputs are typically 1-2 sentences, providing a direct factual answer.'
-Return ONLY this descriptive string, with no preamble or extra formatting.
-"""
+    # Prompt constants moved into prompts.py
+    if TYPE_CHECKING:
+        _llm_deap_crossover: Any
+        _deap_crossover: Any
+        _deap_mutation: Any
+        _initialize_population: Any
+        _evaluate_prompt: Any
+        _infer_output_style_from_dataset: Any
 
     def __init__(
         self,
@@ -102,13 +104,13 @@ Return ONLY this descriptive string, with no preamble or extra formatting.
         mutation_rate: float = DEFAULT_MUTATION_RATE,
         crossover_rate: float = DEFAULT_CROSSOVER_RATE,
         tournament_size: int = DEFAULT_TOURNAMENT_SIZE,
-        num_threads: Optional[int] = None,
+        num_threads: int | None = None,
         elitism_size: int = DEFAULT_ELITISM_SIZE,
         adaptive_mutation: bool = DEFAULT_ADAPTIVE_MUTATION,
         enable_moo: bool = DEFAULT_ENABLE_MOO,
         enable_llm_crossover: bool = DEFAULT_ENABLE_LLM_CROSSOVER,
-        seed: Optional[int] = DEFAULT_SEED,
-        output_style_guidance: Optional[str] = None,
+        seed: int | None = DEFAULT_SEED,
+        output_style_guidance: str | None = None,
         infer_output_style: bool = False,
         verbose: int = 1,
         n_threads: int = DEFAULT_NUM_THREADS,
@@ -134,9 +136,18 @@ Return ONLY this descriptive string, with no preamble or extra formatting.
             **model_kwargs: Additional model parameters
         """
         # Initialize base class first
+        if sys.version_info >= (3, 13):
+            warnings.warn(
+                "Python 3.13 is not officially supported (python_requires <3.13). "
+                "You may see asyncio teardown warnings. Prefer Python 3.12.",
+                RuntimeWarning,
+            )
         if "project_name" in model_kwargs:
-            print(
-                "Removing `project_name` from constructor; it now belongs in the ChatPrompt()"
+            warnings.warn(
+                "The 'project_name' parameter in optimizer constructor is deprecated. "
+                "Set project_name in the ChatPrompt instead.",
+                DeprecationWarning,
+                stacklevel=2,
             )
             del model_kwargs["project_name"]
 
@@ -147,29 +158,32 @@ Return ONLY this descriptive string, with no preamble or extra formatting.
         self.crossover_rate = crossover_rate
         self.tournament_size = tournament_size
         if num_threads is not None:
-            print("num_threads is deprecated; use n_threads instead")
+            warnings.warn(
+                "The 'num_threads' parameter is deprecated and will be removed in a future version. "
+                "Use 'n_threads' instead.",
+                DeprecationWarning,
+                stacklevel=2,
+            )
             n_threads = num_threads
         self.num_threads = n_threads
         self.elitism_size = elitism_size
         self.adaptive_mutation = adaptive_mutation
         self.enable_moo = enable_moo
         self.enable_llm_crossover = enable_llm_crossover
-        self.seed = seed
+        self.seed = seed if seed is not None else self.DEFAULT_SEED
         self.output_style_guidance = (
             output_style_guidance
             if output_style_guidance is not None
             else self.DEFAULT_OUTPUT_STYLE_GUIDANCE
         )
         self.infer_output_style = infer_output_style
-        self.llm_call_counter = 0
-        self._opik_client = opik_client.get_client_cached()
-        self._current_optimization_id: Optional[str] = None
+        self._current_optimization_id: str | None = None
         self._current_generation = 0
-        self._best_fitness_history: List[float] = []
+        self._best_fitness_history: list[float] = []
         self._generations_without_improvement = 0
-        self._current_population: List[Any] = []
+        self._current_population: list[Any] = []
         self._generations_without_overall_improvement = 0
-        self._best_primary_score_history: List[float] = []
+        self._best_primary_score_history: list[float] = []
         self._gens_since_pop_improvement: int = 0
 
         if self.seed is not None:
@@ -199,13 +213,9 @@ Return ONLY this descriptive string, with no preamble or extra formatting.
             creator.create("Individual", list, fitness=fitness_attr)
 
         self.toolbox = base.Toolbox()
-        self.toolbox.register(
-            "default_individual", lambda: creator.Individual("placeholder")
-        )
-        self.toolbox.register(
-            "population", tools.initRepeat, list, self.toolbox.default_individual
-        )
-
+        # Attach methods from helper mixin modules to this instance to avoid
+        # multiple inheritance while preserving behavior.
+        self._attach_helper_methods()
         if self.enable_llm_crossover:
             self.toolbox.register("mate", self._llm_deap_crossover)
         else:
@@ -228,6 +238,95 @@ Return ONLY this descriptive string, with no preamble or extra formatting.
             f"mutation_rate: {self.mutation_rate}, crossover_rate: {self.crossover_rate}"
         )
 
+        # (methods already attached above)
+        self._mcp_context: EvolutionaryMCPContext | None = None
+
+    def _attach_helper_methods(self) -> None:
+        """Bind selected methods from mixin modules onto this instance."""
+
+        def bind(cls: Any, names: list[str]) -> None:
+            for name in names:
+                func = getattr(cls, name)
+                setattr(self, name, func.__get__(self, self.__class__))
+
+        # LLM calls
+        bind(LlmSupport, ["_call_model"])
+
+        # Mutations
+        bind(
+            MutationOps,
+            [
+                "_deap_mutation",
+                "_semantic_mutation",
+                "_structural_mutation",
+                "_word_level_mutation_prompt",
+                "_word_level_mutation",
+                "_get_synonym",
+                "_modify_phrase",
+                "_radical_innovation_mutation",
+            ],
+        )
+
+        # Crossover
+        bind(
+            CrossoverOps,
+            [
+                "_deap_crossover_chunking_strategy",
+                "_deap_crossover_word_level",
+                "_deap_crossover",
+                "_llm_deap_crossover",
+                "_extract_json_arrays",
+            ],
+        )
+
+        # Population management
+        bind(
+            PopulationOps,
+            [
+                "_initialize_population",
+                "_should_restart_population",
+                "_restart_population",
+            ],
+        )
+
+        # Evaluation
+        bind(EvaluationOps, ["_evaluate_prompt"])
+
+        # Helpers
+        bind(Helpers, ["_get_task_description_for_llm"])
+
+        # Style inference
+        bind(StyleOps, ["_infer_output_style_from_dataset"])
+
+    def get_optimizer_metadata(self) -> dict[str, Any]:
+        return {
+            "population_size": self.population_size,
+            "num_generations": self.num_generations,
+            "mutation_rate": self.mutation_rate,
+            "crossover_rate": self.crossover_rate,
+            "tournament_size": self.tournament_size,
+            "elitism_size": self.elitism_size,
+            "adaptive_mutation": self.adaptive_mutation,
+            "enable_moo": self.enable_moo,
+            "enable_llm_crossover": self.enable_llm_crossover,
+            "infer_output_style": self.infer_output_style,
+            "output_style_guidance": self.output_style_guidance,
+        }
+
+    def _create_individual_from_prompt(
+        self, prompt_candidate: chat_prompt.ChatPrompt
+    ) -> Any:
+        individual = creator.Individual(prompt_candidate.get_messages())
+        setattr(individual, "tools", copy.deepcopy(prompt_candidate.tools))
+        return individual
+
+    def _update_individual_with_prompt(
+        self, individual: Any, prompt_candidate: chat_prompt.ChatPrompt
+    ) -> Any:
+        individual[:] = prompt_candidate.get_messages()
+        setattr(individual, "tools", copy.deepcopy(prompt_candidate.tools))
+        return individual
+
     def _get_adaptive_mutation_rate(self) -> float:
         """Calculate adaptive mutation rate based on population diversity and progress."""
         if not self.adaptive_mutation or len(self._best_fitness_history) < 2:
@@ -286,552 +385,7 @@ Return ONLY this descriptive string, with no preamble or extra formatting.
 
         return total_distance / count if count > 0 else 0.0
 
-    def _deap_crossover_chunking_strategy(
-        self, messages_1_str: str, messages_2_str: str
-    ) -> Tuple[str, str]:
-        chunks1 = [
-            chunk.strip() for chunk in messages_1_str.split(".") if chunk.strip()
-        ]
-        chunks2 = [
-            chunk.strip() for chunk in messages_2_str.split(".") if chunk.strip()
-        ]
-
-        # Try chunk-level crossover if both parents have at least 2 chunks
-        if len(chunks1) >= 2 and len(chunks2) >= 2:
-            min_num_chunks = min(len(chunks1), len(chunks2))
-            # Crossover point is between 1 and min_num_chunks - 1
-            # This requires min_num_chunks >= 2, which is already checked.
-            point = random.randint(1, min_num_chunks - 1)
-
-            child1_chunks = chunks1[:point] + chunks2[point:]
-            child2_chunks = chunks2[:point] + chunks1[point:]
-
-            child1_str = ". ".join(child1_chunks) + ("." if child1_chunks else "")
-            child2_str = ". ".join(child2_chunks) + ("." if child2_chunks else "")
-
-            return child1_str, child2_str
-        else:
-            raise ValueError(
-                "Not enough chunks in either prompt for chunk-level crossover"
-            )
-
-    def _deap_crossover_word_level(
-        self, messages_1_str: str, messages_2_str: str
-    ) -> Tuple[str, str]:
-        words1 = messages_1_str.split()
-        words2 = messages_2_str.split()
-
-        # If either prompt is empty (no words), return parents
-        if not words1 or not words2:
-            return messages_1_str, messages_2_str
-
-        min_word_len = min(len(words1), len(words2))
-        # Need at least 2 words in the shorter prompt for a valid crossover point
-        if min_word_len < 2:
-            return messages_1_str, messages_2_str
-
-        # Crossover point for words: 1 to min_word_len - 1
-        point = random.randint(1, min_word_len - 1)
-        child1_words = words1[:point] + words2[point:]
-        child2_words = words2[:point] + words1[point:]
-
-        return " ".join(child1_words), " ".join(child2_words)
-
-    def _deap_crossover(self, ind1: Any, ind2: Any) -> Tuple[Any, Any]:
-        """Enhanced crossover operation that preserves semantic meaning.
-        Attempts chunk-level crossover first, then falls back to word-level.
-        """
-        reporting.display_message(
-            "      Recombining prompts by mixing and matching words and sentences.",
-            verbose=self.verbose,
-        )
-        messages_1_orig: List[Dict[str, str]] = ind1
-        messages_2_orig: List[Dict[str, str]] = ind2
-
-        for i, message_1 in enumerate(messages_1_orig):
-            role: str = message_1["role"]
-            message_1_str: str = message_1["content"]
-
-            # We check that the second message has enough AI messages and the correct role
-            if (len(messages_2_orig) >= i + 1) and (messages_2_orig[i]["role"] == role):
-                message_2 = messages_2_orig[i]
-                message_2_str: str = message_2["content"]
-
-                try:
-                    child1_str, child2_str = self._deap_crossover_chunking_strategy(
-                        message_1_str, message_2_str
-                    )
-                except ValueError:
-                    child1_str, child2_str = self._deap_crossover_word_level(
-                        message_1_str, message_2_str
-                    )
-
-                # Update the message content
-                messages_1_orig[i]["content"] = child1_str
-                messages_2_orig[i]["content"] = child2_str
-            else:
-                # We don't perform any crossover if there are not enough messages or the roles
-                # don't match
-                pass
-
-        return creator.Individual(messages_1_orig), creator.Individual(messages_2_orig)
-
-    def _deap_mutation(
-        self, individual: Any, initial_prompt: chat_prompt.ChatPrompt
-    ) -> Any:
-        """Enhanced mutation operation with multiple strategies."""
-        prompt = chat_prompt.ChatPrompt(messages=individual)
-
-        # Choose mutation strategy based on current diversity
-        diversity = self._calculate_population_diversity()
-
-        # Determine thresholds based on diversity
-        if diversity < self.DEFAULT_DIVERSITY_THRESHOLD:
-            # Low diversity - use more aggressive mutations (higher chance for semantic)
-            semantic_threshold = 0.5
-            structural_threshold = 0.8  # semantic_threshold + 0.3
-        else:
-            # Good diversity - use more conservative mutations (higher chance for word_level)
-            semantic_threshold = 0.4
-            structural_threshold = 0.7  # semantic_threshold + 0.3
-
-        mutation_choice = random.random()
-
-        if mutation_choice > structural_threshold:
-            # This corresponds to the original 'else' (word_level_mutation)
-            mutated_prompt = self._word_level_mutation_prompt(prompt)
-            reporting.display_success(
-                "      Mutation successful, prompt has been edited by randomizing words (word-level mutation).",
-                verbose=self.verbose,
-            )
-            return creator.Individual(mutated_prompt.get_messages())
-        elif mutation_choice > semantic_threshold:
-            # This corresponds to the original 'elif' (structural_mutation)
-            mutated_prompt = self._structural_mutation(prompt)
-            reporting.display_success(
-                "      Mutation successful, prompt has been edited by reordering, combining, or splitting sentences (structural mutation).",
-                verbose=self.verbose,
-            )
-            return creator.Individual(mutated_prompt.get_messages())
-        else:
-            # This corresponds to the original 'if' (semantic_mutation)
-            mutated_prompt = self._semantic_mutation(prompt, initial_prompt)
-            reporting.display_success(
-                "      Mutation successful, prompt has been edited using an LLM (semantic mutation).",
-                verbose=self.verbose,
-            )
-            return creator.Individual(mutated_prompt.get_messages())
-
-    def _semantic_mutation(
-        self, prompt: chat_prompt.ChatPrompt, initial_prompt: chat_prompt.ChatPrompt
-    ) -> chat_prompt.ChatPrompt:
-        """Enhanced semantic mutation with multiple strategies."""
-        current_output_style_guidance = self.output_style_guidance
-        if random.random() < 0.1:
-            return self._radical_innovation_mutation(prompt, initial_prompt)
-
-        try:
-            strategy = random.choice(
-                [
-                    "rephrase",
-                    "simplify",
-                    "elaborate",
-                    "restructure",
-                    "focus",
-                    "increase_complexity_and_detail",
-                ]
-            )
-
-            strategy_prompts = {
-                "rephrase": f"Create a different way to express the same instruction, possibly with a different length or structure, ensuring it still aims for an answer from the target LLM in the style of: '{current_output_style_guidance}'.",
-                "simplify": f"Simplify the instruction while maintaining its core meaning, potentially making it more concise, to elicit an answer in the style of: '{current_output_style_guidance}'.",
-                "elaborate": f"Add more relevant detail and specificity to the instruction, potentially increasing its length, but only if it helps achieve a more accurate answer from the target LLM in the style of: '{current_output_style_guidance}'.",
-                "restructure": f"Change the structure of the instruction (e.g., reorder sentences, combine/split ideas) while keeping its intent, ensuring the new structure strongly guides towards an output in the style of: '{current_output_style_guidance}'.",
-                "focus": f"Emphasize the key aspects of the instruction, perhaps by rephrasing or adding clarifying statements, to better elicit an answer in the style of: '{current_output_style_guidance}'.",
-                "increase_complexity_and_detail": f"Significantly elaborate on this instruction. Add more details, examples, context, or constraints to make it more comprehensive. The goal of this elaboration is to make the prompt itself more detailed, so that it VERY CLEARLY guides the target LLM to produce a highly accurate final answer in the style of: '{current_output_style_guidance}'. The prompt can be long if needed to achieve this output style.",
-            }
-
-            user_prompt_for_semantic_mutation = f"""Given this prompt: '{prompt}'
-Task context: {self._get_task_description_for_llm(initial_prompt)}
-Desired output style from target LLM: '{current_output_style_guidance}'
-Instruction for this modification: {strategy_prompts[strategy]}.
-Return only the modified prompt message list, nothing else. Make sure to return a valid JSON object.
-"""
-            response = self._call_model(
-                messages=[
-                    {
-                        "role": "system",
-                        "content": f"You are a prompt engineering expert. Your goal is to modify prompts to improve their effectiveness in eliciting specific types of answers, particularly matching the style: '{current_output_style_guidance}'. Follow the specific modification instruction provided.",
-                    },
-                    {"role": "user", "content": user_prompt_for_semantic_mutation},
-                ],
-                is_reasoning=True,
-            )
-
-            return chat_prompt.ChatPrompt(messages=utils.json_to_dict(response.strip()))
-        except Exception as e:
-            reporting.display_error(
-                f"      Error in semantic mutation, this is usually a parsing error: {e}",
-                verbose=self.verbose,
-            )
-            return prompt
-
-    def _structural_mutation(
-        self, prompt: chat_prompt.ChatPrompt
-    ) -> chat_prompt.ChatPrompt:
-        """Perform structural mutation (reordering, combining, splitting)."""
-        mutated_messages: List[Dict[str, str]] = []
-
-        for message in prompt.get_messages():
-            content = message["content"]
-            role = message["role"]
-
-            sentences = [s.strip() for s in content.split(".") if s.strip()]
-            if len(sentences) <= 1:
-                mutated_messages.append(
-                    {"role": role, "content": self._word_level_mutation(content)}
-                )
-                continue
-
-            mutation_type = random.random()
-            if mutation_type < 0.3:
-                # Reorder sentences
-                random.shuffle(sentences)
-                mutated_messages.append(
-                    {"role": role, "content": ". ".join(sentences) + "."}
-                )
-                continue
-            elif mutation_type < 0.6:
-                # Combine adjacent sentences
-                if len(sentences) >= 2:
-                    idx = random.randint(0, len(sentences) - 2)
-                    combined = sentences[idx] + " and " + sentences[idx + 1]
-                    sentences[idx : idx + 2] = [combined]
-                    mutated_messages.append(
-                        {"role": role, "content": ". ".join(sentences) + "."}
-                    )
-                    continue
-            else:
-                # Split a sentence
-                idx = random.randint(0, len(sentences) - 1)
-                words = sentences[idx].split()
-                if len(words) > 3:
-                    split_point = random.randint(2, len(words) - 2)
-                    sentences[idx : idx + 1] = [
-                        " ".join(words[:split_point]),
-                        " ".join(words[split_point:]),
-                    ]
-                    mutated_messages.append(
-                        {"role": role, "content": ". ".join(sentences) + "."}
-                    )
-                    continue
-                else:
-                    mutated_messages.append({"role": role, "content": content})
-
-        return chat_prompt.ChatPrompt(messages=mutated_messages)
-
-    def _word_level_mutation_prompt(
-        self, prompt: chat_prompt.ChatPrompt
-    ) -> chat_prompt.ChatPrompt:
-        mutated_messages: List[Dict[str, str]] = []
-        for message in prompt.get_messages():
-            mutated_messages.append(
-                {
-                    "role": message["role"],
-                    "content": self._word_level_mutation(message["content"]),
-                }
-            )
-        return chat_prompt.ChatPrompt(messages=mutated_messages)
-
-    def _word_level_mutation(self, msg_content: str) -> str:
-        """Perform word-level mutation."""
-        words = msg_content.split()
-        if len(words) <= 1:
-            return msg_content
-
-        mutation_type = random.random()
-        if mutation_type < 0.3:
-            # Word replacement
-            idx = random.randint(0, len(words) - 1)
-            words[idx] = self._get_synonym(words[idx])
-        elif mutation_type < 0.6:
-            # Word reordering
-            if len(words) > 2:
-                i, j = random.sample(range(len(words)), 2)
-                words[i], words[j] = words[j], words[i]
-        else:
-            # Phrase modification
-            idx = random.randint(0, len(words) - 1)
-            words[idx] = self._modify_phrase(words[idx])
-
-        return " ".join(words)
-
-    def _get_synonym(self, word: str) -> str:
-        """Get a synonym for a word using LLM."""
-        try:
-            response = self._call_model(
-                messages=[
-                    {
-                        "role": "system",
-                        "content": "You are a helpful assistant that provides synonyms. Return only the synonym word, no explanation or additional text.",
-                    },
-                    {
-                        "role": "user",
-                        "content": f"Give me a single synonym for the word '{word}'. Return only the synonym, nothing else.",
-                    },
-                ],
-                is_reasoning=True,
-            )
-            return response.strip()
-        except Exception as e:
-            logger.warning(f"Error getting synonym for '{word}': {e}")
-            return word
-
-    def _modify_phrase(self, phrase: str) -> str:
-        """Modify a phrase while preserving meaning using LLM."""
-        try:
-            response = self._call_model(
-                messages=[
-                    {
-                        "role": "system",
-                        "content": "You are a helpful assistant that rephrases text. Return only the modified phrase, no explanation or additional text.",
-                    },
-                    {
-                        "role": "user",
-                        "content": f"Modify this phrase while keeping the same meaning: '{phrase}'. Return only the modified phrase, nothing else.",
-                    },
-                ],
-                is_reasoning=True,
-            )
-            return response.strip()
-        except Exception as e:
-            logger.warning(f"Error modifying phrase '{phrase}': {e}")
-            return phrase
-
-    def _radical_innovation_mutation(
-        self, prompt: chat_prompt.ChatPrompt, initial_prompt: chat_prompt.ChatPrompt
-    ) -> chat_prompt.ChatPrompt:
-        """Attempts to generate a significantly improved and potentially very different prompt using an LLM."""
-        logger.debug(
-            f"Attempting radical innovation for prompt: {json.dumps(prompt.get_messages())[:70]}..."
-        )
-        task_desc_for_llm = self._get_task_description_for_llm(initial_prompt)
-        current_output_style_guidance = self.output_style_guidance
-
-        user_prompt_for_radical_innovation = f"""Task Context:
-{task_desc_for_llm}
-Desired output style from target LLM: '{current_output_style_guidance}'
-
-Existing Prompt (which may be underperforming):
-'''{prompt.get_messages()}'''
-
-Please generate a new, significantly improved, and potentially very different prompt for this task.
-Focus on alternative approaches, better clarity, or more effective guidance for the language model, aiming for the desired output style.
-Return only the new prompt list object.
-"""
-        try:
-            new_prompt_str = self._call_model(
-                messages=[
-                    {
-                        "role": "system",
-                        "content": self._get_radical_innovation_system_prompt(),
-                    },
-                    {"role": "user", "content": user_prompt_for_radical_innovation},
-                ],
-                is_reasoning=True,
-            )
-            logger.info(
-                f"Radical innovation generated: {new_prompt_str[:70]}... from: {json.dumps(prompt.get_messages())[:70]}..."
-            )
-            return chat_prompt.ChatPrompt(messages=json.loads(new_prompt_str))
-        except Exception as e:
-            logger.warning(
-                f"Radical innovation mutation failed for prompt '{json.dumps(prompt.get_messages())[:50]}...': {e}. Returning original."
-            )
-            return prompt
-
-    def _initialize_population(
-        self, prompt: chat_prompt.ChatPrompt
-    ) -> List[chat_prompt.ChatPrompt]:
-        """Initialize the population with diverse variations of the initial prompt,
-        including some 'fresh start' prompts based purely on task description.
-        All generated prompts should aim to elicit answers matching self.output_style_guidance.
-        """
-        with reporting.initializing_population(verbose=self.verbose) as init_pop_report:
-            init_pop_report.start(self.population_size)
-
-            population = [prompt]
-            if self.population_size <= 1:
-                return population
-
-            num_to_generate_total = self.population_size - 1
-            num_fresh_starts = max(1, int(num_to_generate_total * 0.2))
-            num_variations_on_initial = num_to_generate_total - num_fresh_starts
-
-            task_desc_for_llm = self._get_task_description_for_llm(prompt)
-            current_output_style_guidance = self.output_style_guidance
-
-            # Generate "fresh start" prompts if the initial prompt is not performing well
-            # Cold start prompts are generated from the task description
-            if num_fresh_starts > 0:
-                init_pop_report.start_fresh_prompts(num_fresh_starts)
-                fresh_start_user_prompt = f"""Here is a description of a task:
-    {task_desc_for_llm}
-
-    The goal is to generate prompts that will make a target LLM produce responses in the following style: '{current_output_style_guidance}'.
-
-    Please generate {num_fresh_starts} diverse and effective prompt(s) for a language model to accomplish this task, ensuring they guide towards this specific output style.
-    Focus on clarity, completeness, and guiding the model effectively towards the desired style. Explore different structural approaches.
-
-    Example of valid response: [
-        ["role": "<role>", "content": "<Prompt targeting specified style.>"],
-        ["role": "<role>", "content": "<Another prompt designed for the output style.>"]
-    ]
-
-    Your response MUST be a valid JSON list of AI messages. Do NOT include any other text, explanations, or Markdown formatting like ```json ... ``` around the list.
-
-    """
-                try:
-                    response_content = self._call_model(
-                        messages=[
-                            {
-                                "role": "system",
-                                "content": f"You are an expert prompt engineer. Your task is to generate novel, effective prompts from scratch based on a task description, specifically aiming for prompts that elicit answers in the style: '{current_output_style_guidance}'. Output ONLY a raw JSON list of strings.",
-                            },
-                            {"role": "user", "content": fresh_start_user_prompt},
-                        ],
-                        is_reasoning=True,
-                    )
-
-                    logger.debug(
-                        f"Raw LLM response for fresh start prompts: {response_content}"
-                    )
-
-                    fresh_prompts = utils.json_to_dict(response_content)
-                    if isinstance(fresh_prompts, list):
-                        if all(isinstance(p, dict) for p in fresh_prompts) and all(
-                            p.get("role") is not None for p in fresh_prompts
-                        ):
-                            population.append(
-                                chat_prompt.ChatPrompt(messages=fresh_prompts)
-                            )
-                            init_pop_report.success_fresh_prompts(1)
-                        elif all(isinstance(p, list) for p in fresh_prompts):
-                            population.extend(
-                                [
-                                    chat_prompt.ChatPrompt(messages=p)
-                                    for p in fresh_prompts[:num_fresh_starts]
-                                ]
-                            )
-                            init_pop_report.success_fresh_prompts(
-                                len(fresh_prompts[:num_fresh_starts])
-                            )
-                        else:
-                            init_pop_report.failed_fresh_prompts(
-                                num_fresh_starts,
-                                f"LLM response for fresh starts was not a valid list of strings or was empty: {response_content}. Skipping fresh start prompts.",
-                            )
-                except json.JSONDecodeError as e_json:
-                    init_pop_report.failed_fresh_prompts(
-                        num_fresh_starts,
-                        f"JSONDecodeError generating fresh start prompts: {e_json}. LLM response: '{response_content}'. Skipping fresh start prompts.",
-                    )
-                except Exception as e:
-                    init_pop_report.failed_fresh_prompts(
-                        num_fresh_starts,
-                        f"Error generating fresh start prompts: {e}. Skipping fresh start prompts.",
-                    )
-
-            # Generate variations on the initial prompt for the remaining slots
-            # TODO: Could add variations with hyper-parameters from the task config like temperature, etc.
-            if num_variations_on_initial > 0:
-                init_pop_report.start_variations(num_variations_on_initial)
-
-                # TODO: We need to split this into batches as the model will not return enough tokens
-                # to generate all the candidates
-                user_prompt_for_variation = f"""Initial prompt:
-    '''{prompt.get_messages()}'''
-
-    Task context:
-    {task_desc_for_llm}
-    Desired output style from target LLM: '{current_output_style_guidance}'
-
-    Generate {num_variations_on_initial} diverse alternative prompts based on the initial prompt above, keeping the task context and desired output style in mind.
-    All generated prompt variations should strongly aim to elicit answers from the target LLM matching the style: '{current_output_style_guidance}'.
-    For each variation, consider how to best achieve this style, e.g., by adjusting specificity, structure, phrasing, constraints, or by explicitly requesting it.
-
-    Return a JSON array of prompts with the following structure:
-    {{
-        "prompts": [
-            {{
-                "prompt": [{{"role": "<role>", "content": "<content>"}}],
-                "strategy": "brief description of the variation strategy used, e.g., 'direct instruction for target style'"
-            }}
-            // ... more prompts if num_variations_on_initial > 1
-        ]
-    }}
-    Ensure a good mix of variations, all targeting the specified output style from the end LLM.
-
-    Return a valid JSON object that is correctly escaped. Return nothing else, d`o not include any additional text or Markdown formatting.
-    """
-                try:
-                    response_content_variations = self._call_model(
-                        messages=[
-                            {
-                                "role": "system",
-                                "content": self._get_reasoning_system_prompt_for_variation(),
-                            },
-                            {"role": "user", "content": user_prompt_for_variation},
-                        ],
-                        is_reasoning=True,
-                    )
-                    logger.debug(
-                        f"Raw response for population variations: {response_content_variations}"
-                    )
-                    json_response_variations = json.loads(response_content_variations)
-                    generated_prompts_variations = [
-                        p["prompt"]
-                        for p in json_response_variations.get("prompts", [])
-                        if isinstance(p, dict) and "prompt" in p
-                    ]
-
-                    if generated_prompts_variations:
-                        init_pop_report.success_variations(
-                            len(
-                                generated_prompts_variations[:num_variations_on_initial]
-                            )
-                        )
-                        population.extend(
-                            [
-                                chat_prompt.ChatPrompt(messages=p)
-                                for p in generated_prompts_variations[
-                                    :num_variations_on_initial
-                                ]
-                            ]
-                        )
-                    else:
-                        init_pop_report.failed_variations(
-                            num_variations_on_initial,
-                            "Could not parse 'prompts' list for variations. Skipping variations.",
-                        )
-                except Exception as e:
-                    init_pop_report.failed_variations(
-                        num_variations_on_initial,
-                        f"Error calling LLM for initial population variations: {e}",
-                    )
-
-            # Ensure population is of the required size using unique prompts
-            # TODO Test with levenshtein distance
-            final_population_set: Set[str] = set()
-            final_population_list: List[chat_prompt.ChatPrompt] = []
-            for p in population:
-                if json.dumps(p.get_messages()) not in final_population_set:
-                    final_population_set.add(json.dumps(p.get_messages()))
-                    final_population_list.append(p)
-
-            init_pop_report.end(final_population_list)
-            # Return exactly population_size prompts if possible, or fewer if generation failed badly.
-            return final_population_list[: self.population_size]
+    # Mutations and helpers are implemented in mixins.
 
     def _should_restart_population(self, curr_best: float) -> bool:
         """
@@ -852,9 +406,9 @@ Return only the new prompt list object.
     def _restart_population(
         self,
         hof: tools.HallOfFame,
-        population: List[Any],
+        population: list[Any],
         best_prompt_so_far: chat_prompt.ChatPrompt,
-    ) -> List[Any]:
+    ) -> list[Any]:
         """Return a fresh, evaluated population seeded by elites."""
         if self.enable_moo:
             elites = list(hof)
@@ -870,7 +424,7 @@ Return only the new prompt list object.
         )
 
         prompt_variants = self._initialize_population(seed_prompt)
-        new_pop = [creator.Individual(p.get_messages()) for p in prompt_variants]
+        new_pop = [self._create_individual_from_prompt(p) for p in prompt_variants]
 
         for ind, fit in zip(new_pop, map(self.toolbox.evaluate, new_pop)):
             ind.fitness.values = fit
@@ -881,12 +435,12 @@ Return only the new prompt list object.
     def _run_generation(
         self,
         generation_idx: int,
-        population: List[Any],
+        population: list[Any],
         prompt: chat_prompt.ChatPrompt,
         hof: tools.HallOfFame,
         report: Any,
         best_primary_score_overall: float,
-    ) -> tuple[List[Any], int]:
+    ) -> tuple[list[Any], int]:
         """Execute mating, mutation, evaluation and HoF update."""
         best_gen_score = 0.0
 
@@ -952,7 +506,7 @@ Return only the new prompt list object.
 
         return offspring, len(invalid)
 
-    def _population_best_score(self, population: List[Any]) -> float:
+    def _population_best_score(self, population: list[Any]) -> float:
         """Return highest primary-objective score among *valid* individuals."""
         valid_scores = [
             ind.fitness.values[0] for ind in population if ind.fitness.valid
@@ -964,10 +518,10 @@ Return only the new prompt list object.
         prompt: chat_prompt.ChatPrompt,
         dataset: opik.Dataset,
         metric: Callable,
-        experiment_config: Optional[Dict] = None,
-        n_samples: Optional[int] = None,
+        experiment_config: dict | None = None,
+        n_samples: int | None = None,
         auto_continue: bool = False,
-        agent_class: Optional[Type[OptimizableAgent]] = None,
+        agent_class: type[OptimizableAgent] | None = None,
         **kwargs: Any,
     ) -> OptimizationResult:
         """
@@ -978,35 +532,27 @@ Return only the new prompt list object.
             experiment_config: Optional experiment configuration
             n_samples: Optional number of samples to use
             auto_continue: Whether to automatically continue optimization
-            **kwargs: Additional keyword arguments
+            agent_class: Optional agent class to use
+            **kwargs: Additional keyword arguments including:
+                mcp_config (MCPExecutionConfig | None): MCP tool calling configuration (default: None)
         """
-        if not isinstance(prompt, chat_prompt.ChatPrompt):
-            raise ValueError("Prompt must be a ChatPrompt object")
-
-        if not isinstance(dataset, opik.Dataset):
-            raise ValueError("Dataset must be a Dataset object")
+        # Use base class validation and setup methods
+        self.validate_optimization_inputs(prompt, dataset, metric)
+        self.configure_prompt_model(prompt)
+        self.agent_class = self.setup_agent_class(prompt, agent_class)
 
-        if not callable(metric):
-            raise ValueError(
-                "Metric must be a function that takes `dataset_item` and `llm_output` as arguments."
-            )
-
-        if prompt.model is None:
-            prompt.model = self.model
-        if prompt.model_kwargs is None:
-            prompt.model_kwargs = self.model_kwargs
-
-        if agent_class is None:
-            self.agent_class = utils.create_litellm_agent_class(prompt)
-        else:
-            self.agent_class = agent_class
+        # Extract MCP config from kwargs (for optional MCP workflows)
+        mcp_config = kwargs.pop("mcp_config", None)
+        evaluation_kwargs: dict[str, Any] = {}
+        if mcp_config is not None:
+            evaluation_kwargs["mcp_config"] = mcp_config
 
         self.project_name = self.agent_class.project_name
 
         # Step 0. Start Opik optimization run
-        opik_optimization_run: Optional[optimization.Optimization] = None
+        opik_optimization_run: optimization.Optimization | None = None
         try:
-            opik_optimization_run = self._opik_client.create_optimization(
+            opik_optimization_run = self.opik_client.create_optimization(
                 dataset_name=dataset.name,
                 objective_name=metric.__name__,
                 metadata={"optimizer": self.__class__.__name__},
@@ -1026,18 +572,19 @@ Return only the new prompt list object.
         reporting.display_configuration(
             prompt.get_messages(),
             {
-                "optimizer": f"{ 'DEAP MOO' if self.enable_moo else 'DEAP SO' } Evolutionary Optimization",
+                "optimizer": f"{'DEAP MOO' if self.enable_moo else 'DEAP SO'} Evolutionary Optimization",
                 "population_size": self.population_size,
                 "generations": self.num_generations,
                 "mutation_rate": self.mutation_rate,
                 "crossover_rate": self.crossover_rate,
             },
             verbose=self.verbose,
+            tools=getattr(prompt, "tools", None),
         )
 
         # Step 1. Step variables and define fitness function
-        self.llm_call_counter = 0
-        self._history: List[OptimizationRound] = []
+        self.reset_counters()  # Reset counters for run
+        self._history: list[OptimizationRound] = []
         self._current_generation = 0
         self._best_fitness_history = []
         self._generations_without_improvement = 0
@@ -1047,8 +594,8 @@ Return only the new prompt list object.
         if self.enable_moo:
 
             def _deap_evaluate_individual_fitness(
-                messages: List[Dict[str, str]],
-            ) -> Tuple[float, float]:
+                messages: list[dict[str, str]],
+            ) -> tuple[float, float]:
                 primary_fitness_score: float = self._evaluate_prompt(
                     prompt,
                     messages,  # type: ignore
@@ -1058,6 +605,7 @@ Return only the new prompt list object.
                     experiment_config=(experiment_config or {}).copy(),
                     optimization_id=self._current_optimization_id,
                     verbose=0,
+                    **evaluation_kwargs,
                 )
                 prompt_length = float(len(str(json.dumps(messages))))
                 return (primary_fitness_score, prompt_length)
@@ -1065,8 +613,8 @@ Return only the new prompt list object.
         else:
             # Single-objective
             def _deap_evaluate_individual_fitness(
-                messages: List[Dict[str, str]],
-            ) -> Tuple[float, float]:
+                messages: list[dict[str, str]],
+            ) -> tuple[float, float]:
                 fitness_score: float = self._evaluate_prompt(
                     prompt,
                     messages,  # type: ignore
@@ -1076,6 +624,7 @@ Return only the new prompt list object.
                     experiment_config=(experiment_config or {}).copy(),
                     optimization_id=self._current_optimization_id,
                     verbose=0,
+                    **evaluation_kwargs,
                 )
                 return (fitness_score, 0.0)
 
@@ -1123,12 +672,12 @@ Return only the new prompt list object.
             self.output_style_guidance = self.DEFAULT_OUTPUT_STYLE_GUIDANCE
 
         # Step 4. Initialize population
-        initial_prompts: List[chat_prompt.ChatPrompt] = self._initialize_population(
+        initial_prompts: list[chat_prompt.ChatPrompt] = self._initialize_population(
             prompt=prompt
         )
 
         deap_population = [
-            creator.Individual(p.get_messages()) for p in initial_prompts
+            self._create_individual_from_prompt(p) for p in initial_prompts
         ]
         deap_population = deap_population[: self.population_size]
 
@@ -1143,7 +692,7 @@ Return only the new prompt list object.
         with reporting.evaluate_initial_population(
             verbose=self.verbose
         ) as report_initial_population:
-            fitnesses: List[Any] = list(map(self.toolbox.evaluate, deap_population))
+            fitnesses: list[Any] = list(map(self.toolbox.evaluate, deap_population))
             _best_score = max(
                 best_primary_score_overall, max([x[0] for x in fitnesses])
             )
@@ -1302,7 +851,7 @@ Return only the new prompt list object.
                     hof, key=lambda ind: ind.fitness.values[0], reverse=True
                 )
                 for i, sol in enumerate(sorted_hof):
-                    final_results_log += f"  Solution {i+1}: Primary Score={sol.fitness.values[0]:.4f}, Length={sol.fitness.values[1]:.0f}, Prompt='{str(sol)[:100]}...'\n"
+                    final_results_log += f"  Solution {i + 1}: Primary Score={sol.fitness.values[0]:.4f}, Length={sol.fitness.values[1]:.0f}, Prompt='{str(sol)[:100]}...'\n"
                 best_overall_solution = sorted_hof[0]
                 final_best_prompt = chat_prompt.ChatPrompt(
                     messages=best_overall_solution
@@ -1419,7 +968,21 @@ Return only the new prompt list object.
             best_score=final_primary_score,
             best_prompt=final_best_prompt.get_messages(),
             verbose=self.verbose,
+            tools=getattr(final_best_prompt, "tools", None),
         )
+
+        final_tools = getattr(final_best_prompt, "tools", None)
+        if final_tools:
+            final_details["final_tools"] = final_tools
+            tool_prompts = {
+                (tool.get("function", {}).get("name") or f"tool_{idx}"): tool.get(
+                    "function", {}
+                ).get("description")
+                for idx, tool in enumerate(final_tools)
+            }
+        else:
+            tool_prompts = None
+
         return OptimizationResult(
             optimizer=self.__class__.__name__,
             prompt=final_best_prompt.get_messages(),
@@ -1430,357 +993,117 @@ Return only the new prompt list object.
             details=final_details,
             history=[x.model_dump() for x in self.get_history()],
             llm_calls=self.llm_call_counter,
+            tool_calls=self.tool_call_counter,
             dataset_id=dataset.id,
             optimization_id=self._current_optimization_id,
+            tool_prompts=tool_prompts,
         )
 
-    @_throttle.rate_limited(_rate_limiter)
-    def _call_model(
-        self,
-        messages: List[Dict[str, str]],
-        is_reasoning: bool = False,
-        optimization_id: Optional[str] = None,
-    ) -> str:
-        """Call the model with the given prompt and return the response."""
-        try:
-            # Basic LLM parameters
-            llm_config_params = {
-                "temperature": getattr(self, "temperature", 0.3),
-                "max_tokens": getattr(self, "max_tokens", 1000),
-                "top_p": getattr(self, "top_p", 1.0),
-                "frequency_penalty": getattr(self, "frequency_penalty", 0.0),
-                "presence_penalty": getattr(self, "presence_penalty", 0.0),
-            }
-
-            # Prepare metadata for opik
-            metadata_for_opik: Dict[str, Any] = {}
-            if self.project_name:
-                metadata_for_opik["project_name"] = self.project_name
-                metadata_for_opik["opik"] = {"project_name": self.project_name}
-
-            if optimization_id:
-                if "opik" in metadata_for_opik:
-                    metadata_for_opik["opik"]["optimization_id"] = optimization_id
-
-            metadata_for_opik["optimizer_name"] = self.__class__.__name__
-            metadata_for_opik["opik_call_type"] = (
-                "reasoning" if is_reasoning else "evaluation_llm_task_direct"
-            )
-
-            if metadata_for_opik:
-                llm_config_params["metadata"] = metadata_for_opik
-
-            # Pass llm_config_params to the Opik monitor
-            final_call_params = opik_litellm_monitor.try_add_opik_monitoring_to_params(
-                llm_config_params.copy()
-            )
-
-            logger.debug(
-                f"Calling model '{self.model}' with messages: {messages}, "
-                f"final params for litellm (from monitor): {final_call_params}"
-            )
-
-            response = litellm.completion(
-                model=self.model, messages=messages, **final_call_params
-            )
-            self.llm_call_counter += 1
-
-            logger.debug(f"Response: {response}")
-            return response.choices[0].message.content
-        except litellm_exceptions.RateLimitError as e:
-            logger.error(f"LiteLLM Rate Limit Error: {e}")
-            raise
-        except litellm_exceptions.APIConnectionError as e:
-            logger.error(f"LiteLLM API Connection Error: {e}")
-            raise
-        except litellm_exceptions.ContextWindowExceededError as e:
-            logger.error(f"LiteLLM Context Window Exceeded Error: {e}")
-            raise
-        except Exception as e:
-            logger.error(
-                f"Error calling model '{self.model}': {type(e).__name__} - {e}"
-            )
-            raise
-
-    def _evaluate_prompt(
+    def optimize_mcp(
         self,
         prompt: chat_prompt.ChatPrompt,
-        messages: List[Dict[str, str]],
         dataset: opik.Dataset,
         metric: Callable,
-        n_samples: Optional[int] = None,
-        dataset_item_ids: Optional[List[str]] = None,
-        experiment_config: Optional[Dict] = None,
-        optimization_id: Optional[str] = None,
-        verbose: int = 0,
+        *,
+        tool_name: str,
+        second_pass: MCPSecondPassCoordinator,
+        experiment_config: dict | None = None,
+        n_samples: int | None = None,
+        auto_continue: bool = False,
+        agent_class: type[OptimizableAgent] | None = None,
+        fallback_invoker: Callable[[dict[str, Any]], str] | None = None,
+        fallback_arguments: Callable[[Any], dict[str, Any]] | None = None,
+        allow_tool_use_on_second_pass: bool = False,
         **kwargs: Any,
-    ) -> float:
-        """
-        Evaluate a single prompt (individual) against the dataset.
-
-        Args:
-            prompt:
-            dataset: The dataset to use for evaluation
-            metric: Metric function to evaluate on, should have the arguments `dataset_item` and `llm_output`
-            n_samples: Optional number of samples to use
-            dataset_item_ids: Optional list of dataset item IDs to use
-            experiment_config: Optional experiment configuration
-            optimization_id: Optional optimization ID
-            verbose: Controls internal logging/progress bars (0=off, 1=on).
-
-        Returns:
-            float: The metric value
-        """
-        total_items = len(dataset.get_items())
-
-        new_prompt = prompt.copy()
-        new_prompt.set_messages(messages)
-
-        experiment_config = experiment_config or {}
-        experiment_config["project_name"] = self.agent_class.project_name
-        experiment_config = {
-            **experiment_config,
-            "optimizer": self.__class__.__name__,
-            "agent_class": self.agent_class.__name__,
-            "agent_config": new_prompt.to_dict(),
-            "metric": metric.__name__,
-            "dataset": dataset.name,
-            "configuration": {
-                "prompt": new_prompt.get_messages(),
-                "n_samples_for_eval": (
-                    len(dataset_item_ids) if dataset_item_ids is not None else n_samples
-                ),
-                "total_dataset_items": total_items,
-            },
-        }
-        try:
-            agent = self.agent_class(new_prompt)
-        except Exception:
-            return 0.0
-
-        def llm_task(dataset_item: Dict[str, Any]) -> Dict[str, str]:
-            # print("MESSAGES:", new_prompt.messages)
-            messages = new_prompt.get_messages(dataset_item)
-            model_output = agent.invoke(messages)
-            # print("OUTPUT:", model_output)
-            return {mappers.EVALUATED_LLM_TASK_OUTPUT: model_output}
-
-        # Evaluate the prompt
-        score = task_evaluator.evaluate(
-            dataset=dataset,
-            dataset_item_ids=dataset_item_ids,
-            metric=metric,
-            evaluated_task=llm_task,
-            num_threads=self.num_threads,
-            project_name=experiment_config["project_name"],
-            n_samples=n_samples if dataset_item_ids is None else None,
-            experiment_config=experiment_config,
-            optimization_id=optimization_id,
-            verbose=verbose,
-        )
-        return score
-
-    def _llm_deap_crossover(self, ind1: Any, ind2: Any) -> Tuple[Any, Any]:
-        """Perform crossover by asking an LLM to blend two parent prompts."""
-        reporting.display_message(
-            "      Recombining prompts using an LLM.", verbose=self.verbose
+    ) -> OptimizationResult:
+        if prompt.tools is None or not prompt.tools:
+            raise ValueError("Prompt must include tools for MCP optimization")
+
+        panel_style = kwargs.pop("tool_panel_style", "bright_magenta")
+
+        segments = extract_prompt_segments(prompt)
+        tool_segment_id = f"tool:{tool_name}"
+        segment_lookup = {segment.segment_id: segment for segment in segments}
+        if tool_segment_id not in segment_lookup:
+            raise ValueError(f"Tool '{tool_name}' not present in prompt tools")
+
+        fallback_args_fn = fallback_arguments or extract_tool_arguments
+
+        if fallback_invoker is None:
+            function_map = getattr(prompt, "function_map", {}) or {}
+            default_invoker_candidate = function_map.get(tool_name)
+            if default_invoker_candidate is not None:
+                typed_invoker = cast(Callable[..., str], default_invoker_candidate)
+
+                def _fallback_invoker(args: dict[str, Any]) -> str:
+                    return typed_invoker(**args)
+
+                fallback_invoker = _fallback_invoker
+
+        tool_entry = None
+        for entry in prompt.tools or []:
+            function = entry.get("function", {})
+            if (function.get("name") or entry.get("name")) == tool_name:
+                tool_entry = entry
+                break
+        if tool_entry is None:
+            raise ValueError(f"Tool '{tool_name}' not present in prompt.tools")
+
+        original_description = tool_entry.get("function", {}).get("description", "")
+        tool_metadata = segment_lookup[tool_segment_id].metadata.get("raw_tool", {})
+
+        mcp_config = MCPExecutionConfig(
+            coordinator=second_pass,
+            tool_name=tool_name,
+            fallback_arguments=fallback_args_fn,
+            fallback_invoker=fallback_invoker,
+            allow_tool_use_on_second_pass=allow_tool_use_on_second_pass,
         )
 
-        parent1_messages: List[Dict[str, str]] = ind1
-        parent2_messages: List[Dict[str, str]] = ind2
-        current_output_style_guidance = self.output_style_guidance
-
-        user_prompt_for_llm_crossover = f"""Parent Prompt 1:
-'''{parent1_messages}'''
+        previous_context = getattr(self, "_mcp_context", None)
+        previous_crossover = self.enable_llm_crossover
 
-Parent Prompt 2:
-'''{parent2_messages}'''
+        context = EvolutionaryMCPContext(
+            tool_name=tool_name,
+            tool_segment_id=tool_segment_id,
+            original_description=original_description,
+            tool_metadata=tool_metadata,
+            panel_style=panel_style,
+        )
 
-Desired output style from target LLM for children prompts: '{current_output_style_guidance}'
+        self._mcp_context = context
+        self.enable_llm_crossover = False
 
-Please generate TWO child prompts by intelligently blending the ideas, styles, or structures from these two parents, ensuring the children aim to elicit the desired output style.
-Follow the instructions provided in the system prompt regarding the JSON output format:
-[
-    [{{"role": "<role>", "content": "<content>"}}, {{"role": "<role>", "content": "<content>"}}], #child_1
-    [{{"role": "<role>", "content": "<content>"}}, {{"role": "<role>", "content": "<content>"}}], #child_2
-]
-"""
         try:
-            logger.debug(
-                f"Attempting LLM-driven crossover between: '{parent1_messages[:50]}...' and '{parent2_messages[:50]}...' aiming for style: '{current_output_style_guidance[:30]}...'"
+            result = self.optimize_prompt(
+                prompt=prompt,
+                dataset=dataset,
+                metric=metric,
+                experiment_config=experiment_config,
+                n_samples=n_samples,
+                auto_continue=auto_continue,
+                agent_class=agent_class,
+                mcp_config=mcp_config,
+                **kwargs,
             )
-            response_content = self._call_model(
-                messages=[
-                    {
-                        "role": "system",
-                        "content": self.get_llm_crossover_system_prompt(),
-                    },
-                    {"role": "user", "content": user_prompt_for_llm_crossover},
-                ],
-                is_reasoning=True,
-            )
-            logger.debug(f"Raw LLM response for crossover: {response_content}")
-
-            json_response = utils.json_to_dict(response_content)
-            if (
-                not isinstance(json_response, list)
-                or len(json_response) != 2
-                or not all(isinstance(cs, list) for cs in json_response)
-            ):
-                logger.warning(
-                    "LLM Crossover: Malformed or empty children_prompts list. Falling back."
-                )
-                raise ValueError("Malformed LLM crossover response")
+        finally:
+            self._mcp_context = previous_context
+            self.enable_llm_crossover = previous_crossover
 
-            child1: List[Dict[str, str]] = json_response[0]
-            child2: List[Dict[str, str]] = json_response[1]
+        finalize_mcp_result(result, context, panel_style)
+        return result
 
-            logger.debug(
-                f"LLM Crossover generated child1: {json.dumps(child1)[:50]}... Child2: {json.dumps(child2)[:50]}..."
-            )
-            return creator.Individual(child1), creator.Individual(child2)
-
-        except Exception as e:
-            logger.warning(
-                f"LLM-driven crossover failed: {e}. Falling back to standard crossover."
-            )
-            return self._deap_crossover(ind1, ind2)
+    # Evaluation is provided by EvaluationOps
 
-    def _get_task_description_for_llm(self, prompt: chat_prompt.ChatPrompt) -> str:
-        """Generates a concise task description for use in LLM prompts for fresh generation or radical innovation."""
-        description = "Task: Given a list of AI messages with placeholder values, generate an effective prompt. "
-        description += f"The original high-level instruction being optimized is: '{prompt.get_messages()}'. "
-        description += "The goal is to create an effective prompt that guides a language model to perform this task well."
-        return description
+    # LLM crossover is provided by CrossoverOps
+    # Helper provided by Helpers
 
+    # Override prompt builders to centralize strings in prompts.py
     def _get_reasoning_system_prompt_for_variation(self) -> str:
-        return f"""You are an expert prompt engineer specializing in creating diverse and effective prompts. Given an initial prompt, your task is to generate a diverse set of alternative prompts.
-
-For each prompt variation, consider:
-1. Different levels of specificity and detail, including significantly more detailed and longer versions.
-2. Various ways to structure the instruction, exploring more complex sentence structures and phrasings.
-3. Alternative phrasings that maintain the core intent but vary in style and complexity.
-4. Different emphasis on key components, potentially elaborating on them.
-5. Various ways to express constraints or requirements.
-6. Different approaches to clarity and conciseness, but also explore more verbose and explanatory styles.
-7. Alternative ways to guide the model's response format.
-8. Consider variations that are substantially longer and more descriptive than the original.
-
-The generated prompts should guide a target LLM to produce outputs in the following style: '{self.output_style_guidance}'
-
-Return a JSON array of prompts with the following structure:
-{{
-    "prompts": [
-        {{
-            "prompt": "alternative prompt 1",
-            "strategy": "brief description of the variation strategy used, e.g., 'focused on eliciting specific output style'"
-        }},
-        {{
-            "prompt": "alternative prompt 2",
-            "strategy": "brief description of the variation strategy used"
-        }}
-    ]
-}}
-Each prompt variation should aim to get the target LLM to produce answers matching the desired style: '{self.output_style_guidance}'.
-"""
+        return evo_prompts.variation_system_prompt(self.output_style_guidance)
 
     def get_llm_crossover_system_prompt(self) -> str:
-        return f"""You are an expert prompt engineer specializing in creating novel prompts by intelligently blending existing ones.
-Given two parent prompts, your task is to generate one or two new child prompts that effectively combine the strengths, styles, or core ideas of both parents.
-The children should be coherent and aim to explore a potentially more effective region of the prompt design space, with a key goal of eliciting responses from the target language model in the following style: '{self.output_style_guidance}'.
-
-Consider the following when generating children:
-- Identify the key instructions, constraints, and desired output formats in each parent, paying attention to any hints about desired output style.
-- Explore ways to merge these elements such that the resulting prompt strongly guides the target LLM towards the desired output style.
-- You can create a child that is a direct blend, or one that takes a primary structure from one parent and incorporates specific elements from the other, always optimizing for clear instruction towards the desired output style.
-- If generating two children, try to make them distinct from each other and from the parents, perhaps by emphasizing different aspects of the parental combination that could lead to the desired output style.
-
-All generated prompts must aim for eliciting answers in the style: '{self.output_style_guidance}'.
-
-Return a JSON object that is a list of both child prompts. Each child prompt is a list of LLM messages. Example:
-[
-    [{{"role": "<role>", "content": "<content>"}},{{"role": "<role>", "content": "<content>"}}],
-    [{{"role": "<role>", "content": "<content>"}},{{"role": "<role>", "content": "<content>"}}]
-]
-
-
-"""
+        return evo_prompts.llm_crossover_system_prompt(self.output_style_guidance)
 
     def _get_radical_innovation_system_prompt(self) -> str:
-        return f"""You are an expert prompt engineer and a creative problem solver.
-Given a task description and an existing prompt for that task (which might be underperforming), your goal is to generate a new, significantly improved, and potentially very different prompt.
-Do not just make minor edits. Think about alternative approaches, structures, and phrasings that could lead to better performance.
-Consider clarity, specificity, constraints, and how to best guide the language model for the described task TO PRODUCE OUTPUTS IN THE FOLLOWING STYLE: '{self.output_style_guidance}'.
-Return only the new prompt string, with no preamble or explanation.
-"""
-
-    def _infer_output_style_from_dataset(
-        self, dataset: opik.Dataset, prompt: chat_prompt.ChatPrompt, n_examples: int = 5
-    ) -> Optional[str]:
-        """Analyzes dataset examples to infer the desired output style."""
-        with reporting.infer_output_style(
-            verbose=self.verbose
-        ) as report_infer_output_style:
-            report_infer_output_style.start_style_inference()
-
-            try:
-                items_to_process = dataset.get_items(n_examples)
-            except Exception as e:
-                report_infer_output_style.error(
-                    f"Failed to get items from dataset '{dataset.name}': {e}"
-                )
-                return None
-
-            if not items_to_process:
-                report_infer_output_style.error(
-                    f"Dataset '{dataset.name}' is empty. Cannot infer output style."
-                )
-                return None
-
-            # Need at least a couple of examples for meaningful inference
-            if len(items_to_process) < min(n_examples, 2):
-                report_infer_output_style.error(
-                    f"Not enough dataset items (found {len(items_to_process)}) to reliably infer output style. Need at least {min(n_examples,2)}."
-                )
-                return None
-
-            examples_str = ""
-            for i, item_content in enumerate(items_to_process):
-                filtered_content = {x: y for x, y in item_content.items() if x != "id"}
-                examples_str += (
-                    f"Example {i+1}:\nDataset Item:\n{filtered_content}\n---\n"
-                )
-
-            user_prompt_for_style_inference = f"""Please analyze the following examples from a dataset and provide a concise, actionable description of the REQUIRED output style for the target LLM. Before describing the output style, make sure to understand the dataset content and structure as it can include input, output and metadata fields. This description will be used to guide other LLMs in generating and refining prompts.
-
-    {examples_str}
-
-    Based on these examples, what is the desired output style description?
-    Remember to focus on aspects like length, tone, structure, content details, and any recurring keywords or phrasing patterns in the outputs.
-    The description should be a single string that can be directly used as an instruction for another LLM.
-    Return ONLY this descriptive string.
-    """
-            # report_infer_output_style.display_style_inference_prompt(user_prompt_for_style_inference)
-
-            try:
-                inferred_style = self._call_model(
-                    messages=[
-                        {"role": "system", "content": self._INFER_STYLE_SYSTEM_PROMPT},
-                        {"role": "user", "content": user_prompt_for_style_inference},
-                    ],
-                    is_reasoning=True,
-                )
-                inferred_style = inferred_style.strip()
-                if inferred_style:
-                    report_infer_output_style.success(inferred_style)
-                    return inferred_style
-                else:
-                    report_infer_output_style.error(
-                        "LLM returned empty string for inferred output style."
-                    )
-                    return None
-            except Exception as e:
-                report_infer_output_style.error(
-                    f"Error during output style inference: {e}"
-                )
-                return None
+        return evo_prompts.radical_innovation_system_prompt(self.output_style_guidance)