# algorithmicsuperintelligence/openevolve architecture

> Architecture diagram of the GitHub repository algorithmicsuperintelligence/openevolve, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/algorithmicsuperintelligence/openevolve
- Repository: https://github.com/algorithmicsuperintelligence/openevolve

## Overview

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: [`openevolve/controller.py`](https://github.com/algorithmicsuperintelligence/openevolve/blob/main/openevolve/controller.py) (Evolution controller), [`openevolve/llm/ensemble.py`](https://github.com/algorithmicsuperintelligence/openevolve/blob/main/openevolve/llm/ensemble.py) (LLM ensemble), [`openevolve/database.py`](https://github.com/algorithmicsuperintelligence/openevolve/blob/main/openevolve/database.py) (Program database), [`scripts/static/js/main.js`](https://github.com/algorithmicsuperintelligence/openevolve/blob/main/scripts/static/js/main.js) (Visualization coordinator)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Entry and orchestration"]
  node_api["Library API<br/>[api.py]"]
  node_cli["CLI<br/>[cli.py]"]
  node_config["Configuration<br/>[config.py]"]
  node_controller["Evolution controller<br/>[controller.py]"]
end

subgraph group_evolve["Evolution loop"]
  node_database[("Program database<br/>[database.py]")]
  node_population["Population policies<br/>[population.py]"]
  node_selection["Island selection<br/>[selection.py]"]
  node_prompt["Prompt sampler<br/>[sampler.py]"]
  node_templates["Prompt templates<br/>[templates.py]"]
  node_codeutils["Code transformations<br/>[code_utils.py]"]
  node_metrics["Metric utilities<br/>[metrics_utils.py]"]
  node_trace["Evolution trace<br/>[evolution_trace.py]"]
end

subgraph group_models["Generation and evaluation"]
  node_ensemble["LLM ensemble<br/>[ensemble.py]"]
  node_llmbase["LLM interface<br/>[base.py]"]
  node_openai["OpenAI-compatible model<br/>[openai.py]"]
  node_claude["Claude Code model<br/>[claude_code.py]"]
  node_copilot["Copilot CLI model<br/>[copilot_cli.py]"]
  node_evaluator["Program evaluator<br/>[evaluator.py]"]
  node_result["Evaluation results"]
  node_parallel["Parallel execution"]
end

subgraph group_inspect["Visualization"]
  node_visualizer["Visualizer server<br/>[visualizer.py]"]
  node_visualmain["Visualization coordinator<br/>[main.js]"]
  node_graph["Evolution graph<br/>[graph.js]"]
  node_list["Program list<br/>[list.js]"]
  node_sidebar["Program details<br/>[sidebar.js]"]
  node_performance["Performance view<br/>[performance.js]"]
end

node_user(("User"))

node_user -->|"starts run"| node_cli
node_user -->|"calls library"| node_api
node_cli -->|"starts evolution"| node_controller
node_api -->|"runs evolution"| node_controller
node_controller -->|"uses settings"| node_config
node_controller -->|"updates population"| node_database
node_controller -->|"schedules island"| node_selection
node_controller -->|"builds prompts"| node_prompt
node_prompt -->|"uses fragments"| node_templates
node_controller -->|"requests generation"| node_ensemble
node_controller -->|"evaluates candidates"| node_evaluator
node_controller -->|"dispatches work"| node_parallel
node_controller -->|"records evolution"| node_trace
node_database -->|"validates policies"| node_population
node_database -->|"calculates fitness"| node_metrics
node_database -->|"compares code"| node_codeutils
node_ensemble -->|"implements interface"| node_llmbase
node_ensemble -->|"creates provider"| node_openai
node_ensemble -->|"creates provider"| node_claude
node_ensemble -->|"creates provider"| node_copilot
node_evaluator -->|"returns results"| node_result
node_visualizer -.->|"serves interface"| node_visualmain
node_visualmain -->|"renders graph"| node_graph
node_visualmain -->|"renders programs"| node_list
node_graph -->|"shows selection"| node_sidebar
node_sidebar -->|"locates program"| node_graph
node_visualmain -.->|"opens view"| node_performance

click node_api "https://github.com/algorithmicsuperintelligence/openevolve/blob/main/openevolve/api.py"
click node_cli "https://github.com/algorithmicsuperintelligence/openevolve/blob/main/openevolve/cli.py"
click node_config "https://github.com/algorithmicsuperintelligence/openevolve/blob/main/openevolve/config.py"
click node_controller "https://github.com/algorithmicsuperintelligence/openevolve/blob/main/openevolve/controller.py"
click node_database "https://github.com/algorithmicsuperintelligence/openevolve/blob/main/openevolve/database.py"
click node_population "https://github.com/algorithmicsuperintelligence/openevolve/blob/main/openevolve/population.py"
click node_selection "https://github.com/algorithmicsuperintelligence/openevolve/blob/main/openevolve/selection.py"
click node_prompt "https://github.com/algorithmicsuperintelligence/openevolve/blob/main/openevolve/prompt/sampler.py"
click node_templates "https://github.com/algorithmicsuperintelligence/openevolve/blob/main/openevolve/prompt/templates.py"
click node_codeutils "https://github.com/algorithmicsuperintelligence/openevolve/blob/main/openevolve/utils/code_utils.py"
click node_metrics "https://github.com/algorithmicsuperintelligence/openevolve/blob/main/openevolve/utils/metrics_utils.py"
click node_ensemble "https://github.com/algorithmicsuperintelligence/openevolve/blob/main/openevolve/llm/ensemble.py"
click node_llmbase "https://github.com/algorithmicsuperintelligence/openevolve/blob/main/openevolve/llm/base.py"
click node_openai "https://github.com/algorithmicsuperintelligence/openevolve/blob/main/openevolve/llm/openai.py"
click node_claude "https://github.com/algorithmicsuperintelligence/openevolve/blob/main/openevolve/llm/claude_code.py"
click node_copilot "https://github.com/algorithmicsuperintelligence/openevolve/blob/main/openevolve/llm/copilot_cli.py"
click node_evaluator "https://github.com/algorithmicsuperintelligence/openevolve/blob/main/openevolve/evaluator.py"
click node_result "https://github.com/algorithmicsuperintelligence/openevolve/blob/main/openevolve/evaluation_result.py"
click node_parallel "https://github.com/algorithmicsuperintelligence/openevolve/blob/main/openevolve/process_parallel.py"
click node_trace "https://github.com/algorithmicsuperintelligence/openevolve/blob/main/openevolve/evolution_trace.py"
click node_visualizer "https://github.com/algorithmicsuperintelligence/openevolve/blob/main/scripts/visualizer.py"
click node_visualmain "https://github.com/algorithmicsuperintelligence/openevolve/blob/main/scripts/static/js/main.js"
click node_graph "https://github.com/algorithmicsuperintelligence/openevolve/blob/main/scripts/static/js/graph.js"
click node_list "https://github.com/algorithmicsuperintelligence/openevolve/blob/main/scripts/static/js/list.js"
click node_sidebar "https://github.com/algorithmicsuperintelligence/openevolve/blob/main/scripts/static/js/sidebar.js"
click node_performance "https://github.com/algorithmicsuperintelligence/openevolve/blob/main/scripts/static/js/performance.js"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_api,node_cli,node_config,node_controller,node_user toneBlue
class node_database,node_population,node_selection,node_prompt,node_templates,node_codeutils,node_metrics,node_trace toneAmber
class node_ensemble,node_llmbase,node_openai,node_claude,node_copilot,node_evaluator,node_result,node_parallel toneMint
class node_visualizer,node_visualmain,node_graph,node_list,node_sidebar,node_performance toneRose
```

## Components

### Entry and orchestration

- [Library API](https://github.com/algorithmicsuperintelligence/openevolve/blob/main/openevolve/api.py): `openevolve/api.py`
- [CLI](https://github.com/algorithmicsuperintelligence/openevolve/blob/main/openevolve/cli.py): `openevolve/cli.py`
- [Configuration](https://github.com/algorithmicsuperintelligence/openevolve/blob/main/openevolve/config.py): `openevolve/config.py`
- [Evolution controller](https://github.com/algorithmicsuperintelligence/openevolve/blob/main/openevolve/controller.py): `openevolve/controller.py`

### Evolution loop

- [Program database](https://github.com/algorithmicsuperintelligence/openevolve/blob/main/openevolve/database.py): `openevolve/database.py`
- [Population policies](https://github.com/algorithmicsuperintelligence/openevolve/blob/main/openevolve/population.py): `openevolve/population.py`
- [Island selection](https://github.com/algorithmicsuperintelligence/openevolve/blob/main/openevolve/selection.py): `openevolve/selection.py`
- [Prompt sampler](https://github.com/algorithmicsuperintelligence/openevolve/blob/main/openevolve/prompt/sampler.py): `openevolve/prompt/sampler.py`
- [Prompt templates](https://github.com/algorithmicsuperintelligence/openevolve/blob/main/openevolve/prompt/templates.py): `openevolve/prompt/templates.py`
- [Code transformations](https://github.com/algorithmicsuperintelligence/openevolve/blob/main/openevolve/utils/code_utils.py): `openevolve/utils/code_utils.py`
- [Metric utilities](https://github.com/algorithmicsuperintelligence/openevolve/blob/main/openevolve/utils/metrics_utils.py): `openevolve/utils/metrics_utils.py`
- [Evolution trace](https://github.com/algorithmicsuperintelligence/openevolve/blob/main/openevolve/evolution_trace.py): `openevolve/evolution_trace.py`

### Generation and evaluation

- [LLM ensemble](https://github.com/algorithmicsuperintelligence/openevolve/blob/main/openevolve/llm/ensemble.py): `openevolve/llm/ensemble.py`
- [LLM interface](https://github.com/algorithmicsuperintelligence/openevolve/blob/main/openevolve/llm/base.py): `openevolve/llm/base.py`
- [OpenAI-compatible model](https://github.com/algorithmicsuperintelligence/openevolve/blob/main/openevolve/llm/openai.py): `openevolve/llm/openai.py`
- [Claude Code model](https://github.com/algorithmicsuperintelligence/openevolve/blob/main/openevolve/llm/claude_code.py): `openevolve/llm/claude_code.py`
- [Copilot CLI model](https://github.com/algorithmicsuperintelligence/openevolve/blob/main/openevolve/llm/copilot_cli.py): `openevolve/llm/copilot_cli.py`
- [Program evaluator](https://github.com/algorithmicsuperintelligence/openevolve/blob/main/openevolve/evaluator.py): `openevolve/evaluator.py`
- [Evaluation results](https://github.com/algorithmicsuperintelligence/openevolve/blob/main/openevolve/evaluation_result.py): `openevolve/evaluation_result.py`
- [Parallel execution](https://github.com/algorithmicsuperintelligence/openevolve/blob/main/openevolve/process_parallel.py): `openevolve/process_parallel.py`

### Visualization

- [Visualizer server](https://github.com/algorithmicsuperintelligence/openevolve/blob/main/scripts/visualizer.py): `scripts/visualizer.py`
- [Visualization coordinator](https://github.com/algorithmicsuperintelligence/openevolve/blob/main/scripts/static/js/main.js): `scripts/static/js/main.js`
- [Evolution graph](https://github.com/algorithmicsuperintelligence/openevolve/blob/main/scripts/static/js/graph.js): `scripts/static/js/graph.js`
- [Program list](https://github.com/algorithmicsuperintelligence/openevolve/blob/main/scripts/static/js/list.js): `scripts/static/js/list.js`
- [Program details](https://github.com/algorithmicsuperintelligence/openevolve/blob/main/scripts/static/js/sidebar.js): `scripts/static/js/sidebar.js`
- [Performance view](https://github.com/algorithmicsuperintelligence/openevolve/blob/main/scripts/static/js/performance.js): `scripts/static/js/performance.js`

### Other components

- **User**

## Connections

- User → CLI: starts run (evidence: `README.md`)
- User → Library API: calls library (evidence: `README.md`)
- CLI → Evolution controller: starts evolution (evidence: `openevolve/cli.py`)
- Library API → Evolution controller: runs evolution (evidence: `openevolve/api.py`)
- Evolution controller → Configuration: uses settings (evidence: `openevolve/controller.py`)
- Evolution controller → Program database: updates population (evidence: `openevolve/controller.py`)
- Evolution controller → Island selection: schedules island (evidence: `openevolve/controller.py`)
- Evolution controller → Prompt sampler: builds prompts (evidence: `openevolve/controller.py`)
- Prompt sampler → Prompt templates: uses fragments (evidence: `openevolve/prompt/sampler.py`)
- Evolution controller → LLM ensemble: requests generation (evidence: `openevolve/controller.py`)
- Evolution controller → Program evaluator: evaluates candidates (evidence: `openevolve/controller.py`)
- Evolution controller → Parallel execution: dispatches work (evidence: `openevolve/controller.py`)
- Evolution controller → Evolution trace: records evolution (evidence: `openevolve/controller.py`)
- Program database → Population policies: validates policies (evidence: `openevolve/database.py`)
- Program database → Metric utilities: calculates fitness (evidence: `openevolve/database.py`)
- Program database → Code transformations: compares code (evidence: `openevolve/database.py`)
- LLM ensemble → LLM interface: implements interface (evidence: `openevolve/llm/ensemble.py`)
- LLM ensemble → OpenAI-compatible model: creates provider (evidence: `openevolve/llm/ensemble.py`)
- LLM ensemble → Claude Code model: creates provider (evidence: `openevolve/llm/ensemble.py`)
- LLM ensemble → Copilot CLI model: creates provider (evidence: `openevolve/llm/ensemble.py`)
- Program evaluator → Evaluation results: returns results (evidence: `openevolve/evaluator.py`)
- Visualizer server → Visualization coordinator: serves interface
- Visualization coordinator → Evolution graph: renders graph (evidence: `scripts/static/js/main.js`)
- Visualization coordinator → Program list: renders programs (evidence: `scripts/static/js/main.js`)
- Evolution graph → Program details: shows selection (evidence: `scripts/static/js/graph.js`)
- Program details → Evolution graph: locates program (evidence: `scripts/static/js/sidebar.js`)
- Visualization coordinator → Performance view: opens view (evidence: `scripts/static/js/performance.js`)