clarify prompt design

Author: codelion

README.md

@@ -337,6 +337,40 @@ Sample configuration files are available in the `configs/` directory:
 - `default_config.yaml`: Comprehensive configuration with all available options
 - `island_config_example.yaml`: Advanced island-based evolution setup
 
+### Prompt Engineering Design
+
+OpenEvolve uses a sophisticated prompt engineering approach that separates different types of program examples to optimize LLM learning:
+
+#### Program Selection Strategy
+
+The system distinguishes between three types of program examples shown to the LLM:
+
+1. **Previous Attempts** (`num_top_programs`): Shows only the best performing programs to demonstrate high-quality approaches
+   - Used for the "Previous Attempts" section in prompts
+   - Focused on proven successful patterns
+   - Helps LLM understand what constitutes good performance
+
+2. **Top Programs** (`num_top_programs + num_diverse_programs`): Broader selection including both top performers and diverse approaches
+   - Used for the "Top Performing Programs" section
+   - Includes diverse programs to prevent local optima
+   - Balances exploitation of known good solutions with exploration of novel approaches
+
+3. **Inspirations** (`num_top_programs`): Cross-island program samples for creative inspiration
+   - Derived from other evolution islands to maintain diversity
+   - Count automatically configures based on `num_top_programs` setting
+   - Prevents convergence by exposing LLM to different evolutionary trajectories
+
+#### Design Rationale
+
+This separation is intentional and serves multiple purposes:
+
+- **Focused Learning**: Previous attempts show only the best patterns, helping LLM understand quality standards
+- **Diversity Maintenance**: Top programs include diverse solutions to encourage exploration beyond local optima  
+- **Cross-Pollination**: Inspirations from other islands introduce novel approaches and prevent stagnation
+- **Configurable Balance**: Adjust `num_top_programs` and `num_diverse_programs` to control exploration vs exploitation
+
+The inspiration count automatically scales with `num_top_programs` to maintain consistency across different configuration sizes, eliminating the need for a separate configuration parameter.
+
 ### Template Customization
 
 OpenEvolve supports advanced prompt template customization to increase diversity in code evolution:

openevolve/database.py

@@ -304,18 +304,23 @@ def get(self, program_id: str) -> Optional[Program]:
         """
         return self.programs.get(program_id)
 
-    def sample(self) -> Tuple[Program, List[Program]]:
+    def sample(self, num_inspirations: Optional[int] = None) -> Tuple[Program, List[Program]]:
         """
         Sample a program and inspirations for the next evolution step
 
+        Args:
+            num_inspirations: Number of inspiration programs to sample (defaults to 5 for backward compatibility)
+
         Returns:
             Tuple of (parent_program, inspiration_programs)
         """
         # Select parent program
         parent = self._sample_parent()
 
         # Select inspirations
-        inspirations = self._sample_inspirations(parent, n=5)
+        if num_inspirations is None:
+            num_inspirations = 5  # Default for backward compatibility
+        inspirations = self._sample_inspirations(parent, n=num_inspirations)
 
         logger.debug(f"Sampled parent {parent.id} and {len(inspirations)} inspirations")
         return parent, inspirations

openevolve/iteration.py

@@ -48,7 +48,7 @@ async def run_iteration_with_shared_db(
 
     try:
         # Sample parent and inspirations from database
-        parent, inspirations = database.sample()
+        parent, inspirations = database.sample(num_inspirations=config.prompt.num_top_programs)
 
         # Get artifacts for the parent program if available
         parent_artifacts = database.get_artifacts(parent.id)

openevolve/process_parallel.py

@@ -153,18 +153,20 @@ def _run_iteration_worker(
         )
 
         # Use config values for limits instead of hardcoding
-        island_top_programs = island_programs[
+        # Programs for LLM display (includes both top and diverse for inspiration)
+        programs_for_prompt = island_programs[
             : _worker_config.prompt.num_top_programs + _worker_config.prompt.num_diverse_programs
         ]
-        island_previous_programs = island_programs[: _worker_config.prompt.num_top_programs]
+        # Best programs only (for previous attempts section, focused on top performers)
+        best_programs_only = island_programs[: _worker_config.prompt.num_top_programs]
 
         # Build prompt
         prompt = _worker_prompt_sampler.build_prompt(
             current_program=parent.code,
             parent_program=parent.code,
             program_metrics=parent.metrics,
-            previous_programs=[p.to_dict() for p in island_previous_programs],
-            top_programs=[p.to_dict() for p in island_top_programs],
+            previous_programs=[p.to_dict() for p in best_programs_only],
+            top_programs=[p.to_dict() for p in programs_for_prompt],
             inspirations=[p.to_dict() for p in inspirations],
             language=_worker_config.language,
             evolution_round=iteration,
@@ -589,7 +591,7 @@ def _submit_iteration(self, iteration: int, island_id: Optional[int] = None) ->
 
             try:
                 # Sample parent and inspirations from the target island
-                parent, inspirations = self.database.sample()
+                parent, inspirations = self.database.sample(num_inspirations=_worker_config.prompt.num_top_programs)
             finally:
                 # Always restore original island state
                 self.database.current_island = original_island