How algorithmicsuperintelligence/openevolve works
OpenEvolve is an evolutionary coding agent: a user supplies an initial program and evaluator, then receives an evolved best program and metrics. The controller coordinates repeated parent selection, prompt construction, LLM generation, candidate evaluation, and population updates. README capabilities include MAP-Elites diversity, island populations and migration, configurable model ensembles, human-in-the-loop mode, and evolution visualization. Core orchestration and model relationships are supported by the index and excerpts; links for unsampled subsystems are omitted where their callers are not shown.
Main entry points: controller.py Evolution controller · ensemble.py LLM ensemble · database.py Program database · main.js Visualization coordinator
Components 27
Entry and orchestration
- Library API
openevolve/api.py - CLI
openevolve/cli.py - Configuration
openevolve/config.py - Evolution controller
openevolve/controller.py
Evolution loop
- Program database
openevolve/database.py - Population policies
openevolve/population.py - Island selection
openevolve/selection.py - Prompt sampler
openevolve/prompt/sampler.py - Prompt templates
openevolve/prompt/templates.py - Code transformations
openevolve/utils/code_utils.py - Metric utilities
openevolve/utils/metrics_utils.py - Evolution trace
openevolve/evolution_trace.py
Generation and evaluation
- LLM ensemble
openevolve/llm/ensemble.py - LLM interface
openevolve/llm/base.py - OpenAI-compatible model
openevolve/llm/openai.py - Claude Code model
openevolve/llm/claude_code.py - Copilot CLI model
openevolve/llm/copilot_cli.py - Program evaluator
openevolve/evaluator.py - Evaluation results
openevolve/evaluation_result.py - Parallel execution
openevolve/process_parallel.py
Visualization
- Visualizer server
scripts/visualizer.py - Visualization coordinator
scripts/static/js/main.js - Evolution graph
scripts/static/js/graph.js - Program list
scripts/static/js/list.js - Program details
scripts/static/js/sidebar.js - Performance view
scripts/static/js/performance.js
Other components
- User
Connections 27
- User → CLI: starts run
README.md - User → Library API: calls library
README.md - CLI → Evolution controller: starts evolution
openevolve/cli.py - Library API → Evolution controller: runs evolution
openevolve/api.py - Evolution controller → Configuration: uses settings
openevolve/controller.py - Evolution controller → Program database: updates population
openevolve/controller.py - Evolution controller → Island selection: schedules island
openevolve/controller.py - Evolution controller → Prompt sampler: builds prompts
openevolve/controller.py - Prompt sampler → Prompt templates: uses fragments
openevolve/prompt/sampler.py - Evolution controller → LLM ensemble: requests generation
openevolve/controller.py - Evolution controller → Program evaluator: evaluates candidates
openevolve/controller.py - Evolution controller → Parallel execution: dispatches work
openevolve/controller.py - Evolution controller → Evolution trace: records evolution
openevolve/controller.py - Program database → Population policies: validates policies
openevolve/database.py - Program database → Metric utilities: calculates fitness
openevolve/database.py - Program database → Code transformations: compares code
openevolve/database.py - LLM ensemble → LLM interface: implements interface
openevolve/llm/ensemble.py - LLM ensemble → OpenAI-compatible model: creates provider
openevolve/llm/ensemble.py - LLM ensemble → Claude Code model: creates provider
openevolve/llm/ensemble.py - LLM ensemble → Copilot CLI model: creates provider
openevolve/llm/ensemble.py - Program evaluator → Evaluation results: returns results
openevolve/evaluator.py - Visualizer server → Visualization coordinator: serves interface
- Visualization coordinator → Evolution graph: renders graph
scripts/static/js/main.js - Visualization coordinator → Program list: renders programs
scripts/static/js/main.js - Evolution graph → Program details: shows selection
scripts/static/js/graph.js - Program details → Evolution graph: locates program
scripts/static/js/sidebar.js - Visualization coordinator → Performance view: opens view
scripts/static/js/performance.js