Core components¶

Galapagos describes its fourteen bundled runnable scaffolds with six component roles over one unit, the Genome. The roles are a common vocabulary for comparing implementations; a scaffold controller may still coordinate them differently. In particular, claude_code and codex delegate a whole run to one CLI session, while meta_harness drains a batch of candidates from one proposer round.

Memory — optional cross-candidate knowledge: reports, tactics, scratchpads

read ↓↑ write

Populationthe store

→

SelectionPolicychooses context

→

PromptBuilderrenders input

→

Proposercreates candidates

→

Evaluatorthe task scores

← admitted, scored Genomes return to the Population

The task supplies the Evaluator. The scaffold supplies the other five roles. A pairing is runnable when the task has a seed and evaluator and the selected scaffold, candidate language, dependencies, hardware, and execution mode are compatible.

Genome — the unit passed between components¶

Field	Purpose
`content`	The candidate artifact, normally source code or text.
`scores`	Metrics returned by the task Evaluator. `combined_score` is the primary fitness when present.
`parent_id` / `lineage`	Ancestry used for selection, tracing, and migration.
`metadata`	Per-candidate state such as island, generation, feature coordinates, or strategy id.
`artifacts`	Non-inherited evidence such as model responses, evaluator feedback, and tracebacks.

See Genome for the full record contract.

1. Population¶

The Population stores candidates and owns admission. Its public interface is add, query, all, and best.

Across every registered scaffold, EvalResult.valid == false is a framework-level rejection: the candidate remains fully represented in evolutionary_trajectory.jsonl, but it is excluded from the Population, best, recent-admitted prompt context, and successful-candidate policy observation. Methods may still spend an attempt/refinement counter on the rejection. Score alone does not determine validity, so an evaluator-valid candidate with combined_score: 0 remains eligible.

Bundled scaffold	Population behavior
`openevolve`	Island-model MAP-Elites archive plus a bounded global archive and ring migration.
`adaevolve`	Quality-diversity archipelago with adaptive island spawning and migration.
`evox`	Candidate store augmented with active evolved-strategy state and improvement statistics.
`ale_agent`	Keep-all best-first archive with explicit frontier and tabu-expanded state.
`algotune_agent`	Keep every evaluator-valid measured workspace and expose the best speedup snapshot as the winner.
`beam_search`	Fixed-width beam pruned by fitness and optional diversity.
`topk`, `best_of_n`, `best_of_n_attempts`, `random`, `claude_code`, `codex`	Keep-all or capacity-bounded in-memory archive.
`meta_harness`	Append-only archive with a scalar best set by default or an explicit score/cost Pareto frontier.

The public general-purpose implementations are InMemoryPopulation and IslandPopulation. Method-specific implementations live beside their scaffold controllers.

2. SelectionPolicy¶

The SelectionPolicy chooses parents and inspirations and may observe results. Stateful policies expose state_dict() / load_state_dict() for scaffolds that support checkpoint resume.

Bundled scaffold	Selection behavior
`openevolve`	Round-robin islands with random, fitness-weighted exploit, and archive sampling.
`adaevolve`	Adaptive exploration intensity plus UCB island allocation.
`evox`	Executes the active LLM-generated strategy, with a safe fallback if it fails.
`ale_agent`	Expands the best unexpanded frontier state once, scheduling K sibling branches with T refinement turns each.
`algotune_agent`	Continues from the mutable working workspace independently of the best snapshot; `revert` restores that snapshot.
`topk`	Expands the global best and supplies the next K programs as context.
`best_of_n`	Holds a parent until N valid children, then returns to the global best.
`best_of_n_attempts`	Rotates after N attempts, including invalid or failed attempts.
`beam_search`	Chooses within the current beam by the configured beam strategy.
`random`	Samples the parent uniformly from the full history and distinct inspirations from the remaining candidates.
`claude_code`	Delegates search decisions to the single CLI agent session.
`codex`	Delegates search decisions to the single Codex CLI agent session.
`meta_harness`	Returns a nominal frontier anchor; the proposer chooses what to inspect and create.

The public general-purpose policies are ExploreExploitPolicy, UCBBanditPolicy, and IdentityPolicy.

3. PromptBuilder¶

The PromptBuilder turns the task context, selection, Memory, and prior evaluator evidence into a Prompt(system, user).

The bundled implementations include the generic DefaultPromptBuilder, OpenEvolve's history and inspiration template, AdaEvolve's tactic-aware template, EvoX's operator-labelled template, ALE-Agent's algorithm-engineering state plus sampled domain guidance, AlgoTune Agent's command and tool transcript, the one-shot TASK.md brief used by claude_code and codex, and Meta-Harness's skill-steered filesystem or serialized archive view.

PromptBuilder formats context; it does not score candidates. Method-specific selection remains in the policy or, for delegated agent scaffolds, in the proposer.

4. Proposer¶

The Proposer creates candidate content. LLMProposer supports registered mutation approaches, including diff_based_edit and full_rewrite; DiffProposer remains a compatibility alias. CrossoverProposer adds crossover and token-Jaccard novelty rejection.

Bundled method-specific proposer behavior includes:

openevolve: whole-line SEARCH/REPLACE edits matching OpenEvolve's mutation protocol.
adaevolve, evox, and the search baselines: LLM mutation with their scaffold-specific prompts and retry settings.
ale_agent: a strategy-only model call at the start of each branch, followed by T full-rewrite implementation/refinement calls; Galapagos schedules the paper's K sibling branches sequentially.
algotune_agent: parses and executes one workspace command per turn (edit, delete, inspection, reference/evaluation, profiling, or revert) and evaluates only commands that change the candidate.
claude_code: one subscription-billed Claude Code CLI session edits the solution and invokes the task evaluator.
codex: one ChatGPT-authenticated Codex CLI session edits the solution and invokes the task evaluator; Galapagos independently scores each observed checkpoint.
meta_harness: one proposer round emits k siblings. The default is a skill-steered Claude Code session browsing meta_harness_D; proposer.mode=llm uses one API-model call over a serialized archive view instead.

5. Evaluator¶

The task owns its evaluator. SubprocessEvaluator executes it on the host for general.eval_mode=local; ContainerEvaluator executes it in the task's Docker image for the default docker mode. The same task evaluator source is selected in both modes, but dependency, hardware, and isolation guarantees differ.

The standard evaluator lifecycle has one required and one optional entrypoint:

evaluate(program_path) scores every search candidate and supplies selection feedback.
evaluate_final(program_path), when present in the same trusted source file, runs exactly once after the winner is frozen. Its metrics become the public score of record and never return to the search loop. Galapagos detects this hook from source; task cards do not register a second evaluator component.

For the minimal task-author contract and example, see Optional: final evaluation after search.

An evaluator returns an EvalResult containing numeric scores plus optional feedback, traceback, and artifacts. It must recompute the objective from candidate output rather than accept a self-reported score.

6. Memory¶

Memory holds free-form knowledge that is not naturally per-candidate metadata.

Bundled scaffold	Memory behavior
`adaevolve`	Generates and rotates breakthrough tactics after stagnation.
`evox`	Records generated strategies and their measured improvement.
`ale_agent`	Keeps a bounded branch/turn outcome summary; history injection is an ablation switch and is off in the paper's full-method preset.
`algotune_agent`	Keeps a bounded, role-preserving command transcript with evaluator and tool feedback.
`meta_harness`	Persists the evolution summary and bounded candidate reports in archive `D`.
Other bundled scaffolds	`NullMemory` / no method-specific memory.

The public general-purpose implementations are NullMemory and ScratchpadMemory.

Bundled scaffold coverage¶

This matrix is deliberately limited to scaffold controllers that are present and registered in the current package.

Scaffold	Population	Selection	Prompt	Proposer	Evaluator	Memory
`openevolve`	✓	✓	✓	✓	task	—
`adaevolve`	✓	✓	✓	✓	task	✓
`evox`	✓	✓	✓	✓	task	✓
`ale_agent`	✓	✓	✓	✓	task	✓
`algotune_agent`	✓	✓	✓	command agent	task	✓
`beam_search`	✓	✓	✓	✓	task	—
`best_of_n`	✓	✓	✓	✓	task	—
`best_of_n_attempts`	✓	✓	✓	✓	task	—
`topk`	✓	✓	✓	✓	task	—
`random`	✓	✓	✓	✓	task	—
`claude_code`	✓	delegated	✓	CLI agent	task	—
`codex`	✓	delegated	✓	CLI agent	task	—
`meta_harness`	✓	delegated	✓	coding agent or LLM	task	✓

Public imports¶

from galapagos.components import (
    Population, InMemoryPopulation, IslandPopulation,
    SelectionPolicy, ExploreExploitPolicy, UCBBanditPolicy, IdentityPolicy,
    PromptBuilder, DefaultPromptBuilder,
    Proposer, LLMProposer, DiffProposer, CrossoverProposer,
    Evaluator, SubprocessEvaluator, ContainerEvaluator,
    Memory, NullMemory, ScratchpadMemory,
)

For tunable keys used by the bundled implementations, see Scaffold configs.