Alpha Evolve

Alpha-Evolve

Reference (read if you need the algorithm's details): AlphaEvolve — https://arxiv.org/abs/2506.13131 · OpenEvolve (open-source impl) — https://github.com/algorithmicsuperintelligence/openevolve

A population-based evolutionary loop over a program. The artifact is the editable model code; a child is one analysis-informed SEARCH/REPLACE diff to a parent, and the feedback signal is a cascade-evaluated training run (<metric>, smoke→full). Children are placed in a MAP-Elites archive across islands (complexity × diversity axes), so a child survives by being either better or more novel, not just better. The discipline this enforces: diversity is preserved, not collapsed — diverse high performers co-exist instead of one local optimum winning. You are the controller: sample a parent + inspirations, spawn parallel Mutators to propose and evaluate children, place them, migrate between islands, checkpoint. Loops to a fixed compute budget or until interrupted.

When to use

Use this for parallel, diversity-preserving search over a model/program where many variants explore at once and the archive keeps the illuminated frontier. Default to broad island coverage; if quality stalls, bias selection toward exploiting top elites; if coverage stalls, bias toward empty cells. Not for the sequential autoresearch loops (one change at a time), and not for fixing a known anomaly.

The cast (both in this folder): roles/Mutator.md produces + cascade-evaluates one child (the generation step); schemas/result.schema.json is the result a Mutator returns.

Setup

Resolve bindings interactively. If loop.run.yaml exists in the working dir, load it, confirm the values in one line, and skip to the loop. Otherwise: on Claude Code (the AskUserQuestion tool is available, <host> = claude-code) infer a likely value for each binding and present it as the recommended option; on other hosts (<host> = other) ask each as a quoted plain-text prompt. Then write loop.run.yaml (format: examples/run.example.yaml) and confirm the values before creating any other files. <host> also decides execution: Claude Code spawns real Agent Mutators in parallel (capped at <concurrency>); other hosts degrade to running a generation's children serially (identical algorithm).

Probe the box first (mandatory — measure, never assume <concurrency>). Record and report:

• CPU cores → <cores>: python3 -c "import os; print(os.cpu_count())".
• RAM → <ram_gb>: macOS sysctl -n hw.memsize; Linux grep MemTotal /proc/meminfo.
• Accelerator → <accelerator>/<vram>/<gpu_count>: nvidia-smi --query-gpu=name,memory.total,count --format=csv (NVIDIA); else macOS Apple GPU/MPS; else CPU-only.

num_generations is derived: ceil(<total_budget> / <concurrency>). The cascade is derived from <budget> (not asked): smoke = ~1 epoch / a small subset, full = <budget>, gate = child's smoke <metric> ≥ parent's smoke. <budget>/<metric>/eval split are FIXED — never mutation targets (a child may not "train longer" to look better); changing them means re-running the whole loop.

Advanced (opt-in). Ask one yes/no: "Use defaults for the evolutionary settings, or customize?" Defaults are faithful to AlphaEvolve/OpenEvolve — use them and ask nothing more. Only on "customize" ask for each (showing the default as recommended): num_islands (4), num_top (3), num_diverse (2), num_bins (10), migration_interval (5), diversity_reference_size (10), pop_per_island (40), seed (42). Axes are fixed: complexity × diversity. See examples/run.example.yaml for the shape.

Print the resolved bindings + the probe + derived num_generations, and do not create files or launch until the user confirms. Then initialise the sandbox (header rows only; programs/ is created as children are evaluated):

<sandbox_root>/lae/
├── archive.tsv     ← current elites = program database + checkpoint
├── history.tsv     ← append-only record of every child
├── leaderboard.md  ← rendered UI
└── programs/       ← one self-contained dir per program

The controller (loop)

You maintain num_islands MAP-Elites maps in archive.tsv, the append-only history.tsv, running per-axis percentile stats, and leaderboard.md. You are the sole writer of all shared logs — Mutators only return results, so there are no write races. Copy this checklist and tick items off:

• Setup done: probe recorded, bindings confirmed, sandbox initialised, num_generations derived.
• GEN 0 — in each island, create the baseline program (a copy of <editable_files>) + optionally a few stochastic variants; cascade-evaluate; place in the archive.
• Per generation: build EXACTLY <concurrency> tasks (round-robin island, seeded-rule parent, top num_top + num_diverse most-diverse inspirations); make each child dir by copying the parent program + harness.
• Run the C Mutators (spawn-or-degrade), each with roles/Mutator.md, parent code, inspirations, parent artifacts, its child dir, and the smoke/full budgets.
• For each returned child: append a history.tsv row; if evaluated, compute its niche → cell and place it in the island map iff <metric> is better (kept=y); record smoke_dropped/crash without placing.
• Re-render leaderboard.md; checkpoint (archive.tsv is the checkpoint); print a status line.
• Every migration_interval generations: ring-migrate top elites island k → k+1.
• Stop at <total_budget> (reserve a little for synthesis), then synthesize the final report.

Niche computation (you do this, from a child's sandbox):

• complexity = trainable param count (fallback: total LOC of the editable files + any files the child added), log10-scaled.
• diversity = average normalized edit distance of the program's concatenated code (editable + added files) to a random sample of diversity_reference_size programs from its island (vs the baseline if the island is near-empty). Higher = more novel.
• Normalize each axis with running ~5th/95th percentiles (not raw min/max, so one outlier can't collapse the range): scaled = clamp01((v − p5)/(p95 − p5)); bin = min(num_bins−1, int(scaled × num_bins)); cell = (complexity_bin, diversity_bin). Re-bin existing elites when a percentile shifts enough to move an edge (keep the higher <metric> on collisions; the archive is small).