Skip to content

Commit 884ad12

Browse files
codelioncodelion
committed
init implementation
1 parent 7791d8f commit 884ad12

30 files changed

+4076
-147
lines changed

‎.gitignore

Lines changed: 18 additions & 146 deletions
Original file line numberDiff line numberDiff line change
@@ -1,12 +1,8 @@
1-
# Byte-compiled / optimized / DLL files
1+
# Python
22
__pycache__/
33
*.py[cod]
44
*$py.class
5-
6-
# C extensions
75
*.so
8-
9-
# Distribution / packaging
106
.Python
117
build/
128
develop-eggs/
@@ -20,155 +16,31 @@ parts/
2016
sdist/
2117
var/
2218
wheels/
23-
share/python-wheels/
2419
*.egg-info/
2520
.installed.cfg
2621
*.egg
2722
MANIFEST
2823

29-
# PyInstaller
30-
# Usually these files are written by a python script from a template
31-
# before PyInstaller builds the exe, so as to inject date/other infos into it.
32-
*.manifest
33-
*.spec
34-
35-
# Installer logs
36-
pip-log.txt
37-
pip-delete-this-directory.txt
38-
39-
# Unit test / coverage reports
40-
htmlcov/
41-
.tox/
42-
.nox/
43-
.coverage
44-
.coverage.*
45-
.cache
46-
nosetests.xml
47-
coverage.xml
48-
*.cover
49-
*.py,cover
50-
.hypothesis/
51-
.pytest_cache/
52-
cover/
53-
54-
# Translations
55-
*.mo
56-
*.pot
57-
58-
# Django stuff:
59-
*.log
60-
local_settings.py
61-
db.sqlite3
62-
db.sqlite3-journal
63-
64-
# Flask stuff:
65-
instance/
66-
.webassets-cache
67-
68-
# Scrapy stuff:
69-
.scrapy
70-
71-
# Sphinx documentation
72-
docs/_build/
73-
74-
# PyBuilder
75-
.pybuilder/
76-
target/
77-
78-
# Jupyter Notebook
79-
.ipynb_checkpoints
80-
81-
# IPython
82-
profile_default/
83-
ipython_config.py
84-
85-
# pyenv
86-
# For a library or package, you might want to ignore these files since the code is
87-
# intended to run in multiple environments; otherwise, check them in:
88-
# .python-version
89-
90-
# pipenv
91-
# According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
92-
# However, in case of collaboration, if having platform-specific dependencies or dependencies
93-
# having no cross-platform support, pipenv may install dependencies that don't work, or not
94-
# install all needed dependencies.
95-
#Pipfile.lock
96-
97-
# UV
98-
# Similar to Pipfile.lock, it is generally recommended to include uv.lock in version control.
99-
# This is especially recommended for binary packages to ensure reproducibility, and is more
100-
# commonly ignored for libraries.
101-
#uv.lock
102-
103-
# poetry
104-
# Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
105-
# This is especially recommended for binary packages to ensure reproducibility, and is more
106-
# commonly ignored for libraries.
107-
# https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
108-
#poetry.lock
109-
110-
# pdm
111-
# Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
112-
#pdm.lock
113-
# pdm stores project-wide configurations in .pdm.toml, but it is recommended to not include it
114-
# in version control.
115-
# https://pdm.fming.dev/latest/usage/project/#working-with-version-control
116-
.pdm.toml
117-
.pdm-python
118-
.pdm-build/
119-
120-
# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
121-
__pypackages__/
122-
123-
# Celery stuff
124-
celerybeat-schedule
125-
celerybeat.pid
126-
127-
# SageMath parsed files
128-
*.sage.py
129-
130-
# Environments
131-
.env
132-
.venv
133-
env/
24+
# Virtual environments
13425
venv/
26+
env/
13527
ENV/
136-
env.bak/
137-
venv.bak/
138-
139-
# Spyder project settings
140-
.spyderproject
141-
.spyproject
14228

143-
# Rope project settings
144-
.ropeproject
29+
# IDE
30+
.idea/
31+
.vscode/
32+
*.swp
33+
*.swo
14534

146-
# mkdocs documentation
147-
/site
148-
149-
# mypy
150-
.mypy_cache/
151-
.dmypy.json
152-
dmypy.json
153-
154-
# Pyre type checker
155-
.pyre/
156-
157-
# pytype static type analyzer
158-
.pytype/
159-
160-
# Cython debug symbols
161-
cython_debug/
162-
163-
# PyCharm
164-
# JetBrains specific template is maintained in a separate JetBrains.gitignore that can
165-
# be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
166-
# and can be added to the global gitignore or merged into this file. For a more nuclear
167-
# option (not recommended) you can uncomment the following to ignore the entire idea folder.
168-
#.idea/
35+
# Output files
36+
examples/*/output/
37+
openevolve_output/
38+
*.log
16939

170-
# Ruff stuff:
171-
.ruff_cache/
40+
# Test cache
41+
.pytest_cache/
42+
.coverage
43+
htmlcov/
17244

173-
# PyPI configuration file
174-
.pypirc
45+
# Misc
46+
.DS_Store

‎CONTRIBUTING.md

Lines changed: 69 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,69 @@
1+
# Contributing to OpenEvolve
2+
3+
Thank you for your interest in contributing to OpenEvolve! This document provides guidelines and instructions for contributing to the project.
4+
5+
## Getting Started
6+
7+
1. Fork the repository
8+
2. Clone your fork: `git clone https://github.com/codelion/openevolve.git`
9+
3. Install the package in development mode: `pip install -e .`
10+
4. Run the tests to ensure everything is working: `python -m unittest discover tests`
11+
12+
## Development Environment
13+
14+
We recommend using a virtual environment for development:
15+
16+
```bash
17+
python -m venv env
18+
source env/bin/activate # On Windows: env\Scripts\activate
19+
pip install -e ".[dev]"
20+
```
21+
22+
## Code Style
23+
24+
We follow the [Black](https://black.readthedocs.io/) code style. Please format your code before submitting a pull request:
25+
26+
```bash
27+
black openevolve tests examples
28+
```
29+
30+
## Pull Request Process
31+
32+
1. Create a new branch for your feature or bugfix: `git checkout -b feature/your-feature-name`
33+
2. Make your changes
34+
3. Add tests for your changes
35+
4. Run the tests to make sure everything passes: `python -m unittest discover tests`
36+
5. Commit your changes: `git commit -m "Add your descriptive commit message"`
37+
6. Push to your fork: `git push origin feature/your-feature-name`
38+
7. Submit a pull request to the main repository
39+
40+
## Adding Examples
41+
42+
We encourage adding new examples to showcase OpenEvolve's capabilities. To add a new example:
43+
44+
1. Create a new directory in the `examples` folder
45+
2. Include all necessary files (initial program, evaluation code, etc.)
46+
3. Add a README.md explaining the example
47+
4. Make sure the example can be run with minimal setup
48+
49+
## Reporting Issues
50+
51+
When reporting issues, please include:
52+
53+
1. A clear description of the issue
54+
2. Steps to reproduce
55+
3. Expected behavior
56+
4. Actual behavior
57+
5. Environment details (OS, Python version, etc.)
58+
59+
## Feature Requests
60+
61+
Feature requests are welcome. Please provide:
62+
63+
1. A clear description of the feature
64+
2. The motivation for adding this feature
65+
3. Possible implementation ideas (if any)
66+
67+
## Code of Conduct
68+
69+
Please be respectful and considerate of others when contributing to the project. We aim to create a welcoming and inclusive environment for all contributors.

‎README.md

Lines changed: 74 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1 +1,74 @@
1-
# openevolve
1+
# OpenEvolve
2+
3+
An open-source implementation of the AlphaEvolve system described in the Google DeepMind paper "AlphaEvolve: A coding agent for scientific and algorithmic discovery" (2025).
4+
5+
## Overview
6+
7+
OpenEvolve is an evolutionary coding agent that uses Large Language Models to optimize code through an iterative process. It orchestrates a pipeline of LLM-based code generation, evaluation, and selection to continuously improve programs for a variety of tasks.
8+
9+
Key features:
10+
- Evolution of entire code files, not just single functions
11+
- Support for multiple programming languages
12+
- Supports OpenAI-compatible APIs for any LLM
13+
- Multi-objective optimization
14+
- Flexible prompt engineering
15+
- Distributed evaluation
16+
17+
## How It Works
18+
19+
OpenEvolve follows an evolutionary approach with the following components:
20+
21+
1. **Prompt Sampler**: Creates context-rich prompts containing past programs, their scores, and problem descriptions
22+
2. **LLM Ensemble**: Generates code modifications via an ensemble of language models
23+
3. **Evaluator Pool**: Tests generated programs and assigns scores
24+
4. **Program Database**: Stores programs and their evaluation metrics, guiding future evolution
25+
26+
## Getting Started
27+
28+
### Installation
29+
30+
```bash
31+
git clone https://github.com/codelion/openevolve.git
32+
cd openevolve
33+
pip install -e .
34+
```
35+
36+
### Quick Start
37+
38+
```python
39+
from openevolve import OpenEvolve
40+
41+
# Initialize the system
42+
evolve = OpenEvolve(
43+
initial_program="path/to/initial_program.py",
44+
evaluation_function="path/to/evaluator.py",
45+
config="path/to/config.yaml"
46+
)
47+
48+
# Run the evolution
49+
best_program = evolve.run(iterations=1000)
50+
print(f"Best program found: {best_program.path}")
51+
print(f"Score: {best_program.score}")
52+
```
53+
54+
## Examples
55+
56+
See the `examples/` directory for complete examples of using OpenEvolve on various problems:
57+
- Matrix multiplication optimization
58+
- Packing problems
59+
- Algorithmic discovery
60+
- Scheduling optimization
61+
62+
## Citation
63+
64+
If you use OpenEvolve in your research, please cite:
65+
66+
```
67+
@software{openevolve,
68+
title = {OpenEvolve: Open-source implementation of AlphaEvolve},
69+
author = {Asankhaya Sharma},
70+
year = {2025},
71+
publisher = {GitHub},
72+
url = {https://github.com/codelion/openevolve}
73+
}
74+
```

0 commit comments

Comments
 (0)