add history-aware self-hosting search

Author: Darreckk

README.md

@@ -215,6 +215,40 @@ OpenEvolve implements a sophisticated **evolutionary coding pipeline** that goes
 - **Adaptive Feature Dimensions**: Custom quality-diversity metrics
 - **Migration Patterns**: Ring topology with controlled gene flow
 - **Multi-Strategy Sampling**: Elite, diverse, and exploratory selection
+- **Evaluator-Defined Identity**: Set `program_identity_artifact` to reject
+  structurally duplicate measured children across the complete run history
+- **Measured-Phenotype Identity**: Set `phenotype_identity_artifact` to reject
+  structurally different children whose complete measured behavior is already
+  present
+- **Observed-Result Allocation**: Optional `database.controller_scheduler`
+  routes new calls using a domain-selected `score_metric`, validity, diversity,
+  rejection rate, exploration, and token efficiency. Set `diversity_artifact`
+  to count evaluator-defined niches, and reserve at least one island so live
+  parallel scheduling retains a real allocation choice. Optionally set
+  `adaptive_parallelism` below the worker count to use fast balanced warmup
+  followed by a fresher-context quality phase. Set it to `1` when complete
+  archive freshness matters more than late-stage throughput. The allocator
+  reads retained seed and migrated-program scores as well as child results.
+  Set `leader_score_band` to keep post-warmup calls within an absolute score
+  distance of the best retained population. Set `parent_score_band` to keep
+  post-warmup parents within a score distance of the selected population's
+  retained leader
+- **Compact Measured-History Context**: Set
+  `prompt.archive_context_artifact` to show the proposal model a deterministic,
+  bounded inventory of one evaluator-defined artifact from measured programs.
+  The append-only values survive MAP-Elites displacement and checkpoint resume
+- **Filtered Proposal Neighborhoods**: Set
+  `prompt.proposal_neighborhood_artifact` when an evaluator can enumerate
+  valid parent-local options. The controller removes identities measured
+  anywhere in the complete persisted history, including behaviorally rejected
+  or displaced programs, and renders the bounded remainder as
+  `proposal-options.json` without embedding domain rules in OpenEvolve
+- **Prompt Artifact Selection**: Set ordered
+  `prompt.artifact_include_names` to keep complete evaluator receipts in the
+  archive while rendering only task-relevant artifacts to the proposal model
+- **Auditable Rejections**: Usage receipts distinguish measured candidates
+  from archive admission and record the selected parent plus a provider-response
+  digest without duplicating full prompt content
 
 </details>
 
@@ -859,14 +893,20 @@ Just set the `api_base` in your config to point to your endpoint.
 
 **Multiple success metrics:**
 
-1. **Primary Metric**: Your evaluator's `combined_score` or metric average
+1. **Primary Metric**: `selection_score` when supplied, then `combined_score`
 2. **Convergence**: Best score improvement over time
 3. **Diversity**: MAP-Elites grid coverage
 4. **Efficiency**: Iterations to reach target performance
 5. **Robustness**: Performance across different test cases
 
 **Use the visualizer** to track all metrics in real-time and identify when evolution has converged.
 
+For exact scientific searches, an evaluator can additionally return
+`selection_eligible`. A value at or below zero retains the attempt in lineage
+records but excludes it from parent selection, MAP-Elites cells, and the elite
+archive. This separates non-negotiable admission checks from the
+multi-objective quality score while preserving older evaluator behavior.
+
 </details>
 
 ### **Contributors**

openevolve/api.py

@@ -175,7 +175,9 @@ async def _run_evolution_async(
             best_code = best_program.code
             metrics = best_program.metrics or {}
 
-            if "combined_score" in metrics:
+            if "selection_score" in metrics:
+                best_score = metrics["selection_score"]
+            elif "combined_score" in metrics:
                 best_score = metrics["combined_score"]
             elif metrics:
                 numeric_metrics = [v for v in metrics.values() if isinstance(v, (int, float))]

openevolve/cli.py

@@ -4,9 +4,11 @@
 
 import argparse
 import asyncio
+import json
 import logging
 import os
 import sys
+from pathlib import Path
 from typing import Dict, List, Optional
 
 from openevolve import OpenEvolve
@@ -25,6 +27,16 @@ def parse_args() -> argparse.Namespace:
         "evaluation_file", help="Path to the evaluation file containing an 'evaluate' function"
     )
 
+    parser.add_argument(
+        "--seed-program",
+        action="append",
+        default=[],
+        help=(
+            "Additional evaluated starting parent. Repeat the option to seed "
+            "multiple islands while retaining initial_program as the incumbent."
+        ),
+    )
+
     parser.add_argument("--config", "-c", help="Path to configuration file (YAML)", default=None)
 
     parser.add_argument("--output", "-o", help="Output directory for results", default=None)
@@ -77,6 +89,10 @@ async def main_async() -> int:
     if not os.path.exists(args.evaluation_file):
         print(f"Error: Evaluation file '{args.evaluation_file}' not found")
         return 1
+    missing_seeds = [path for path in args.seed_program if not os.path.exists(path)]
+    if missing_seeds:
+        print(f"Error: Seed program file not found: '{missing_seeds[0]}'")
+        return 1
 
     # Load base config from file or defaults
     config = load_config(args.config)
@@ -110,6 +126,7 @@ async def main_async() -> int:
             evaluation_file=args.evaluation_file,
             config=config,
             output_dir=args.output,
+            seed_program_paths=args.seed_program,
         )
 
         # Load from checkpoint if specified
@@ -161,6 +178,25 @@ async def main_async() -> int:
             print(f"\nLatest checkpoint saved at: {latest_checkpoint}")
             print(f"To resume, use: --checkpoint {latest_checkpoint}")
 
+        summary = {
+            "schema_version": 1,
+            "record_type": "openevolve_run_summary",
+            "completion_reason": openevolve.completion_reason,
+            "last_completed_iteration": openevolve.last_completed_iteration,
+            "completed_iteration_count": openevolve.completed_iteration_count,
+            "latest_checkpoint": latest_checkpoint,
+            "best_program_id": best_program.id,
+            "best_program_metrics": best_program.metrics,
+            "llm_usage": openevolve.llm_usage,
+        }
+        summary_path = Path(openevolve.output_dir) / "run-summary.json"
+        temporary = summary_path.with_name(f".{summary_path.name}.tmp")
+        temporary.write_text(
+            json.dumps(summary, indent=2, sort_keys=True) + "\n",
+            encoding="utf-8",
+        )
+        temporary.replace(summary_path)
+
         return 0
 
     except Exception as e:

openevolve/config.py

@@ -282,6 +282,19 @@ class PromptConfig:
     include_artifacts: bool = True
     max_artifact_bytes: int = 20 * 1024  # 20KB in prompt
     artifact_security_filter: bool = True
+    # Optional ordered subset of evaluator artifacts rendered in prompts.
+    # Stored artifacts remain complete.
+    artifact_include_names: Optional[List[str]] = None
+    # Optional evaluator artifact collected across the complete live archive
+    # and rendered as one compact deterministic prompt artifact.
+    archive_context_artifact: Optional[str] = None
+    archive_context_max_items: int = 64
+    # Optional evaluator-produced neighborhood. The artifact must be schema
+    # version 1 JSON with an identity_artifact name and ordered options carrying
+    # identity fields. The controller removes identities already retained in the
+    # live archive and renders the remainder as proposal-options.json.
+    proposal_neighborhood_artifact: Optional[str] = None
+    proposal_options_max_items: int = 32
 
     # Feature extraction and program labeling
     suggest_simplification_after_chars: Optional[int] = (
@@ -312,13 +325,33 @@ class ControllerSchedulerConfig:
     """Optional observed-result island allocator for bounded live comparisons."""
 
     enabled: bool = False
+    score_metric: str = "combined_score"
+    # Optional evaluator artifact used to count distinct measured phenotypes.
+    # When absent, source-code hashes preserve the legacy definition.
+    diversity_artifact: Optional[str] = None
     exploitation_weight: float = 0.0
     underexplored_weight: float = 0.0
     validity_weight: float = 0.0
     diversity_weight: float = 0.0
     token_efficiency_weight: float = 0.0
     rejection_penalty: float = 0.0
     minimum_calls: int = 1
+    # Optional post-warmup quality band. When set, allocate only among islands
+    # whose retained best score is within this absolute distance of the global
+    # retained leader. None preserves unrestricted legacy allocation.
+    leader_score_band: Optional[float] = None
+    # Optional post-warmup parent band within the selected island. When set,
+    # parent sampling is limited to retained programs whose score is within
+    # this absolute distance of that island's retained leader.
+    parent_score_band: Optional[float] = None
+    # Keep this many islands outside the active worker frontier so a completed
+    # call leaves the allocator a real choice. This does not reduce concurrency
+    # when num_islands > parallel_evaluations.
+    reserve_islands: int = 1
+    # Optional lower in-flight limit after the balanced warmup proposal count
+    # has been submitted. This trades some throughput for fresher archive
+    # context during quality-focused adaptive search.
+    adaptive_parallelism: Optional[int] = None
 
 
 @dataclass
@@ -461,6 +494,14 @@ class Config:
     strict_diff_application: bool = False
     enforce_evolve_blocks: bool = False
     max_diff_blocks: int = 32
+    # Optional evaluator artifact whose exact value identifies the candidate's
+    # behaviorally meaningful contents. When configured, a child duplicating
+    # any program already known to the live archive is rejected.
+    program_identity_artifact: Optional[str] = None
+    # Optional second evaluator identity for exact measured behavior. This is
+    # checked only after evaluation, so structurally different programs that
+    # produce an already archived phenotype do not bloat parent selection.
+    phenotype_identity_artifact: Optional[str] = None
 
     # Early stopping settings
     early_stopping_patience: Optional[int] = None
@@ -544,9 +585,92 @@ def validate(self) -> None:
             )
         if self.max_diff_blocks < 1:
             raise ValueError("max_diff_blocks must be at least 1")
+        if self.prompt.archive_context_artifact is not None and (
+            not isinstance(self.prompt.archive_context_artifact, str)
+            or not self.prompt.archive_context_artifact.strip()
+        ):
+            raise ValueError(
+                "prompt.archive_context_artifact must be a non-empty string or None"
+            )
+        if self.prompt.proposal_neighborhood_artifact is not None and (
+            not isinstance(self.prompt.proposal_neighborhood_artifact, str)
+            or not self.prompt.proposal_neighborhood_artifact.strip()
+        ):
+            raise ValueError(
+                "prompt.proposal_neighborhood_artifact must be a non-empty "
+                "string or None"
+            )
+        artifact_names = self.prompt.artifact_include_names
+        if artifact_names is not None:
+            if not isinstance(artifact_names, list) or any(
+                not isinstance(name, str) or not name.strip()
+                for name in artifact_names
+            ):
+                raise ValueError(
+                    "prompt.artifact_include_names must be a list of non-empty strings or None"
+                )
+            if len(set(artifact_names)) != len(artifact_names):
+                raise ValueError(
+                    "prompt.artifact_include_names must not contain duplicates"
+                )
+            if (
+                self.prompt.archive_context_artifact is not None
+                and "archive-context.json" not in artifact_names
+            ):
+                raise ValueError(
+                    "prompt.artifact_include_names must include archive-context.json "
+                    "when archive_context_artifact is configured"
+                )
+            if (
+                self.prompt.proposal_neighborhood_artifact is not None
+                and "proposal-options.json" not in artifact_names
+            ):
+                raise ValueError(
+                    "prompt.artifact_include_names must include "
+                    "proposal-options.json when proposal_neighborhood_artifact "
+                    "is configured"
+                )
+        if (
+            isinstance(self.prompt.archive_context_max_items, bool)
+            or not isinstance(self.prompt.archive_context_max_items, int)
+            or self.prompt.archive_context_max_items < 1
+        ):
+            raise ValueError(
+                "prompt.archive_context_max_items must be a positive integer"
+            )
+        if (
+            isinstance(self.prompt.proposal_options_max_items, bool)
+            or not isinstance(self.prompt.proposal_options_max_items, int)
+            or self.prompt.proposal_options_max_items < 1
+        ):
+            raise ValueError(
+                "prompt.proposal_options_max_items must be a positive integer"
+            )
+        for field_name in (
+            "program_identity_artifact",
+            "phenotype_identity_artifact",
+        ):
+            value = getattr(self, field_name)
+            if value is not None and (
+                not isinstance(value, str) or not value.strip()
+            ):
+                raise ValueError(f"{field_name} must be a non-empty string or None")
         scheduler = self.database.controller_scheduler
         if not isinstance(scheduler.enabled, bool):
             raise ValueError("database.controller_scheduler.enabled must be boolean")
+        if not isinstance(scheduler.score_metric, str) or not scheduler.score_metric.strip():
+            raise ValueError(
+                "database.controller_scheduler.score_metric "
+                "must be a non-empty string"
+            )
+        if scheduler.diversity_artifact is not None and (
+            not isinstance(scheduler.diversity_artifact, str)
+            or not scheduler.diversity_artifact.strip()
+        ):
+            raise ValueError(
+                "database.controller_scheduler.diversity_artifact "
+                "must be a non-empty string or None"
+            )
         for field_name in (
             "exploitation_weight",
             "underexplored_weight",
@@ -566,6 +690,18 @@ def validate(self) -> None:
                     f"database.controller_scheduler.{field_name} "
                     "must be finite and nonnegative"
                 )
+        for field_name in ("leader_score_band", "parent_score_band"):
+            value = getattr(scheduler, field_name)
+            if value is not None and (
+                isinstance(value, bool)
+                or not isinstance(value, (int, float))
+                or not math.isfinite(float(value))
+                or float(value) < 0.0
+            ):
+                raise ValueError(
+                    f"database.controller_scheduler.{field_name} "
+                    "must be finite and nonnegative when provided"
+                )
         if (
             isinstance(scheduler.minimum_calls, bool)
             or not isinstance(scheduler.minimum_calls, int)
@@ -575,6 +711,36 @@ def validate(self) -> None:
                 "database.controller_scheduler.minimum_calls "
                 "must be a positive integer"
             )
+        if (
+            isinstance(scheduler.reserve_islands, bool)
+            or not isinstance(scheduler.reserve_islands, int)
+            or scheduler.reserve_islands < 0
+            or (
+                scheduler.enabled
+                and scheduler.reserve_islands >= self.database.num_islands
+            )
+        ):
+            raise ValueError(
+                "database.controller_scheduler.reserve_islands must be an integer "
+                "in [0, database.num_islands) when the scheduler is enabled"
+            )
+        if scheduler.adaptive_parallelism is not None and (
+            isinstance(scheduler.adaptive_parallelism, bool)
+            or not isinstance(scheduler.adaptive_parallelism, int)
+            or scheduler.adaptive_parallelism < 1
+            or scheduler.adaptive_parallelism
+            > self.evaluator.parallel_evaluations
+            or (
+                scheduler.enabled
+                and scheduler.adaptive_parallelism
+                > self.database.num_islands - scheduler.reserve_islands
+            )
+        ):
+            raise ValueError(
+                "database.controller_scheduler.adaptive_parallelism must be a "
+                "positive integer no greater than the evaluator worker count or "
+                "selectable island count"
+            )
 
     def to_dict(self) -> Dict[str, Any]:
         return asdict(self)