Skip to content

Commit 77b98de

Browse files
aktasbatuhanclaude
andauthored
Restructure README: emphasize compounding memory and adaptive features (#33)
* docs: surface flagship capabilities and tighten README narrative Lead with a 'What makes KaiEvolve different' section covering the features that previously had no README coverage, and add deep-dive sections for each: - Compounding memory: HMRD program summaries + the running literature review - Adaptive model selection via Thompson sampling over the LLM ensemble - Multi-file evolution across coordinated EVOLVE-BLOCK ids - Self-seeding runs with 'kai run --init-from' Trim filler bullets and the Key Features/How It Works duplication, soften the 'distributed' overclaim to process-based parallelism, and surface the kernelbench (GPU) and noisy_optimization (stochastic) examples that substantiate existing platform and noise-aware claims. * docs: add CLI + web viewer demo GIFs to the README - docs/viewer/viewer-demo.gif: walkthrough of the kai web viewer (overview -> run dashboard -> programs table -> approaches), captured from a live run. - docs/cli/cli-demo.gif: the `kai` CLI runs table. Embedded in the "Exploring runs" section. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> --------- Co-authored-by: Claude <noreply@anthropic.com>
1 parent 3224204 commit 77b98de

3 files changed

Lines changed: 197 additions & 73 deletions

File tree

‎README.md‎

Lines changed: 197 additions & 73 deletions
Original file line numberDiff line numberDiff line change
@@ -6,86 +6,86 @@ An open-source evolutionary coding agent that uses LLMs to discover and optimize
66

77
KaiEvolve is an evolutionary coding agent that uses Large Language Models to automatically optimize and discover algorithms through iterative improvement. Starting from the AlphaEvolve research, it incorporates advanced features for reproducibility, multi-language support, sophisticated evaluation pipelines, and integration with cutting-edge LLM optimization techniques. It serves as both a research platform for evolutionary AI and a practical tool for automated code optimization.
88

9-
### Key Features
10-
11-
KaiEvolve implements a comprehensive evolutionary coding system with:
12-
13-
- **Evolutionary Coding Agent**: LLM-guided evolution of entire code files (not just functions)
14-
- **Distributed Controller Loop**: Asynchronous pipeline coordinating LLMs, evaluators, and databases
15-
- **Program Database**: Storage and sampling of evolved programs with evaluation metrics
16-
- **Prompt Sampling**: Context-rich prompts with past programs, scores, and problem descriptions
17-
- **LLM Ensemble**: Multiple language models working together for code generation
18-
- **Multi-objective Optimization**: Simultaneous optimization of multiple evaluation metrics
19-
- **Checkpoint System**: Automatic saving and resuming of evolution state
20-
21-
#### Scientific Reproducibility
22-
- **Comprehensive Seeding**: Full deterministic reproduction with hash-based component isolation
23-
- **Default Reproducibility**: Seed=42 by default for immediate reproducible results
24-
- **Granular Control**: Per-component seeding for LLMs, database, and evaluation pipeline
25-
26-
#### Advanced LLM Integration
27-
- **Ensemble Sophistication**: Weighted model combinations with intelligent fallback strategies
28-
- **Test-Time Compute**: Integration with [optillm](https://github.com/codelion/optillm) for Mixture of Agents (MoA) and enhanced reasoning
29-
- **Universal API Support**: Works with any OpenAI-compatible endpoint (Anthropic, Google, local models)
30-
- **Plugin Ecosystem**: Support for optillm plugins (readurls, executecode, z3_solver, etc.)
31-
32-
#### Evolution Algorithm Innovations
33-
- **MAP-Elites Implementation**: Quality-diversity algorithm for balanced exploration/exploitation
34-
- **Island-Based Evolution**: Multiple populations with periodic migration for diversity maintenance
35-
- **Inspiration vs Performance**: Sophisticated prompt engineering separating top performers from diverse inspirations
36-
- **Multi-Strategy Selection**: Elite, diverse, and exploratory program sampling strategies
37-
- **Adaptive Feature Dimensions**: Default features (complexity & diversity) with customizable multi-dimensional search spaces
38-
39-
#### Evaluation and Feedback Systems
40-
- **Artifacts Side-Channel**: Capture build errors, profiling data, and execution feedback for LLM improvement
41-
- **Cascade Evaluation**: Multi-stage testing with progressive complexity for efficient resource usage
42-
- **LLM-Based Feedback**: Automated code quality assessment and reasoning capture
43-
- **Comprehensive Error Handling**: Graceful recovery from evaluation failures with detailed diagnostics
44-
45-
#### Multi-Language and Platform Support
46-
- **Language Agnostic**: Python, Rust, R, Metal shaders, and more
47-
- **Platform Optimization**: Apple Silicon GPU kernels, CUDA optimization, CPU-specific tuning
48-
- **Framework Integration**: MLX, PyTorch, scientific computing libraries
49-
50-
#### Developer Experience and Tooling
51-
- **`kai` CLI**: A guided terminal experience with a live `monitor`, one-shot `runs`/`show`/`best` tables, side-by-side `compare`, `export` to CSV/JSON, and live human `steer` (see [Exploring runs](#exploring-runs-the-kai-cli-and-web-viewer))
52-
- **Interactive web viewer**: `kai viewer` opens per-run dashboards, a sortable programs browser, an *approaches* synthesis of the strategies the AI tried, and **interactive solution visualizations** drawn by an optional per-task `visualize.py`
53-
- **Benchmarking harness**: A/B whole setups across tasks on a shared scale with reproducible seeds
54-
- **Error Recovery**: Robust checkpoint loading with automatic fix for common serialization issues
55-
56-
#### Performance and Scalability
57-
- **Process-Based Parallelism**: True parallel execution bypassing Python's GIL for CPU-bound tasks
58-
- **Resource Management**: Memory limits, timeouts, and resource monitoring
59-
- **Efficient Storage**: Optimized database with artifact management and cleanup policies
9+
### What makes KaiEvolve different
10+
11+
A faithful AlphaEvolve loop gets you mutation, evaluation, and a quality-diversity
12+
archive. KaiEvolve adds the machinery that makes *long* runs actually compound —
13+
the search remembers what it learned and steers itself instead of re-deriving the
14+
problem every iteration:
15+
16+
- **Compounding memory (HMRD + running literature review)** — every successful
17+
program carries a 4-section *Hypothesis / Method / Result / Discussion* summary.
18+
At each checkpoint, KaiEvolve distills only the *new* programs into a bounded
19+
"lab notebook" that is injected into every prompt and persists to disk, so the
20+
LLM builds on accumulated knowledge rather than a rotating window of neighbors —
21+
and a fresh run can pick up where the last one left off. See
22+
[Compounding memory](#compounding-memory-hmrd--literature-review).
23+
- **Adaptive model selection (Thompson sampling)** — hand the ensemble several
24+
models with default weights and a Beta–Bernoulli bandit learns which one to
25+
spend on from the rewards each earns, instead of a fixed split. See
26+
[Adaptive model selection](#adaptive-model-selection-thompson-sampling).
27+
- **Multi-file evolution** — coordinate `EVOLVE-BLOCK`s across a whole directory
28+
of files by shared block ID, not just a single program. See
29+
[Multi-file evolution](#multi-file-evolution).
30+
- **Self-seeding runs** — `kai run --init-from <run_dir>` starts a new run from a
31+
previous run's best program. See [Seeding a run](#seeding-a-run-from-a-previous-best).
32+
- **Human + automated steering** — redirect a live run with a markdown steering
33+
brief, or let an opt-in *research director* meta-agent write strategic
34+
directives. See [Watching and steering](#watching-and-steering-a-live-run).
35+
- **Noise-aware fitness** — for stochastic evaluators, re-evaluate and average so
36+
selection isn't fooled by a single lucky draw (see
37+
[`examples/noisy_optimization/`](examples/noisy_optimization/)).
38+
- **Two-phase warmup** — optional prompt optimization (pairwise feedback descent)
39+
and hyperparameter tuning before the main run (see
40+
[`configs/twophase_warmup.yaml`](configs/twophase_warmup.yaml)).
41+
42+
### Core capabilities
43+
44+
Underneath those, KaiEvolve is a complete evolutionary coding system:
45+
46+
- **Evolutionary coding agent**: LLM-guided evolution of whole code files, not just functions
47+
- **MAP-Elites + island-based evolution**: a quality-diversity archive across multiple
48+
populations with periodic migration, balancing exploration and exploitation
49+
- **Inspiration vs. performance prompting**: top performers and diverse inspirations are
50+
sampled separately, with multi-strategy (elite / diverse / exploratory) selection
51+
- **Adaptive feature dimensions**: default `complexity` & `diversity` axes, extensible to any
52+
metric your evaluator returns
53+
- **Cascade evaluation + artifacts side-channel**: multi-stage testing plus a feedback channel
54+
that hands build errors, tracebacks, and profiling data back to the LLM
55+
- **LLM ensemble over any OpenAI-compatible API**: OpenAI, Anthropic, Google, or local models,
56+
with [optillm](https://github.com/codelion/optillm) for test-time compute (MoA, reflection) and plugins
57+
- **Multi-objective optimization** with a `combined_score` convention for fitness
58+
- **Checkpoint / resume** of full evolution state, with robust loading
59+
- **Scientific reproducibility**: deterministic, per-component seeding (`seed=42` by default)
60+
- **Language agnostic**: Python, Rust, R, Metal shaders, and more
61+
- **Process-based parallelism**: true parallel evaluation past Python's GIL, with memory/timeout limits
62+
- **`kai` CLI + zero-build web viewer**: live monitoring, side-by-side comparison, CSV/JSON export,
63+
and interactive solution visualizations (see [Exploring runs](#exploring-runs-the-kai-cli-and-web-viewer))
6064

6165
## How It Works
6266

63-
KaiEvolve orchestrates a sophisticated evolutionary pipeline:
67+
Each iteration runs the same loop, in a fresh process working from a database snapshot:
6468

65-
### Core Evolution Loop
69+
1. **Prompt sampler** builds a context-rich prompt: top-performing programs (for
70+
optimization guidance), diverse inspirations (for creative exploration),
71+
execution artifacts and error feedback, the running [literature
72+
review](#compounding-memory-hmrd--literature-review), any active steering
73+
brief, and — via optillm plugins — dynamically fetched documentation.
6674

67-
1. **Enhanced Prompt Sampler**: Creates rich prompts containing:
68-
- Top-performing programs (for optimization guidance)
69-
- Diverse inspiration programs (for creative exploration)
70-
- Execution artifacts and error feedback
71-
- Dynamic documentation fetching (via optillm plugins)
75+
2. **LLM ensemble** generates the mutation. With default model weights, a
76+
[Thompson sampler](#adaptive-model-selection-thompson-sampling) picks which
77+
model to call from the rewards each has earned; with explicit weights it falls
78+
back to a fixed split. optillm adds test-time compute (MoA, reflection); model
79+
selection is deterministic under a fixed seed.
7280

73-
2. **Intelligent LLM Ensemble**:
74-
- Weighted model combinations for quality/speed tradeoffs
75-
- Test-time compute techniques (MoA, chain-of-thought, reflection)
76-
- Deterministic selection with comprehensive seeding
81+
3. **Evaluator pool** runs multi-stage cascade evaluation in parallel under
82+
memory/timeout limits, collecting artifacts and optional LLM-based quality
83+
feedback. Stochastic evaluators can re-evaluate and average for
84+
[noise-aware fitness](examples/noisy_optimization/).
7785

78-
3. **Advanced Evaluator Pool**:
79-
- Multi-stage cascade evaluation
80-
- Artifact collection for detailed feedback
81-
- LLM-based code quality assessment
82-
- Parallel execution with resource limits
83-
84-
4. **Sophisticated Program Database**:
85-
- MAP-Elites algorithm for quality-diversity balance
86-
- Island-based populations with migration
87-
- Feature map clustering and archive management
88-
- Comprehensive metadata and lineage tracking
86+
4. **Program database** maps the result into the MAP-Elites archive across
87+
islands, tracks lineage and metadata, and — at checkpoints — distills new
88+
programs' HMRD summaries into the literature review for the next iterations.
8989

9090
## Getting Started
9191

@@ -215,6 +215,26 @@ python kaievolve-run.py examples/circle_packing/initial_program.py \
215215
--iterations 50
216216
```
217217

218+
### Seeding a run from a previous best
219+
220+
Resuming continues an existing run's full state. To instead start a *fresh* run
221+
from where another one finished — a new config, a different model roster, or a
222+
clean archive seeded by the best solution so far — use `--init-from` with a run
223+
directory:
224+
225+
```bash
226+
kai run --init-from bench_results/<run>/run_0 \
227+
examples/circle_packing/evaluator.py \
228+
--config examples/circle_packing/config_phase_2.yaml \
229+
--iterations 100
230+
```
231+
232+
KaiEvolve locates that run's best program (`<run_dir>/best/best_program.py`, or
233+
the latest `checkpoints/checkpoint_*/best_program.py`) and uses it as the initial
234+
program — so you only need to pass the evaluator. This pairs naturally with the
235+
persistent [literature review](#compounding-memory-hmrd--literature-review): point
236+
both runs at the same review file and knowledge compounds across them.
237+
218238
### Comparing Results Across Checkpoints
219239

220240
Each checkpoint directory contains the best program found up to that point, making it easy to compare solutions over time:
@@ -267,6 +287,8 @@ Evolution produces a lot of programs; the `kai` command makes them legible. Run
267287
| `kai glossary` | Plain-language explanation of the terms |
268288
| `kai run` | Run KaiEvolve on your own code (the optimizer itself) |
269289

290+
![the kai CLI](docs/cli/cli-demo.gif)
291+
270292
> Point `kai` at your results with `--root` (or set `KAI_ROOT`); `--configs`
271293
> tells it where each setup's config lives.
272294

@@ -277,6 +299,8 @@ database and no build step. It gives an at-a-glance overview, a per-run dashboar
277299
and a click-to-inspect drawer that couples each step's reasoning, code diff, and
278300
the **solution it produced**.
279301

302+
![the kai web viewer: overview, run dashboard, programs table, and approaches synthesis](docs/viewer/viewer-demo.gif)
303+
280304
**Overview.** Every setup per task, ranked by score, with cost and a progress sparkline:
281305

282306
![overview](docs/viewer/overview.png)
@@ -534,6 +558,93 @@ export ENABLE_ARTIFACTS=false
534558
- **Rich debugging context** - Full stack traces and error messages guide improvements
535559
- **Zero overhead** - When disabled, no performance impact on evaluation
536560

561+
## Compounding memory: HMRD + literature review
562+
563+
A plain evolutionary loop is amnesiac: each prompt sees a handful of neighboring
564+
programs and re-derives the problem from scratch. KaiEvolve gives the search a
565+
memory in two layers.
566+
567+
**HMRD summaries.** Every successful program is asked to emit a tagged
568+
*Hypothesis / Method / Result / Discussion* prefix, which workers parse and attach
569+
to the program. This turns the population from a pile of code into a record of
570+
*what was tried and why it did or didn't work*. HMRD is on by default
571+
(`prompt.require_hmrd`) and also feeds the optional strategy clustering
572+
(`prompt.strategy_clustering_enabled`) and the *approaches* synthesis in the web
573+
viewer.
574+
575+
**Running literature review.** Opt in with `prompt.literature_review_enabled` and
576+
KaiEvolve maintains a bounded "lab notebook" distilled from those HMRD summaries.
577+
At each checkpoint it distills *only the programs added since the last checkpoint*
578+
and merges them into the review, then injects the review into every generation
579+
prompt. The cost stays flat regardless of population size, and because the review
580+
persists to a file it **compounds across runs** — a new run loads the accumulated
581+
notebook and builds on it.
582+
583+
```yaml
584+
prompt:
585+
require_hmrd: true # 4-section summaries (default on)
586+
literature_review_enabled: true # maintain + inject the running review
587+
literature_review_path: null # null => <output_dir>/literature_review.md;
588+
# set a stable path to accumulate across runs
589+
literature_review_max_chars: 4000 # bounded (~1000 tokens)
590+
literature_review_interval: null # distill every N iters; null => checkpoint_interval
591+
```
592+
593+
Set `literature_review_path` to a shared file and chain runs with
594+
[`--init-from`](#seeding-a-run-from-a-previous-best) to carry knowledge forward.
595+
596+
## Adaptive model selection (Thompson sampling)
597+
598+
Picking a single model per run is a bet; static ensemble weights are a fixed bet.
599+
KaiEvolve can instead *learn* the split. When you list more than one model and
600+
leave the weights at their default (`1.0`), the ensemble switches on a
601+
Beta–Bernoulli **Thompson sampler**: it round-robins until each model has a few
602+
samples, then routes each call to the model whose recent reward distribution looks
603+
most promising — automatically shifting spend toward whatever is actually working
604+
on *this* task. Set explicit weights to opt out and use a fixed weighted split.
605+
606+
```yaml
607+
llm:
608+
models:
609+
- name: "google/gemini-2.5-flash-lite" # no `weight:` => Thompson sampling
610+
- name: "google/gemini-2.5-flash"
611+
thompson_window_size: 50 # how many recent samples inform each model's estimate
612+
thompson_min_samples: 3 # round-robin until each model has this many samples
613+
thompson_exploration_bonus: 0.0 # >0 nudges toward less-used models
614+
```
615+
616+
The reward a model earns can be the child's absolute score or its improvement over
617+
the parent (`llm.reward_mode: "absolute" | "improvement"`, optionally cost-aware);
618+
selection is deterministic under a fixed seed.
619+
620+
## Multi-file evolution
621+
622+
Some problems don't live in one file — a kernel plus its launcher, a model plus
623+
its training loop. KaiEvolve can evolve `EVOLVE-BLOCK`s that span a directory,
624+
coordinated by a shared block ID. Mark the corresponding blocks in each file with
625+
the same ID, point `kai run` at the directory, and name the block to evolve:
626+
627+
```python
628+
# file_a.py
629+
# EVOLVE-BLOCK-START id="kernel"
630+
...
631+
# EVOLVE-BLOCK-END
632+
633+
# file_b.py
634+
# EVOLVE-BLOCK-START id="kernel"
635+
...
636+
# EVOLVE-BLOCK-END
637+
```
638+
639+
```bash
640+
kai run --directory path/to/project --block-id kernel \
641+
path/to/evaluator.py --config path/to/config.yaml --iterations 200
642+
```
643+
644+
KaiEvolve presents the matching blocks to the LLM together, applies the evolved
645+
result back across the files, and evaluates the project as a whole. The best
646+
solution is written back to the original files at the end.
647+
537648
## Examples
538649

539650
See the `examples/` directory for complete examples of using KaiEvolve on various problems:
@@ -552,7 +663,20 @@ Below is the optimal packing found by KaiEvolve after 800 iterations:
552663
#### [examples/alphaevolve/](examples/alphaevolve/)
553664
Five open mathematical problems from the AlphaEvolve paper (autocorrelation_C1, packing_circles_max_sum_of_radii, no_isosceles_triangles, happy_ending, unit_distances), each packaged as an initial program plus evaluator. Run them with the suite config tuned for these tasks, [`configs/bench_alphaevolve.yaml`](configs/bench_alphaevolve.yaml).
554665

666+
### GPU Kernels
667+
668+
#### [examples/kernelbench/](examples/kernelbench/)
669+
Evolving CUDA/GPU kernels for PyTorch operators (e.g. `23_softmax`) against a
670+
reference implementation — the platform-optimization case, where fitness is raw
671+
throughput on real hardware.
672+
673+
### Stochastic Evaluators
555674

675+
#### [examples/noisy_optimization/](examples/noisy_optimization/)
676+
A minimal benchmark for [noise-aware fitness](#what-makes-kaievolve-different): the
677+
evaluator reports a noisy estimate of each candidate's quality, so a single draw
678+
can mislead selection. Raising `evaluator.re_evaluations` above 1 averages repeats
679+
to shrink the variance — a worked example of evolving under a stochastic objective.
556680

557681
## Preparing Your Own Problems
558682

‎docs/cli/cli-demo.gif‎

15.7 KB
Loading

‎docs/viewer/viewer-demo.gif‎

181 KB
Loading

0 commit comments

Comments
 (0)