# AlphaEvolve on Google Cloud

> Client library and examples for running AlphaEvolve, a Gemini-powered evolutionary coding agent, on Google Cloud.

AlphaEvolve on Google Cloud is a Python client library and set of runnable examples from the Google-Cloud-AI organization for the managed AlphaEvolve service, which is available through Gemini Enterprise. You supply a seed program and a scoring function, and the service uses Gemini models to propose code changes that are evaluated and evolved over many generations.

## What It Is

AlphaEvolve is described as an evolutionary coding agent for general-purpose algorithm discovery and optimization. This repository contains the client-side `alpha_evolve` library plus examples. It is not an open-source reimplementation of the service: generation runs in Google Cloud through the Discovery Engine API, while the evaluator is your own code.

## How the Evolution Loop Works

The managed service combines a prompt sampler, an LLM ensemble of Gemini models, and a program database. On the client side you provide:

- A seed program, with the region to evolve marked by `EVOLVE-BLOCK-START` and `EVOLVE-BLOCK-END` comments.
- A deterministic evaluator that returns one or more scores.
- A controller loop (`run_controller_loop()`) that fetches candidates, runs the evaluator, and submits scores and insights back to the service.

Invalid candidates return sentinel scores along with insight messages, which are fed back to Gemini to guide later generations. A run is bounded by settings such as `MAX_PROGRAMS_GENERATED`, `MAX_PROGRAMS_EVALUATED`, and concurrency limits.

## Examples and Evaluation Targets

The included examples are circle packing, a travelling salesman heuristic, multi-objective signal processing, Rust and C++ adaptive sorting evaluated on Cloud Run, and LoRA hyperparameter tuning for Gemma on GKE with Ray and L4 GPUs. Evaluation can run locally in an `exec()` sandbox, in a Cloud Run function, or on a GKE and Ray GPU cluster. Runs produce the best evolved program source, per-metric scores, insights, and visualizations.

## Agent Skills

Six skills let an agentic coding assistant guide the workflow: experiment design, runner, monitor, post-experiment analysis, orchestrator, and consultant.

## Setup Path

Users need Python 3.9+, `uv`, the `gcloud` CLI, and a Google Cloud project with AlphaEvolve provisioned and a Gemini Enterprise App/Engine ID. The README states a Gemini Enterprise license is required, and that the project is not currently accepting external contributions.

## Features
- Evolutionary algorithm discovery and optimization from a seed program and scoring function
- Python client library for experiments, controller loop, and workers
- Mixture of Gemini models with configurable weights
- EVOLVE-BLOCK markers to scope code that gets rewritten
- Local, Cloud Run, or GKE + Ray evaluation
- Parallel candidate evaluation
- Multi-objective evaluation with insights fed back to the LLM
- Six agent skills for experiment design, running, monitoring, and integrating results
- Runnable examples including circle packing, TSP, signal processing, adaptive sort, and LLM fine-tuning

## Integrations
Google Cloud, Gemini Enterprise, Gemini, Discovery Engine API, Cloud Run, GKE, Ray, Terraform, Prometheus, Grafana, Antigravity

## Platforms
WEB, API, DEVELOPER_SDK, CLI

## Pricing
Open Source

## Links
- Website: https://github.com/Google-Cloud-AI/alphaevolve-on-googlecloud
- Documentation: https://docs.cloud.google.com/gemini/enterprise/docs/alphaevolve/developer-guide/overview
- Repository: https://github.com/Google-Cloud-AI/alphaevolve-on-googlecloud
- EveryDev.ai: https://www.everydev.ai/tools/alphaevolve-on-google-cloud